Yahoo!広告検索広告コンバージョン API 後付けコンバージョン計測・オフラインCV連携の実践ガイド

Yahoo検索広告を運用するなかで、「コンバージョン数が実態と合わない」と感じたことはないでしょうか。

広告経由で問い合わせがあり、後日電話で成約したケース。ECサイトで広告をクリックしたユーザーが、店舗で購入したケース。あるいは、Cookieの有効期限切れやブラウザ設定により、本来計測されるべきコンバージョンが欠落しているケース。

従来のJavaScriptタグによる計測は、ブラウザ上でコンバージョンが発生した瞬間を捉える仕組みです。そのため、オフラインで発生したコンバージョンや、時間差で確定するコンバージョンは原理的に計測できません。また、プライバシー規制の強化やブラウザのトラッキング制限により、タグ計測の精度そのものが低下傾向にあります。

こうした課題を解決する手段として注目されているのが、Yahoo検索広告の「コンバージョンAPI」です。サーバーサイドからコンバージョンデータを直接送信することで、タグ計測では捉えられなかったコンバージョンを補完できます。

本記事では、TROCCOの転送先カスタムコネクタ機能を活用し、DWH（BigQueryやSnowflakeなど）に蓄積されたコンバージョンデータをYahoo検索広告コンバージョンAPIを利用し媒体へ連携する手順を、具体的に解説します。

カスタムコネクタとは？

ETLツールでは一般的に、2つの異なるインターフェース間の接続を可能にする実装のことを、コネクタと呼びます。

TROCCOの転送先カスタムコネクタ機能は、DWHなどのデータソースから抽出したデータを、任意のREST APIを利用しデータ送信できる機能です。

Yahoo検索広告コンバージョンAPIのエンドポイントとリクエスト形式を設定することで、GUIベースでの連携が実現します。

TROCCOのカスタムコネクタの特徴

OAuth認証（認可コード・クライアントクレデンシャルズ）やAPIキーの設定に対応
ページネーションや任意のクエリパラメータに対応
通常のコネクタと同様にスケジュールによる定期実行が可能

詳細は下記の記事をご参照ください。
Connector Builder（コネクタビルダー）とは

※ カスタムコネクタはTROCCOのAdvancedプラン以上のプランでご利用いただける機能です。
※「Connector Builder」は機能名称を「カスタムコネクタ」に変更しました。現在は「カスタムコネクタ」として提供しています。

全体構成・データ連携イメージ

本事例におけるデータの流れは以下のとおりです。

DWH（BigQuery / Snowflake 等） → TROCCO（転送先カスタムコネクタ） → Yahoo検索広告コンバージョンAPI

DWHには、自社で収集・管理しているコンバージョンデータが格納されています。受注管理システムやCRM、POSデータなど、さまざまなソースから集約されたデータが対象となります。

コンバージョンと広告クリックの紐づけにはyclidを使用します。yclidはYahoo検索広告のクリック識別子で、ユーザーが広告をクリックした際にURLパラメータとして付与されます。このyclidをコンバージョンデータとともにAPIに送信することで、どの広告クリックがコンバージョンにつながったかを特定できます。

なお、本連携はリアルタイム送信ではなく、バッチ処理による定期連携を前提としています。たとえば「毎日深夜に前日分のコンバージョンを送信する」といった運用が一般的です。

この方法のメリットは3点あります。

DWHを正としたデータ起点で連携できる
GUIベースで設定でき、コード実装が不要
バッチ処理による安定したデータ送信が可能

API実装のためにエンジニアリソースを確保する必要がなく、広告運用担当者やデータ担当者が主体となって導入を進められます。

【実践編】Yahoo検索広告コンバージョン API連携カスタムコネクタを作成する手順

Yahoo広告側の準備

まず、Yahoo広告側で必要な設定と認証情報の取得を行います。

アプリケーション登録とClient IDの取得

Yahoo検索広告コンバージョンAPIを利用するには、Yahoo! デベロッパーネットワークでアプリケーションを登録し、Client ID（Application ID）を取得する必要があります。

手順は以下のとおりです。

Yahoo! デベロッパーネットワーク（https://developer.yahoo.co.jp/start/）にアクセス
Yahoo! JAPAN IDでログイン
1. ※ Yahoo広告の管理画面へのログインはビジネスIDですが、デベロッパーネットワークでのアプリ登録はYahoo! JAPAN IDで行います。
「アプリケーションの管理」から新規アプリケーションを登録
「ID連携を利用しない」を選択しても、コンバージョンAPIは使用可能です
発行されたApplication ID（Client ID）を控える

