ウェブコンバージョン

​

Conversion API の設定

​

前提条件

​

Ads API アクセス - 新規アプリケーション

• Conversion API の主な要件は、Developer Account と Ads API Access を保有していることです。このプロセスは Ads API Getting Started ガイドで説明されています。以下の点に注意してください。

ステップ 1: 開発者アカウント

• Developer Account を申請する際は、即時承認を受けられるよう、いずれかのサブスクリプションプランにお申し込みください。 
• 注意: ベストプラクティスとして、公式な企業の X ハンドルを使用して開発者アカウントを作成し、Ads API アクセスを申請することを強く推奨します。開発者アカウントが個人の開発者ハンドルに紐づいている場合、必要になってもその認証情報を移管する方法はありません。継続的な管理のためには企業アカウント配下で管理し、必要に応じて Multi-user login を利用するのが最善です。そうでない場合でも最低限、アカウントは初期設定のままではない状態 (ヘッダー画像、アバター、自己紹介文、自己紹介 URL を設定) にし、2 要素認証を有効にしておく必要があります。

ステップ 2: Ads API アプリケーション

• Ads API アプリケーション用に、正しい App ID を用意しておいてください。App ID は Developer Console の「Projects & Apps」内で確認できます。例: 16489123
• Ads API へのアクセスをリクエストするには、X の担当者にご連絡ください。

​

Ads API アクセス - 既存のアプリケーション

• すでに Ads API をアクティブに利用しているアプリケーションがある場合、そのアプリケーションおよび既存のアクセストークンを Conversion API でも利用できます。

​

アクセス・トークン

• Ads API アプリケーションを所有しているユーザーハンドル向けの User Access Token は、開発者コンソールから直接生成および取得できます。これは、自分自身の X ハンドルで使用することを想定しているため、「personal access token (パーソナルアクセス・トークン) 」と呼ばれます。認証および開発者コンソールの概要についてはこちらをご覧ください。
• Ads API アプリケーションを所有しているハンドル以外のユーザーハンドル向けの User Access Token は、3-legged OAuth フローで生成する必要があります。3-legged OAuth で Access Token を生成する方法には、次のものがあります。
  • twurl ユーティリティを用いた Web ベース認可によるコマンドライン
  • PIN ベース認可によるコマンドライン
  • 3-legged OAuth パターンを実装したカスタム Web フロー
• Conversion API で使用するユーザートークンはすべて、AD_MANAGER または ACCOUNT_ADMIN のアクセスレベルを持つユーザーのものである必要があります。これは authenticated_user_access エンドポイントで確認できます。
• 注: 上記の手順で作成されたトークン自体は、利用のためであれば AD_MANAGER または ACCOUNT_ADMIN のアクセスレベルを持たないユーザーと共有することができます。

​

手順

​

Conversion API イベントの作成

Conversion API を利用するには、Ads Manager で新しいコンバージョンイベントを作成するか、すでに作成して X Pixel で使用しているコンバージョンイベントを利用する必要があります。Pixel と Conversion API のイベント間で重複排除 (デデュープ) を行いたい場合は、Pixel 用に作成した既存のイベントを使用する必要があります。 

オプション 1: Ads Manager で既存のコンバージョンイベントを使用する

すでに X ピクセルで使用している既存のイベントを利用したい場合は、そのイベントを引き続き利用でき、そのイベントから Event ID を取得する必要があります。同じイベントに対して X ピクセルと Conversion API の両方を使用する場合は、同一イベントについて X ピクセルと Conversion API 間のイベントを重複排除するため、X ピクセルのコードスニペットと Conversion API リクエストの両方で、必ず同じ重複排除キーを (conversion_id として) 使用してください。詳細については、「d. イベントのテストと重複排除」セクションを参照してください。 

オプション 2: Ads Manager で新しいコンバージョンイベントを作成する方法：

イベントを作成する前に、Events Manager で Event Source を作成しておくことが重要です。アカウントに Event Source (X Pixel) が追加されているか確認するには、Events Manager に移動し、左側のメニューに X Pixel が表示されているか確認してください。 

まだ Event Source が追加されていない場合は、以下の手順に従って Event Source を作成してください。

