メインコンテンツへスキップ

​
Conversion API の設定

​
前提条件 

​
Ads API アクセス - 新規申請

ステップ 1: Developer Account
  • Developer Account を申請する際は、即時承認のためにサブスクリプションのプランのいずれかにお申し込みください。
  • 注: ベストプラクティスとして、公式の会社の X ハンドルを使用してデベロッパーアカウントを作成し、Ads API アクセスを申請することを強く推奨します。デベロッパーアカウントが個人のデベロッパーハンドルに紐づいている場合、必要になってもその認証情報を移行する方法はありません。継続的な運用のため、会社アカウントの管理下に置き、必要に応じてMulti-user login を活用してください。そうでない場合でも、最低限、アカウントはデフォルト以外の設定（ヘッダー画像、アバター、自己紹介文、自己紹介 URL）を行い、二要素認証を有効にしてください。
ステップ 2: Ads API アプリケーション
  • Ads API アプリケーション用に正しい App id を用意してください。App id は developer portal の Projects & Apps で確認できます。例: 16489123
  • X の担当者に連絡し、Ads API へのアクセスをリクエストしてください。

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

  • すでに X Ads API を積極的に利用しているアプリケーションがある場合は、そのアプリケーションと既存の access token の両方を Conversion API で利用できます。

​
Access Tokens

  • X Ads API アプリケーションを所有しているユーザーのハンドル向けのユーザー Access Tokens は、developer portal から直接生成・取得できます。これは自身の X ハンドルでの使用を想定しているため「personal access token」と呼ばれます。認証および developer portal の概要はこちらを参照してください。
  • X Ads API アプリケーションの所有者ハンドル以外のユーザーハンドル向けのユーザー Access Tokens は、3-legged OAuth フローで生成する必要があります。3-legged OAuth で Access Token を生成する方法の選択肢は以下のとおりです:
  • Conversion API で使用するユーザートークンは、AD_MANAGER または ACCOUNT_ADMIN のアクセスレベルを持つユーザーのものである必要があります。これは authenticated_user_access endpoint で確認できます。
  • 注: 上記のとおりに作成されたトークン自体は、利用目的であれば AD_MANAGER または ACCOUNT_ADMIN のアクセスレベルを持たないユーザーとも共有できます。

​
手順

​
Conversion API イベントの作成

Conversion API を使用するには、Ads Manager で新しいコンバージョンイベントを作成するか、すでに作成して X Pixel で使用しているイベントを利用する必要があります。Pixel と Conversion API のイベントで重複排除を行う場合は、Pixel 用に作成した既存のイベントを使用してください。 
オプション 1: Ads Manager で既存のコンバージョンイベントを使用する
すでに X ピクセルで利用している既存のイベントを使う場合は、対応可能です。その際は、そのイベントの Event ID を取得してください。同一のイベントで Pixel と Conversion API の両方を使用する場合は、イベントの重複を防ぐため、Pixel のコードスニペットと 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 を選択して Add an event source を実行（左側のサイドバーにまだ X pixel 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 IDX が生成（詳細）不要
メールアドレス先頭と末尾のスペースを削除必須（SHA256）
電話番号E.164規格必須（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 の query パラメータに twclid の値が含まれている場合は、必ずパースする。
  2. data を、関連するフォームの fields やコンバージョンイベント情報と併せて保存する。
Click ID をコンバージョンイベントやワークフロー情報に関連付けることで、バッチ処理、複数のウェブサイトの遷移フローに基づいてコンバージョンイベントを分析・作成するアルゴリズム、さらには一括アップロードなどのシナリオが可能になります。 Event Source URL は URL エンコード されている必要があり、イベントをトリガーしたウェブページを表します。

​
2. メール識別子の準備

サポートされている顧客照合の fields は送信できますが、正規化し、必要に応じてプライバシー保護のためにハッシュ化する必要があります。 情報はソルトなしの SHA256 でハッシュ化しなければなりません。 たとえば、メールアドレス test@x.com の場合、次のハッシュ値で送信してください: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62。