Client IDは認証情報として扱われるため、平文でのファイル保存や、チャットツールでの共有は避けてください。TROCCOの接続設定に登録することで、安全に管理できます。

自動タグ設定の有効化

yclidを取得するには、Yahoo広告アカウントの「自動タグ設定」を有効にする必要があります。

広告管理ツール画面上部のアカウント名をクリックし、設定を変更する広告アカウントを選択
サイドメニューの「アカウント設定」をクリック
「編集」ボタンを押し、自動タグ設定の「設定する」にチェックを入れ保存

この設定により、広告クリック時のURLにyclidパラメータが自動で付与されるようになります。

詳細は公式ヘルプを参照してください。
https://ads-help.yahoo-net.jp/s/article/H000054776?language=ja

コンバージョン測定の設定

次に、Yahoo広告の管理画面でコンバージョン測定の設定を行います。

Yahoo広告の管理画面にログイン
「ツール」→「コンバージョン測定」を選択
「コンバージョン設定を作成」をクリック
コンバージョン名、コンバージョン種別、計測期間などを設定
設定を保存すると、コンバージョン測定タグが発行される

<script async> ytag({ "type": "yss_conversion", "config": { "yahoo_conversion_id": "XXXXXXXXXX", "yahoo_conversion_label": "YOUR_CONVERSION_LABEL", "yahoo_conversion_value": "1" } }); </script>

yahoo_conversion_id と yahoo_conversion_label の値はAPIリクエストで必要となるため、控えておいてください。

詳細は公式ヘルプを参照してください。
https://ads-help.yahoo-net.jp/s/article/H000046007?language=ja

コンバージョンタグのテスト用サイトへの設置

コンバージョン測定の設定を保存すると、コンバージョンタグ（JavaScriptコード）が発行されます。このタグをテスト用サイトのコンバージョン完了ページ（サンクスページなど）に設置してください。

【事前準備】

コンバージョンタグを設置する前に、サイトジェネラルタグとコンバージョン測定補完機能タグをサイト全体に設置しておく必要があります。これらのタグがない状態ではコンバージョン計測が正常に動作しません。

【HTML直接設置の手順】

コンバージョン測定の設定画面で「タグを表示」をクリック
表示されたJavaScriptコードをコピー
コンバージョン完了ページのHTMLの</body>タグ直前に貼り付け
ページを公開し、タグが正しく動作することを確認

このタグ設置は、コンバージョンAPIによる送信とは別に、従来のタグ計測が正常に機能するかを確認するためのステップです。API連携の検証においても、タグ計測との比較や、コンバージョン設定自体が正しく機能しているかの確認に役立ちます。

【Google Tag Managerで設置の手順】

上記タグは、Google Tag Manager で設置することも可能です。その場合の手順は以下のとおりです。

GTMにログインし、「タグ」→「新規」を選択
タグタイプで「カスタムHTML」を選択し、Yahoo広告管理画面で発行されたコンバージョンタグを貼り付け
トリガーでコンバージョンを計測したいページ(サンクスページなど)を指定
プレビューで動作確認後、公開

注意事項 サイトジェネラルタグが読み込まれた後にコンバージョンタグが発火するよう、タグの順序付けを設定してください。

yclidの値の取得方法について

yclidはYahoo検索広告における「クリック識別子」です。ユーザーが広告をクリックした際に、ランディングページのURLパラメータとして付与されます。

例：https://example.com/lp?yclid=YSS.1234567890.Ab12CdEfGhIJ345kLm_N_oPq

コンバージョンAPIでは、このyclidを送信することで、コンバージョンと広告クリックを紐づけます。

なお、yclidの代わりに sa_p、sa_t、sa_ra の3つのパラメータを組み合わせて送信することも可能です。これらも広告クリック時にURLに付与されるパラメータで、3つすべてを指定することでyclidと同様にユーザーを識別できます。

yclidの取得手順

yclidを取得するには、実際に広告を出稿し、広告をクリックする必要があります。

Yahoo検索広告で広告を出稿する（テスト用でも可）
Yahoo検索で該当のキーワードを検索
表示された広告をクリックする
ランディングページのURLに付与されたyclidを確認する