1. ads.x.com にアクセスします。
2. 画面左上の Tools セクションを開き、Events Manager をクリックします。
3. 画面右上の Add event source を選択します。左側のサイドバーにまだ X Pixel の Event Source がない場合は、ここから Event Source を追加します。
   1. X Pixel Event Source の ID が Pixel ID です。

これで Event Source と Pixel ID が用意できました。次に、トラッキングしたいコンバージョンイベント用に、その Event Source 内にイベントを作成する必要があります。

1. X Pixel Event Source 内で、右側の Add events を選択します。
2. Conversion API でのインストールを選択します。
3. このイベントの Pixel ID と Event ID が表示されます。これらは API で使用されます。
   1. このイベントの ID が Event ID です。
4. Save をクリックすると、コンバージョンイベントが作成され、すぐに利用できる状態になります。

​

コンバージョンイベント用識別子の準備

現在、Click ID (twclid) 、メールアドレス、電話番号など、少なくとも 1 つの識別子を渡す必要があります。IP アドレスまたはユーザーエージェントを使用する場合は、コンバージョンを適切にマッチングするために、2 つ目の識別子も必ず送信してください。

より多くの識別子を渡すことで、コンバージョンマッチング率が向上します。

カスタマーマッチングフィールド	フォーマット	ハッシュ化は必須か
X Click ID	X が生成 (詳細はこちら)	不要
メールアドレス	先頭と末尾の空白を削除	必須 (SHA256)
電話番号	E164 規格	必須 (SHA256)

IP アドレス	先頭と末尾の空白を削除	不要
ユーザーエージェント	先頭と末尾の空白を削除	不要

​

1. X Click ID 識別子を準備する

コンバージョンリクエストには常に Click ID を含めることを推奨します。

Click ID は、ユーザーが遷移してきた後の遷移先サイトで、クエリ文字列パラメーター twclid が利用可能な場合に、その値から抽出して取得する必要があります。 

基本的な JavaScript コード例:

var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // 推奨される次のステップ: ログ記録、ローカルストレージへの挿入
}

次のことを推奨します。 

1. URL のクエリパラメータに twclid の値が存在する場合は、必ずそれをパースする。

2. 関連するフォームフィールドやコンバージョンイベント情報と併せて、そのデータを保存する。

Click ID をコンバージョンイベントやワークフロー情報と紐づけることで、バッチ処理、複数のウェブサイトのナビゲーションフローに基づいてコンバージョンイベントを分析・作成するアルゴリズム、大量アップロードといったユースケースが可能になります。

Event Source URL は URL エンコード された形式で指定する必要があり、イベントをトリガーしたウェブページを表します。

​

2. メール識別子を準備する

顧客マッチング用としてサポートされているフィールドは送信できますが、正規化したうえで、必要に応じてプライバシー保護のためにハッシュ化する必要があります。

この情報は、ソルトなしで SHA256 を使用してハッシュ化しなければなりません。 

たとえば、メールアドレス [e-mail] の場合、次のようなハッシュ形式で送信する必要があります: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62。

​

3. 電話番号識別子の準備

電話番号は E164 Standard に準拠した形式で指定し、情報はソルトなしの SHA256 でハッシュする必要があります。 

たとえば、米国の電話番号 [phone] の場合、次のようなハッシュ値として送信する必要があります: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231。

​

4. IP アドレス識別子を準備する

IP アドレスは、別の識別子 (twclid、メールアドレス、電話番号、またはユーザーエージェント) と組み合わせて送信する必要があります。この識別子についてはハッシュ化は不要です。

この値は、4 つの数字をピリオドで区切ったドット付き 10 進表記で記述されます。たとえば、ユーザーの IP アドレスは 8.25.197.25 のように表記されます。

​

5. User Agent 識別子を準備する

User Agent は、別の識別子 (twclid、メールアドレス、電話番号、または IP アドレス) と組み合わせて送信する必要があります。この識別子についてハッシュ化は不要です。

この識別子により、サーバーはリクエストを送信しているユーザーエージェントのアプリケーション、オペレーティングシステム、ベンダー、およびバージョンを特定できます。たとえば、この値は Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 のように送信できます。

​

コンバージョンイベントリクエストの作成

POST: version/measurement/conversions/:pixel_id