​
3. 電話識別子の準備

電話番号は E164 Standard に従った形式で渡し、情報はソルトなしの SHA256 で hash 化してください。 例：米国の電話番号 +11234567890 は、次の hash 化済み形式で送信します：1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231。

​
4. IPアドレス識別子の準備

IPアドレスは、別の識別子（twclid、メールアドレス、電話番号、またはユーザーエージェント）と組み合わせて渡す必要があります。この識別子についてはハッシュ化は不要です。 この値は、ピリオドで区切られた4つの数で表すドット表記の10進数表現です。たとえば、ユーザーのIPアドレスは 8.25.197.25 のようになります。

​
5. ユーザーエージェント識別子を準備する

ユーザーエージェントは、別の識別子（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）であることを確認してください。エラーコードが返された場合に備え、リトライ機構と基本的なロギングの実装を推奨します。 endpoint の URL および POST ボディパラメータの詳細は、API Reference セクションを参照してください。 

​
読みやすさのために整形したリクエスト例


    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":"ペット用品購入",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"ブランケット",
                  "content_type":"ペット用品",
                  "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 の Conversion Tracking ページで「Single event web tag」のステータスが TRACKING と表示されるはずです。Conversion API 経由でコンバージョンを送信しても、進行中のキャンペーンには影響しません。 また、タグの ID ごとにコンバージョンイベントの分析結果を確認できます。

​
Pixel と Conversion API 間の重複

Pixel と Conversion API のリクエスト間でコンバージョンの重複排除を行う場合、重複排除キーとして conversion_id を使用できます。重複排除はイベント単位でのみ実行されます。つまり、pixel と CAPI のリクエスト間で重複排除するには、同じ conversion_id を使用することに加えて、広告主は両方のリクエストで同一のイベントを送信する必要があります。重複排除は、48 時間以内に受信されたイベントに対してのみ行われます。

​
コンバージョン計測（概要）

​
概要

コンバージョン計測を使用すると、X上の広告を閲覧・エンゲージした後に、意図したアクションを実行したXのユーザー数を測定できます。どのキャンペーンがサイト訪問、登録、購入といったアクションを促しているかを把握できる機能を提供します。これにより、広告主はダイレクトレスポンス広告の成果を把握するためのX外での計測機能を得られ、費用対効果よく顧客を獲得できます。 コンバージョンタグを使用することで、広告主はユーザーのコンバージョンを追跡し、それをX上の広告キャンペーンにひも付けることができます。これにより、キャンペーンを最適化して獲得単価（CPA）目標を達成するための可視性が得られます。 コンバージョン計測で広告主が測定できるウェブサイト上のアクションにはさまざまなものがあります。広告キャンペーンで促したいアクションに応じて、1つ以上を選択できます。
  • サイト訪問: ユーザーが広告主のサイトのランディングページを訪問
  • 購入: ユーザーが広告主のサイトで商品またはサービスの購入を完了
  • ダウンロード: ユーザーが広告主のサイトからホワイトペーパーやソフトウェアパッケージなどのファイルをダウンロード
  • 登録: ユーザーが広告主のサービス、ニュースレター、またはメール配信に登録
  • カスタム: 上記のいずれにも該当しないカスタムアクション向けの包括的なカテゴリ
Xのコンバージョン計測は、広告主にコンバージョンアトリビューションの全体像を提供します。クライアントがX独自のコンバージョン計測機能の代替として使用している可能性のあるサードパーティ計測システム（たとえば、ユニークなクリックURLとサードパーティのトラッキングタグの組み合わせ）と比較して、Xのコンバージョンタグは、Tweetの展開、リツイート、いいね、返信、フォローといった中位・上位ファネルのエンゲージメントに起因するコンバージョン、さらにはインプレッションに起因するコンバージョンまで、広告主が追跡できるようにします。