自社のWebサイトでは、yclidをセッション情報やCookie、データベースに保存しておき、コンバージョン発生時に紐づけられるようにしておく必要があります。

注意：yclidはプログラムで生成できません

yclidは、Yahoo広告のシステムが広告クリック時に発行する値であり、ダミーデータやプログラムによる生成はできません。

これは事前検証の段階でつまずきやすいポイントです。開発環境やステージング環境でテストを行う場合でも、実際の広告クリックによって取得したyclidを使用する必要があります。

本番環境での運用を見据えて、以下の点を事前に準備しておくことを推奨します。

テスト用の広告キャンペーンを用意する
取得したyclidをテストデータに組み込む
少量データでの検証を先に行う

TROCCO側の設定

Yahoo広告側の準備が完了したら、TROCCOで転送先カスタムコネクタを作成します。

公式ドキュメントを参照しながらYahoo検索広告コンバージョンAPIの設定を行います。

Yahoo!広告（検索広告）コンバージョンAPI 公式ドキュメント
https://github.com/yahoojp-marketing/search-ads-conversion-api-documents

Conversion API
https://github.com/yahoojp-marketing/search-ads-conversion-api-documents/blob/main/docs_ja/conversion-api.md

転送先カスタムコネクタの作成

TROCCOにログイン
「カスタムコネクタ」→ 「新規追加」をクリック
「転送先で作成する」を選択

APIドキュメントを確認しながら、各種設定をコネクタ情報・認証情報の設定を行います。

基本情報

名前	任意の識別名（例：Yahoo検索広告 CAPI）
ベースURL	`https://search-ads-cv.yahooapis.jp`

認証情報

認証種別を「APIキー」を選択し、以下を設定します。

認証ヘッダ名	User-Agent
認証スキーム	Yahoo AppID:

エンドポイント設定

「エンドポイントを追加」ボタンを押して必要なAPIエンドポイントを追加します。

名前	任意の識別名（例：コンバージョンAPI）
操作種別	作成API ※ 転送データを新しいレコードとして登録する場合はこちらを選択してください。
リクエストタイプ	単一リクエスト ※ 1レコードごとに1回のAPIリクエストを送信する場合はこちらを選択してください。
パス	/v1/
HTTPメソッド	POST
リクエストテンプレート	Liquid形式でリクエストボディを定義

リクエストテンプレートでは、転送元データのカラムをAPIパラメータにマッピングします。Yahoo検索広告コンバージョンAPIでは、以下のパラメータが必須です。

yclid（または sa_p, sa_t, sa_ra の組み合わせ）	必須	実際の広告クリックから取得した値が必須。ダミー値では計測されません。
yahoo_conversion_id	必須	広告管理画面で発行された正式な値が必須。
yahoo_conversion_label	必須	広告管理画面で発行された正式な値が必須。
yahoo_conversion_value	任意	整数で指定
event_time（10桁または13桁のUNIX時間）	必須	テストで使用するyclidの広告クリック発生日時から、コンバージョン測定の計測期間内である必要があります。最近取得したyclidを使用する場合は、現在時刻のUNIX時間で問題ありません。
url（コンバージョン発生ページのURL）	必須	テスト時は任意のURLで問題ありません（例：`https://example.com/test`）。
user_agent	必須	テスト時は任意のブラウザUA文字列で問題ありません。
ip	必須	テスト時は任意のIPアドレスで問題ありません（例：`192.168.0.1`）。

リクエストテンプレートの記載例

{
  "yclid": "{{ row.yclid }}",
  "yahoo_conversion_id": "XXXXXXXXXX",
  "yahoo_conversion_label": "YOUR_CONVERSION_LABEL",
  "event_time": {{ row.event_time }},
  "url": "{{ row.url }}",
  "ip": "{{ row.ip }}",
  "user_agent": "{{ row.user_agent }}"
}

転送元テーブルのカラム名に応じて、適宜調整してください。

リクエストボディの展開テスト

テンプレートプレビュー機能を利用すると、サンプルデータを用いて、Liquid形式で記載したリクエストテンプレートが実際にどのように展開されるのか、確認することができます。

サンプルデータに値を設定し、「プレビュー生成」ボタンをクリックし、プレビュー結果を表示し、想定どおりのリクエストボディになっているか確認します。