特定の広告アカウントに対してコンバージョンイベントを送信します。レスポンスコードが成功 (HTTP 200 OK) であることを必ず確認してください。エラーコードが返された場合に備え、リトライ機構と基本的なログ出力を用意しておくことを推奨します。

エンドポイントのURLおよびPOSTボディパラメータの詳細については、APIリファレンスセクションを参照してください。 

​

リクエスト例 (読みやすくするために整形済み)

    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​

レスポンス例

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

​

レート制限

レート制限は、15分ごとにアカウントあたり最大 60,000 件のイベントです。

このリクエスト呼び出し以外にも、サーバー側コードで次のようなロジックを実装する必要がある場合があります:

1. 各イベントごとに正しいコンバージョンデータを送信できるようにするための、ユーザーアクションのインストルメンテーション (ログ記録など)

2. 関連するプライバシー選択を行ったユーザーのコンバージョンイベントを除外するために必要なロジック
   例: 広告主のウェブサイト上で、トラッキングや個人情報の販売をオプトアウトしている場合

3. イベントを取得してコンバージョンを送信するための、イベントトリガーおよびページとの連携

​

イベントのテストと重複排除

​

イベントのテスト

イベントでコンバージョンイベントが正常に受信されると、12～24時間以内に、Ads Manager のコンバージョントラッキングページ上で「Single event web tag」のステータスが TRACKING と表示されるようになります。Conversion API 経由でコンバージョンを送信しても、配信中のキャンペーンには影響しません。

また、タグ ID ごとのコンバージョンイベントの分析結果は、次の方法で確認できます。

• Ads Manager のデータエクスポート (Analytics for Website Conversion Tracking のヘルプページ)

• Ads API を使用したデータのエクスポート (segmentation_type=CONVERSION_TAGS)  

​

Pixel と Conversion API 間の重複

Pixel と Conversion API リクエスト間でコンバージョンの重複排除を行いたい場合は、重複排除キーとして conversion_id を使用できます。重複排除はイベントレベルでのみ行われます。言い換えると、Pixel と CAPI 間で重複排除を行うには、同じ conversion_id を使用するだけでなく、Pixel 側と CAPI 側の両方のリクエストで同一のイベントを使用する必要があります。重複排除が行われるのは、48 時間以内に受信したイベントに対してのみです。

​

コンバージョントラッキング (概要)

​

概要

コンバージョン計測を使用すると、X 上の広告を閲覧・エンゲージした後に、X ユーザーが望ましいアクションを実行した数を測定できます。どのキャンペーンがサイト訪問、サインアップ、購入といったアクションを促しているかを測定できるようになります。これにより、広告主は X 外での計測機能を通じて、ダイレクトレスポンス広告のパフォーマンスを把握し、費用対効果の高い形で顧客を獲得できるようになります。

コンバージョンタグを利用することで、広告主はユーザーのコンバージョンを計測し、それを X 上の広告キャンペーンに紐付けることができます。これにより、広告主はキャンペーンを最適化し、目標とする顧客獲得単価 (CPA) を達成するために必要な可視性を得られます。

コンバージョン計測を用いて広告主が測定できるウェブサイト上のアクションには、さまざまな種類があります。広告キャンペーンによって促したいアクションに応じて、1 つまたは複数を選択できます。

• サイト訪問: ユーザーが広告主のサイト上のランディングページを訪問する
• 購入: ユーザーが広告主のサイト上で商品またはサービスの購入を完了する
• ダウンロード: ユーザーが広告主のサイトから、ホワイトペーパーやソフトウェアパッケージなどのファイルをダウンロードする
• サインアップ: ユーザーが広告主のサービス、ニュースレター、またはメール配信に登録する
• カスタム: 上記のいずれのカテゴリにも当てはまらない独自アクションを対象とする汎用カテゴリ

X のコンバージョン計測により、広告主はコンバージョンアトリビューションの全体像を把握できます。ユニークなクリック URL とサードパーティのトラッキングタグを組み合わせた手法など、X 独自のコンバージョン計測機能の代わりにクライアントが利用していた可能性のあるサードパーティ計測システムと比較して、X のコンバージョンタグは、ツイートの詳細表示、リツイート、「いいね」、返信、フォロー、さらにはインプレッションといった中・上位ファネルのエンゲージメントに起因するコンバージョンまで計測できるようにします。