​
FAQ

まず、広告主は X が提供するコードスニペットであるコンバージョンタグを作成し、自社サイトに設置します。これで、ユーザーが指定のアクションを完了した際にコンバージョンを計測できる準備が整います。その後、ユーザーは X クライアント上で広告主の広告に接触し、広告主のサイトへ誘導され、タグ付けされたアクションを行います。タグ設定時に広告主が指定したアトリビューションウィンドウ内にユーザーがそのアクションを完了した場合、タグはそのユーザーが以前に X の広告と接点を持ったことを認識します。するとタグが「発火」し、コンバージョンを生み出した広告へ正しく帰属できるように X のサーバーへ通知を送信します。
いいえ、本プロダクトでは特定のコンバージョンタグを特定のキャンペーンに紐づける設定には対応していません。代わりに、タグを一度設定すると、システムが自動的に、特定のタグでどの広告がコンバージョンにつながったかを追跡します。
デフォルトのポストビュー・アトリビューションウィンドウ：1日デフォルトのポストエンゲージメント・アトリビューション：14日これらのデフォルトは、コンバージョンタグの設定時、またはタグ作成後いつでも変更できます。ポストエンゲージメントのアトリビューションウィンドウの選択肢は 1、7、14、30、60、90 日です。ポストビューのアトリビューションウィンドウの選択肢は なし、1、7、14、30、60、90 日です。
各クライアントの目標・状況・戦略は異なりますが、コンバージョントラッキングのアルファまたはベータに参加したクライアントで効果があったアイデアをいくつかご紹介します。クリエイティブ：
  • オファー: 割引・プロモーション・送料無料などのオファーを Promoted Tweet と組み合わせて、アクションへの関心を高める
  • 懸賞・コンテスト: 特に著名ブランドでは、懸賞やコンテストがコンバージョンを牽引
  • Tweet コピーのテスト: 全大文字と小文字の比較検証（FREE と free、NOW と now）
  • 締め切り: 期限を提示して即時の行動を促す（Offer Expires December 12!）
  • 印象的な写真の追加: 視覚的に訴求力のある写真を Tweet クリエイティブに追加することがコンバージョン促進に有効かをテストする価値があります。結果は変動したり、クライアントの提供内容に依存する場合があります。
ターゲティング：
  • @handle ターゲティングと関心カテゴリターゲティング: 想定オーディエンスに合わせて Tweet のコピーと @handles を緊密に整合させることでコンバージョンを牽引
  • ニッチだがボリュームのあるキーワードの活用: コンサート分野では、アーティスト／ミュージシャン（例：名前）に関連するキーワードが有効でした。
  • Tailored audiences: TA Web とコンバージョントラッキングを併用したクライアントは、他のターゲティングを用いた対照群より CPA が低くなりました
キャンペーンのセグメンテーションが細かいほど、レポートされるコンバージョン結果はより実行可能になります。たとえば、50 個のキーワードで最適化するより、4 個のキーワードのキャンペーンを最適化するほうがはるかに容易です。

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

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

​
エラー処理と解説

1 回のリクエストは、含まれるすべての変換でエラーが 0 件の場合にのみ成功します。個々の変換でいずれかのエラーが発生した場合、endpoint は該当するすべてのエラーを一覧で返します。

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

以下は、X 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（そのendpointに対してURLまたはパラメータが正しくない可能性がある）

​
Conversion API のエラーコード

​
400 Bad Request のシナリオ