HTTPヘッダ設定

ヘッダ名	表示名	デフォルト値	編集可能	必須
Content-Type	Content-Type	application/json		✓

その他の詳細についてはヘルプドキュメントを参照してください。
https://documents.trocco.io/docs/create-destination-custom-connector

ここまで設定できたら、一度エンドポイントとカスタムコネクタを保存しておきます。

接続設定の作成と接続確認

カスタムコネクタの詳細画面右上の編集ボタンをクリックし、エンドポイントの編集アイコンをクリックして再度編集画面を開きます。

「接続情報を追加」ボタンをクリックすると新規タブで接続情報の作成画面が表示される
カスタムコネクタで先程作成したカスタムコネクタを選択
任意の名前を入力し、「APIキーや認証トークン」に控えておいた「Client ID」を入力
「保存」をクリックし接続情報を保存

これにより、認証情報が安全に管理されます。

先程作成した接続情報を利用して接続確認を行います。
この接続確認は、実際にcurlでAPIリクエストを送信するため、データが登録されてしまいます。データ登録されても問題ない場合のみ、実行するようにします。

「接続情報を読み込む」をクリックし作成した接続情報をプルダウンで選択
接続確認に利用するサンプルデータにサンプルデータを入力
「接続を確認」ボタンをクリック

転送設定の作成と実行

転送設定を作成します。

STEP1: 転送元・転送先の設定

「データ転送」→「転送設定」→「新規転送設定作成」を選択
転送元：BigQuery（またはSnowflake等）を選択
転送先：カスタムコネクタを選択
転送元のSQLクエリで、必要なカラムを抽出

SELECT
  yclid,
  event_time,
  url,
  user_agent,
  ip
FROM
  `your_project.your_dataset.conversions`
WHERE
  -- yclidが存在するレコードのみ抽出
  yclid IS NOT NULL
  AND yclid != ''
  -- 直近30日以内のコンバージョンを対象（計測期間に応じて調整）
  AND event_time >= UNIX_MILLIS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
  -- 必須パラメータが揃っているレコードのみ
  AND user_agent IS NOT NULL
  AND ip IS NOT NULL
  AND url IS NOT NULL
ORDER BY
  event_time DESC

転送先カスタムコネクタの設定で作成したカスタムコネクタ、接続情報、作成エンドポイントを選択

転送元のSQLでは、yclidが存在するレコードのみを抽出する、event_timeをUNIX時間に変換する、といった加工を行います。また、user_agentやipなど、APIで必須となるパラメータも転送元データに含まれている必要があります。

転送元や転送先の設定項目についての詳細は、ヘルプドキュメントを参照して設定してください。

転送元 – Google BigQuery
転送先 – カスタムコネクタ

STEP2: データプレビュー・詳細設定

スキーマ・データのプレビュー画面にLiquidテンプレートのプレビューが表示されるので問題ないか確認します。

問題がなければ、「確認画面へ」をクリックし、STEP3で「保存して適用」をクリックして転送設定を保存します。

これで転送設定の作成は完了です。

ジョブを実行

それでは、作成した転送設定を利用し実際にデータを転送してみましょう。

作成した転送設定の画面の右上にある「実行」ボタンを押します。

ジョブの実行時に指定できる項目がありますが、今回は特に変更せず、そのまま実行をクリックしてください。

ジョブの実行ログ画面に切り替わり転送が開始されます。ジョブが正常終了するとステータスが「SUCCESS」に変更になります。

Yahoo広告へコンバージョンデータの送信が完了しました！

いかがでしょうか？

最小限の設定でAPI連携ができるカスタムコネクタの作成やデータの転送までできることがおわかりいただけたかと思います。
また、スケジュール実行を設定することで、日次・週次での定期連携も可能です。

実装時の注意点・運用上のポイント

yclidが取得できない主な原因

自動タグ設定が無効になっている
広告がまだ配信されていない、または配信停止中
ブラウザの拡張機能やセキュリティソフトがURLパラメータを除去している
ランディングページ側でyclidをキャプチャする仕組みが実装されていない

event_timeの制約

コンバージョンAPIに送信できるevent_timeは、広告クリック発生日時からコンバージョン測定の計測期間内である必要があります。計測期間を超えたコンバージョンは送信しても計測対象外となるため、DWHからの抽出条件に日付フィルタを設定しておくことを推奨します。