​

FAQ

コンバージョントラッキングタグはどのように動作しますか？

まず広告主は、X から提供されるコードスニペットであるコンバージョンタグを作成し、自社サイトに設置します。タグは、ユーザーが指定されたアクションを完了した際にコンバージョンを計測できる状態になります。

その後、ユーザーは X クライアント上で広告主の広告を目にし、広告主のウェブサイトへ誘導され、タグを設置したアクションを行います。ユーザーが、タグ設定時に広告主が指定したアトリビューションウィンドウ内にそのアクションを完了した場合、タグはそのユーザーが以前に X 広告とインタラクションしていたことを認識します。タグは「発火」して、コンバージョンを発生させた広告にコンバージョンをひも付けるための通知を X のサーバーに送信します。

キャンペーン設定の中で、そのキャンペーンに関連するトラッキングピクセルを選択する方法はありますか？

いいえ、現在の製品では特定のコンバージョンタグを特定のキャンペーンに紐づける構成にはなっていません。代わりに、一度タグを設定すると、システムがどの広告が特定のタグでコンバージョンを生んだかを自動的に追跡します。

コンバージョンタグのデフォルトのアトリビューションウィンドウ設定はどうなっていますか？

デフォルトのポストビュー・アトリビューションウィンドウ: 1 日間

デフォルトのポストエンゲージメント・アトリビューションウィンドウ: 14 日間

これらのデフォルト値は、コンバージョンタグの設定時やタグ作成後いつでも変更できます。ポストエンゲージメント・アトリビューションウィンドウの選択肢は 1、7、14、30、60、90 日です。ポストビュー・アトリビューションウィンドウの選択肢は「なし」、1、7、14、30、60、90 日です。

コンバージョンを効果的に増やすための有効な DR クリエイティブや戦略にはどのようなものがありますか？

各クライアントの目標や状況、戦略はそれぞれ異なりますが、コンバージョントラッキングのアルファ版またはベータ版に参加したクライアントで効果があったアイデアをいくつかご紹介します。

クリエイティブ:

• オファー: 行動喚起への関心を高めるために、プロモツイートに割引、プロモーション、送料無料などのオファーを組み合わせる
• 懸賞やコンテスト: 特に認知度の高いブランドでは、懸賞やコンテストがコンバージョンを促進
• ツイート文言のテスト: 全て大文字と小文字の比較テスト (FREE と free、NOW と now など)
• 期限の設定: すぐに行動してもらうために期限を設ける (「12 月 12 日まで！」など)
• 魅力的な写真の追加: 視覚的に魅力的な写真をツイートクリエイティブに追加することがコンバージョン促進に有効かどうかをテストする価値があります。結果はクライアントの提供内容によって異なる場合があります。

ターゲティング:

• @handle ターゲティングおよびインタレストカテゴリターゲティング: ツイート文言と @handle をツイートの想定オーディエンスに高い精度で合わせることでコンバージョンが増加
• ニッチだがボリュームの多いキーワードの活用: コンサート分野では、アーティスト／ミュージシャン (例: 名前) に関連するキーワードの使用が有効であることがわかりました。
• Tailored audiences (テイラードオーディエンス) : TA Web とコンバージョントラッキングを併用したクライアントは、他のターゲティングを使用した対照グループよりも低い CPA を達成しました。

キャンペーンのセグメンテーションが細かければ細かいほど、コンバージョンレポートの結果をよりアクションにつなげやすくなります。たとえば、50 個のキーワードを含むキャンペーンを最適化するよりも、4 個のキーワードを含むキャンペーンを最適化する方がはるかに容易です。

​

Conversion API のトラブルシューティングとサポート

API 呼び出し後に返されるエラーコードに関するご質問は、以下のセクションをご覧ください。その他のご質問については、遠慮なく Twitter の担当者までお問い合わせください。可能な限り速やかに解決に向けて対応いたします。 

​

エラー処理と説明

1 つのリクエストは、その中に含まれるすべてのコンバージョンで errors が 0 件である場合にのみ成功します。個々のコンバージョン内でいずれかのエラーが発生した場合、エンドポイントはそのコンバージョンに該当するすべての errors の一覧を返します。

​

X Ads API エラーコードの概要