理由タイプエラーメッセージ
識別子の欠落エラー（現在はハッシュ化済みメールまたは X クリック ID（twclid））400 Bad Request少なくとも 1 つのユーザー識別子を指定する必要があります
無効なハッシュ化済みメール400 Bad RequestHashed_email は有効な SHA-256 hash ではありません
event_id の type が単一イベントタグ（SET）ではない400 Bad RequestEvent_id (<event_id>) は単一イベントタグ（SET）ではありません
要求したコンバージョンイベントが上限を超過（現在は 1 リクエストあたり 500 件）400 Bad Requestコンバージョン数の上限は 500 です
Event ID の欠落400 Bad RequestEvent 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":"ユーザー識別子を少なくとも1つ指定する必要があります","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) は有効な 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":"時間は yyyy-MM-ddTHH:mm:ss.SSSZ 形式である必要がありますが、conversion_time に対して \"2022-06-16T01:14:00.603\" が指定されました","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Unauthorized

理由: 認証情報が不足している、または誤っています 解決策: 次の3つの認証方法のいずれかを使用して、セットアップドキュメントの手順に従って認証を行ってください: Ads API アプリケーションの所有者ではないユーザーハンドル向けの User Access Tokens は、3-legged OAuth フローで生成する必要があります。3-legged OAuth で Access Token を生成する方法としては、次のオプションがあります。 Conversion API で使用するユーザートークンは、アクセスレベルが AD_MANAGER または ACCOUNT_ADMIN のユーザーのものである必要があり、authenticated_user_access endpoint で確認できます。

​
403 アクセス拒否

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

​
404 Not Found 

理由種類エラーメッセージ
リクエストURLまたはパラメータが当該endpointに対して正しくありません404 Route Not Found要求されたリソースが見つかりませんでした
pixel_id/Universal website tag の所有者であるアカウントへのアクセス権がありません404 Not FoundUser <user_id> には account <account_id> へのアクセス権がありません。ユーザーのハンドルを取得するには ‘sn <user_id>’ と入力してください。使用中のユーザーを変更するには ‘twurl accounts’ および ‘twurl set default \u003Cusername\u003E’ を使用してください。
event id が、指定された pixel ID (UWT ID) に関連付けられたアカウントに属していません404 Not Foundevent_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 リファレンスは、一覧から endpoint を選択してください。

​
ウェブコンバージョン

コンバージョン APImeasurement/conversions/:pixel_id
ウェブイベントタグ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パラメータ
NameDescription
pixel_id
必須		広告アカウントの Base Tag ID。広告アカウントの Base Tag ID を base36 でエンコードした値を表します。

Type: string

Example: o8z6j
conversions
必須		API リクエストの POST ボディに含まれるオブジェクト。コンバージョンイベントのリスト。最大 500 件まで指定できます。対応する fields は以下の表を参照してください。

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
conversions オブジェクト
NameDescription
conversion_time
必須		ISO 8601 形式で表した時刻。

Type: string

Example: 2017-10-05T00:00:00Z
event_id
必須		特定のイベントの base-36 の ID。この広告アカウント内で事前設定されたイベントに対応します。Events Manager の該当イベントでは「ID」と呼ばれます。

Type: string

Example: o87ne または tw-o8z6j-o87ne（tw-pixel_id-event-id）のどちらも可
identifiers
必須		コンバージョンイベントと照合するための識別子オブジェクトの List。サポートされる fields は下表を参照。識別子オブジェクトは少なくとも 1 つ必須です。

IP アドレスまたはユーザーエージェントを使用する場合は、正確なコンバージョン照合のために 2 つ目の識別子を送信する必要があります。

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
任意		イベントで購入されるアイテム数。0 より大きい正の数である必要があります。

Type: integer

Example: 4
price_currency
任意		イベントで購入されるアイテムの通貨。ISO-4217 で表記。詳細は Currency を参照。

Type: string

Default: USD

Example: JPY
value
任意		イベントで購入されるアイテムの価格。price_currency の通貨で表されます。

Type: double

Example: 100.00
conversion_id
任意		Pixel と Conversion API のコンバージョン間の重複排除用。同一の event tag 内における Web Pixel と Conversion API のコンバージョンの重複を排除するために使用できるコンバージョンイベントの識別子。詳細は Conversions Guide の「Testing Events and Deduplication」セクションを参照。

Type: string

Example: 23294827
description
任意		コンバージョンに関する追加情報を含む説明。

Type: string

Example: test conversion
contents
任意		特定の製品/コンテンツに関する詳細の List。より粒度の細かい情報を提供します。サポートされる fields は下表を参照。

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 オブジェクト
NameDescription
twclid
場合によっては必須		クリックスルーURLから抽出された Click ID。他の識別子が追加されていない場合は必須です。

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
場合によっては必須		SHA256 でハッシュ化されたメールアドレス。ハッシュ化前に、テキストは小文字にし、前後のスペースを削除してください。他の識別子が追加されていない場合は必須です。

Type: string

Example: test-email@test.com の場合 = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
場合によっては必須		E164 形式の電話番号を SHA256 でハッシュ化したもの。ハッシュ化前に電話番号は E164 形式である必要があります。他の識別子が追加されていない場合は必須です。

Type: string

Example: +11234567890 の場合 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address
場合によっては必須		この値はドット区切りの10進表記で、ピリオドで区切られた4つの数字で表します。

IP アドレスは、他の識別子（twclid、メールアドレス、電話番号、またはユーザーエージェント）と併せて渡す必要があります。

Type: string

Example: 8.25.197.25
user_agent
場合によっては必須		この識別子により、サーバーはリクエスト元のユーザーエージェントのアプリケーション、オペレーティングシステム、ベンダー、またはバージョンを特定できます。

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 オブジェクト
NameDescription
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
レスポンスパラメータ
NameDescription
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":"ペット用品購入",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"ブランケット",
                  "content_type":"ペット用品",
                  "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

​
パラメータ

NameDescription
account_id
必須		対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
count
任意		個々のリクエストごとに取得を試みるレコード数を指定します。

Type: int

Default: 200
Min, Max: 1, 1000
cursor
任意		次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。

Type: string

Example: 8x7v00oow
sort_by
任意		サポートされている属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。

Type: string

Example: created_at-asc
web_event_tag_ids
任意		識別子のカンマ区切りリストを指定して、目的の Web イベントタグのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。

Type: string

Example: o3bk1
with_deleted
任意		削除済みの結果をレスポンスに含めます。

Type: boolean

Default: false
Possible values: true, false
with_total_count
任意		レスポンスに 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": "ウェブイベントタグ",
          "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
パラメータ
名前説明
account_id
必須		対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必須		このリクエストで操作対象とする Web イベントタグの参照。

Type: string

Example: o3bk1
with_deleted
任意		削除済みの結果をレスポンスに含めます。

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イベントタグ",
        "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

​
パラメータ

NameDescription
account_id
required		対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
click_window
required		この Web タグのクリック計測ウィンドウ。

注: 下記の値のみが受け付けられます。

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 の値以下である必要があります。

注: 下記の値のみが受け付けられます。

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": "ウェブイベントタグ",
        "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": "ウェブイベントタグ",
          "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

現在のアカウントに紐づくウェブイベントタグを更新します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
パラメータ

NameDescription
account_id
必須		利用対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必須		現在のアカウント上の Web タグの ID。

Type: string

Example: o3bk1
click_window
任意		この Web タグのクリック計測ウィンドウ。

注: 下記の値のみが受け付けられます。

Type: int

Possible values: 1, 7, 14, 30
name
任意		Web タグの名称。

Type: string

Example: Sample single conversion event
retargeting_enabled
任意		この Web タグでリターゲティングを有効にするかどうか。

Type: boolean

Possible values: true, false
type
任意		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
任意		この 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": "ウェブイベントタグ",
        "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

現在のアカウントに関連付けられた特定のウェブイベントタグを削除します。

​
リソース URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
パラメータ
NameDescription
account_id
必須		使用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必須		現在のアカウントにある Web タグの識別子。

Type: string

Example: o3bk1
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
応答例
    {
      "data": {
        "name": "ウェブイベントタグ",
        "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"
        }
      }
    }
⌘I