必須パラメータの確認

転送元データに、APIで必須となるすべてのパラメータが含まれていることを事前に確認してください。詳細は「TROCCO側の設定」セクションの表を参照してください。

リクエスト制限について

コンバージョンAPIには50リクエスト/秒のレート制限があります。大量のコンバージョンデータを送信する場合は、バッチサイズや送信間隔を調整する必要があります。レート制限を超えた場合はHTTP 429エラーが返されます。

コンバージョンAPI送信後の反映タイミングについて

コンバージョンAPIで送信したデータは、Yahoo広告の管理画面に即時反映されるわけではありません。API送信は非同期処理となっており、管理画面への反映には一定の時間がかかります。

送信直後に管理画面を確認しても、コンバージョン数に変化が見られないことがあります。これは送信が失敗したわけではなく、仕様上の正常な挙動です。反映までの時間は状況によって異なり、数分から数時間、場合によっては当日中から翌日にかけて反映されることもあります。

テスト時にこの点を理解していないと、「送信したはずなのに反映されない」と混乱しやすくなります。検証時は以下の流れで確認することをお勧めします。

まずAPIレスポンスのステータスコードを確認する（HTTP 200が成功）
一定時間を置いてから管理画面でコンバージョン数を確認する

APIレスポンスが正常であれば、送信処理自体は完了しています。ただし、APIドキュメントに記載のとおり、リクエストが成功した場合でも、不正な値の場合や重複判定となった場合はコンバージョンの計測対象外になる点に注意してください。管理画面への反映を焦らず、時間を置いて確認するようにしてください。

テスト時の推奨事項

本番運用を開始する前に、以下の観点で検証を行ってください。

少量データ（数件〜数十件）での動作確認
必須パラメータがすべて含まれていることの確認
Yahoo広告管理画面でコンバージョンが反映されることの確認（時間を置いて）
エラーレスポンスが返った場合のデータ内容の確認

実運用の前のテストとして、転送元Google Spreadsheetsを利用すると、カスタムコネクタで送信するカラムの設計を柔軟に変更しながら検証を行うことが可能です。

Yahoo検索広告コンバージョン API連携を活用したカスタムコネクタのユースケース

オフラインコンバージョンの後追い送信

店舗への来店、営業担当による商談成立、電話での受注など、オフラインで発生したコンバージョンを広告成果として計測できます。広告クリック時のyclidと顧客データを紐づけておくことで、後日コンバージョンが確定した段階でAPIに送信します。

DWHを正とした広告コンバージョンデータの一元管理

複数の広告媒体やタグ計測のデータをDWHに集約し、一元的に管理している企業では、DWHのデータを正として各媒体にコンバージョンを送信する運用が可能です。データの整合性を保ちながら、広告最適化のためのシグナルを送信できます。

他媒体への横展開

Yahoo検索広告での連携が確立したら、同様の仕組みをGoogle広告やMeta広告のコンバージョンAPIにも展開できます。転送先カスタムコネクタ機能は任意のREST APIに対応しているため、媒体ごとにエンドポイントとリクエスト形式を設定することで、複数媒体への一括連携も実現可能です。

まとめ

Yahoo検索広告のコンバージョン計測において、タグ計測だけでは捉えきれないケースは少なくありません。オフラインコンバージョン、後追いコンバージョン、計測漏れの補完など、コンバージョンAPIを活用することで、より正確な広告効果測定が可能になります。

TROCCOの転送先カスタムコネクタ機能を使えば、API実装のためのエンジニアリソースを確保することなく、GUIベースでの連携を実現できます。DWHに蓄積されたファーストパーティデータを活用し、広告運用の精度向上に取り組んでみてはいかがでしょうか。

まずはテスト用のコンバージョンデータを使った検証から始めることをお勧めします。

作成したコネクタは再利用が可能です。専門的なAPI実装を前提とせず現場主導でデータ連携や運用自動化を進められるため、設計から保守までの負担を大幅に削減できます。

公式コネクタ同等の性能・セキュリティに加え、ワークフロー／通知も利用可能で、内製に比べ低コストで導入できます。

無料トライアルで、その使いやすさをお試しください。

※ 転送先カスタムコネクタ機能のご利用にはAdvancedプラン以上のご契約が必要です。

primeNumber編集長

primeNumberのブログを担当している編集長