以下は、Ads API におけるエラーコードの網羅的な一覧です。

https://developer.x.com/en/docs/twitter-ads-api/response-codes

Conversion API の成功したレスポンスは、200 番台の HTTP コードと、要求されたオブジェクトを含む JSON ベースのペイロードによって示されます。

​

500番台のHTTPステータスコードが返される場合、これはリクエスト内容やアカウント設定ではなく、サーバー側の問題に関連しています。X API status page や developer community forum を確認し、ほかのユーザーにも同様の問題が発生していないかを確認してください。

​

400 番台の HTTP ステータスコードが返される場合、よくあるケースは次のとおりです

• 400 Bad Request (リクエストが仕様どおりになっていない)

• 401 Unauthorized (認証に問題がある)

• 403 Forbidden (その開発者アカウントに紐づく API アクセス権に問題がある)

• 404 Not Found (そのエンドポイントに対して URL やパラメータが正しくない可能性がある)

​

Conversion API のエラーコード

​

400 Bad Request のシナリオ

理由	タイプ	エラーメッセージ
識別子が指定されていないエラー (現在はハッシュ化済みメールアドレスまたは X クリック ID (twclid) )	400 Bad Request	少なくとも 1 つのユーザー識別子を指定する必要があります
無効なハッシュ化済みメールアドレス	400 Bad Request	Hashed_email が有効な SHA-256 ハッシュではありません
event_id の type が単一イベントタグ (SET) ではない	400 Bad Request	Event_id (<event_id>) が単一イベントタグ (SET) ではありません
リクエストされたコンバージョンイベント数が上限を超えている (現在は 1 リクエストあたり 500 イベントまで)	400 Bad Request	コンバージョン数の上限は 500 件です
Event ID が指定されていない	400 Bad Request	Event ID が見つかりませんでした

​

JSON エラーコードの例

リクエスト:

POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​

エラーメッセージ：

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​

リクエスト:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​

エラーメッセージ:

{"errors":[{"code":"INVALID_PARAMETER","message":"At least one user identifier must be provided","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​

リクエスト:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​

エラーメッセージ：

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​

リクエスト：

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​

エラーメッセージ：

{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​

401 Unauthorized

理由: 認証情報が存在しない、または正しくありません

解決方法: 次の 3 つの認証方法のいずれかを使用して、セットアップドキュメントに記載された認証手順に従ってください。

Ads API アプリケーションを所有しているハンドル以外のユーザーハンドル用の User Access Tokens は、3-legged OAuth フローで生成する必要があります。3-legged OAuth を使用して Access Token を生成する方法としては、次のオプションがあります。

• twurl ユーティリティを用いた Web ベース認可によるコマンドライン

• PIN ベース認証によるコマンドライン

• 3-legged OAuth パターンを実装したカスタム Web フロー

Conversion API で使用されるユーザートークンはすべて、AD_MANAGER または ACCOUNT_ADMIN のアクセスレベル*を持つユーザーのものでなければなりません。このアクセスレベルは、authenticated_user_access エンドポイントで確認できます。

​

403 アクセス禁止

理由	種別	エラーメッセージ
使用している開発者アカウントには Ads API へのアクセス権がありません。こちらからアクセスを申請してください。	403 Unauthorized Client	このリクエストを行っている id が <> のクライアントアプリケーションには X Ads API へのアクセス権がありません。アプリケーションに advertiser-api access が付与されていることを確認してください。使用しているアプリケーションを変更するには、‘twurl accounts’ と ‘twurl set default <username> <key>’ を使用してください。

​

404 Not Found

理由	種別	エラーメッセージ
リクエストのURLまたはパラメータが、このエンドポイントに対して正しくありません	404 Route Not Found	要求されたリソースが見つかりませんでした
pixel_id/Universal website tag を所有するアカウントへのアクセス権がありません	404 Not Found	User <user_id> には account <account_id> へのアクセス権がありません。ユーザーのハンドルを取得するには ‘sn <user_id>’ と入力してください。使用中のユーザーを変更するには ‘twurl accounts’ と ‘twurl set default \u003Cusername\u003E’ を使用してください。
event id が、指定された pixel ID (UWT ID) に関連付けられているアカウントに属していません	404 Not Found	event_id <event_id> は指定されたアカウントに属していません

​

JSON エラーコードの例

​

リクエスト:

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

エラーメッセージ:

{"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​

APIリファレンス インデックス

完全なAPIリファレンスを表示するには、リストからエンドポイントを選択してください。

​

Webコンバージョン

コンバージョンAPI	measurement/conversions/:pixel_id
Webイベントタグ	accounts/:account_id/web_event_tags

​

Web Conversions

POST version/measurement/conversions/:pixel_id

単一の Event Tag ID に対して、ウェブサイトのコンバージョンイベントを送信します。

レスポンスコードが HTTP 200 OK (成功) であることを確認してください。エラーコードが返される場合に備えて、リトライ機構と基本的なログ出力を用意しておくことを推奨します。

レート制限は、アカウントごとに 15 分間あたり 100,000 リクエストです (各リクエストで最大 500 件のイベントを送信できます) 。

リソース URL

https://ads-api.x.com/12/measurement/conversions/:pixel_id

リクエスト URL パラメータ

Name	Description
pixel_id 必須	広告アカウントの Base Tag ID。広告アカウントの Base Tag ID を base36 でエンコードした値を表します。 Type: string Example: o8z6j
conversions 必須	API リクエストの POST リクエストボディ内のオブジェクトです。コンバージョンイベントのリストで、最大 500 件まで指定できます。サポートされているフィールドについては、以下の表を参照してください。 Type: array Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]

conversions オブジェクト

Name	Description
conversion_time required	ISO 8601 で表現された時間。 Type: string Example: 2017-10-05T00:00:00Z
event_id required	特定のイベントの base-36 (36 進数) ID。この広告アカウント内に含まれる、事前に設定されたイベントと一致します。Events Manager 内の対応するイベントでは、これは ID と呼ばれます。 Type: string Example: o87ne または tw-o8z6j-o87ne (tw-pixel_id-event-id) のいずれも有効です
identifiers required	コンバージョンイベントを照合するための identifier オブジェクトのリスト。サポートされているフィールドは、下の表に記載されています。少なくとも 1 つの identifier オブジェクトが必須です。 IP アドレスまたはユーザーエージェントを使用する場合は、正しくコンバージョンを照合するために 2 つ目の identifier も送信する必要があります。 Type: array Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items optional	イベント内で購入されるアイテム数。0 より大きい正の数である必要があります。 Type: integer Example: 4
price_currency optional	イベントで購入されるアイテムの通貨。ISO-4217 で表現されます。詳細は Currency を参照してください。 Type: string Default: USD Example: JPY
value optional	イベントで購入されるアイテムの価格。price_currency で指定された通貨で表現されます。 Type: double Example: 100.00
conversion_id optional	ピクセルコンバージョンと Conversion API コンバージョン間の重複排除用。同じイベントタグ 内の Web Pixel と Conversion API のコンバージョン間で重複排除を行うために使用できる、コンバージョンイベントの識別子です。詳細は Conversions Guide の「Testing Events and Deduplication」セクションを参照してください。 Type: string Example: 23294827
description optional	コンバージョンに関する追加情報を含む説明。 Type: string Example: test conversion
contents optional	特定の商品／コンテンツに関する詳細情報のリストで、より粒度の細かい情報を提供します。サポートされているフィールドは、下の表を参照してください。 Type: array Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]

identifiers object

Name	Description
twclid sometimes required	クリック先 URL から抽出された Click ID。ほかの識別子が追加されていない場合は必須です。 Type: string Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email sometimes required	SHA256 でハッシュ化されたメールアドレス。テキストはすべて小文字にし、前後の空白を削除してからハッシュ化してください。ほかの識別子が追加されていない場合は必須です。 Type: string Example: For [e-mail] = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number sometimes required	E164 形式の電話番号を SHA256 でハッシュ化したもの。電話番号はハッシュ化する前に E164 形式にしておく必要があります。ほかの識別子が追加されていない場合は必須です。 Type: string Example: For [phone] = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address sometimes required	4 つの数字をピリオドで区切った、ドット区切りの 10 進表記で記述されます。 IP アドレスは、ほかの識別子 (twclid、メールアドレス、電話番号、または user agent) のいずれかと組み合わせて渡す必要があります。 Type: string Example: 8.25.197.25
**user_agent ** sometimes required	この識別子により、サーバーはリクエストを行っているユーザーエージェントのアプリケーション、オペレーティングシステム、ベンダー、および／またはバージョンを識別できます。 User Agent は、ほかの識別子 (twclid、メールアドレス、電話番号、または IP アドレス) のいずれかと組み合わせて渡す必要があります。 Type: string Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

contents オブジェクト

Name	Description
content_id optional	SKU または GTIN。コンテンツを表す識別子。 Type: string Example: jhp
content_group_id optional	製品バリエーションのグループに関連付けられた ID。 Type: integer Example: group 1
content_name optional	製品またはサービスの名称。 Type: string Example: radio flyer
content_price optional	製品またはサービスの価格。 Type: double Example: 5.00
content_type optional	購入された製品のカテゴリー。 Type: string Example: clothes
num_items optional	購入された製品数。 Type: integer Example: 1

レスポンスパラメーター

Name	Description
conversions_processed	正常に処理されたコンバージョン数 Type: integer Example: 1
debug_id	以降の調査に使用できるデバッグ用 UUID Type: string Example: ff02e052-36e4-47d6-bdf0-6d8986446562

リクエスト例

    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

リクエスト例

    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​

Webイベントタグ

GET accounts/:account_id/web_event_tags

現在のアカウントに関連付けられている Webイベントタグの一部またはすべての詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​

パラメーター

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常、必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	各リクエストごとに取得を試行するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
sort_by optional	サポートされている属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
web_event_tag_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを指定した Web イベントタグのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: o3bk1
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメーターと cursor は排他的です。 Note: total_count を含むリクエストはレート制限がより厳しくなり、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​

レスポンス例

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD",
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/web_event_tags/:web_event_tag_id

現在のアカウントに紐づく特定の Web イベントタグを取得します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
web_event_tag_id required	リクエストで操作対象となる Web イベントタグへの参照です。 Type: string Example: o3bk1
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1

レスポンス例

    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​

POST accounts/:account_id/web_event_tags

新しい Web イベントタグを現在のアカウントに関連付けて作成します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
click_window required	この Webタグのクリック計測期間 (クリックウィンドウ) です。 Note: 以下に示す値のみが有効です。 Type: int Possible values: 1, 7, 14, 30
name required	Webタグの名前です。 Type: string Example: Sample single conversion event
retargeting_enabled required	この Webタグに対してリターゲティングを有効にするかどうかを示します。 Type: boolean Possible values: true, false
type required	Webタグの種別です。 Type: enum Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE (UI 上では、SITE_VISIT は「Page view」、SIGN_UP は「Lead」として表示されます)
view_through_window required	この Webタグのビュースルー計測期間 (ビュースルーウィンドウ) です。この値は常に click_window の値以下である必要があります。 Note: 以下に示す値のみが有効です。 Type: int Possible values: 0, 1, 7, 14, 30

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​

レスポンス例

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​

PUT accounts/:account_id/web_event_tags/:web_event_tag_id

現在のアカウントに関連付けられているWebイベントタグを更新します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
web_event_tag_id required	現在のアカウントの Web タグの識別子です。 Type: string Example: o3bk1
click_window optional	この Web タグのクリック計測期間です。 注: 以下に示す値のみが有効です。 Type: int Possible values: 1, 7, 14, 30
name optional	Web タグの名前です。 Type: string Example: Sample single conversion event
retargeting_enabled optional	この Web タグでリターゲティングを有効にするかどうかを示します。 Type: boolean Possible values: true, false
type optional	Web タグの種別です。 Type: enum Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE (UI 上では、SITE_VISIT は「Page view」、SIGN_UP は「Lead」として表示されます)
view_through_window optional	この Web タグのビュースルー計測期間です。この値は常に click_window の値以下でなければなりません。 注: 以下に示す値のみが有効です。 Type: int Possible values: 0, 1, 7, 14, 30

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​

レスポンスの例

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

現在のアカウントに紐付いている特定の web event tag を削除します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常、必須パラメーターです。指定したアカウントは、認証されたユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
web_event_tag_id required	現在のアカウントに存在する Web タグの識別子。 Type: string Example: o3bk1

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1

レスポンス例

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }