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

​
Conversion API の設定

​
前提条件 

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

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

​
Ads API アクセス - 既存のアプリ

  • 既に稼働中の Ads API アプリがある場合は、そのアプリと既存のアクセストークンをいずれも Conversion API で使用できます。

​
アクセストークン

  • Ads API アプリケーションを所有するユーザーハンドル向けのユーザーアクセストークンは、開発者ポータルから直接生成および取得できます。これは自身の X ハンドルでの使用を想定しているため、「個人用アクセストークン」と呼ばれます。認証および開発者ポータルの概要はこちらをご覧ください。
  • Ads API アプリケーションを所有するハンドル以外のユーザーハンドル向けのユーザーアクセストークンは、3-legged OAuth フローで生成する必要があります。3-legged OAuth でアクセストークンを生成する方法には次のようなものがあります:
  • 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 を取得してください。同一のイベントでピクセルと Conversion API の両方を使用する場合は、同一イベントにおけるピクセルと Conversion API 間の重複排除を行うため、ピクセルのコードスニペットと 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 がまだない場合は Add an 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」をクリックすると、コンバージョンイベントが作成され、使用可能になります

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

現在は、twclid（Click ID）、メールアドレス、電話番号のいずれか少なくとも1つの識別子を送信する必要があります。IPアドレスまたはユーザーエージェントを使用する場合は、正確にコンバージョンを照合するため、2つ目の識別子も送信してください。 識別子を多く送信するほど、コンバージョン照合率は向上します。
顧客照合フィールド形式ハッシュ化が必要か
X Click IDX によって生成（詳細）不要
メールアドレス前後の空白を削除必須（SHA256）
電話番号E.164 標準必須（SHA256）
IP アドレス前後の空白を削除不要
ユーザーエージェント前後の空白を削除不要

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

コンバージョンリクエストには、常に Click ID を含めることを推奨します ユーザーが遷移先サイトに到達した後、利用可能であれば、クエリ文字列パラメータ twclid から Click ID を抽出して解析してください。  簡単な JavaScript のコード例: 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // 推奨される次のステップ:ログ記録、ローカルストレージへの挿入
}
次のことを推奨します。 
  1. URL のクエリパラメータに twclid の値が含まれている場合は、必ずパースしてください。
  2. 関連するフォームの fields やコンバージョンイベント情報と合わせて、data を保存してください。
Click ID をコンバージョンイベントやワークフロー情報に関連付けることで、バッチ処理、複数のウェブサイトのナビゲーションフローに基づいてコンバージョンイベントを分析・生成するアルゴリズム、大量アップロードといったシナリオが可能になります。 Event Source URL はURL エンコードされている必要があり、イベントをトリガーしたウェブページを表すことを想定しています。

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

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

​
3. 電話識別子の準備 

電話番号は E.164 規格 に従って渡し、情報はソルトなしの SHA-256 でハッシュ化する必要があります。  例：米国の電話番号 +11234567890 は、ハッシュ化した値として次のように送信してください：1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231。

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

IPアドレスは、別の識別子（twclid、メールアドレス、電話番号、またはユーザーエージェント）と組み合わせて渡す必要があります。この識別子についてはハッシュ化は不要です。 この値は、4つの数値をピリオドで区切ったドット表記（dotted-decimal）で表します。たとえば、ユーザーの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）であることを確認してください。エラーコードが返される場合に備え、リトライ機構と基本的なログ記録を用意することを推奨します。 エンドポイントの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":"ペット用品の購入",
            "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 のコンバージョン トラッキング ページで「Single event web tag」のステータスが TRACKING と表示されます。Conversion API 経由でコンバージョンを送信しても、進行中のキャンペーンには影響しません。 また、タグ ID ごとのコンバージョンイベントの分析結果は、次の方法で確認できます。

​
Pixel と Conversion API 間の重複排除

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

​
コンバージョントラッキング（概要）

​
概要

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

​
FAQ

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

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

API 呼び出し後のエラーコードに関するご質問は、以下のセクションをご覧ください。その他のご質問については、どうぞ遠慮なく Twitter の担当者までご連絡ください。できるだけ早く解決に向けて対応いたします。 

​
エラー処理と説明

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

​
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 RequestHashed_email は有効な SHA-256 ハッシュではありません
event_id の種別が単一イベントタグ（SET）ではない400 Bad RequestEvent_id (<event_id>) は単一イベントタグ（SET）ではありません
要求したコンバージョンイベントが上限を超過（現在はリクエストあたり 500 件）400 Bad Requestコンバージョン数の上限は 500 です
Event ID が見つからない400 Bad RequestEvent ID が見つかりませんでした

​
JSON エラーコード例

リクエスト:
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion&#95;time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
エラーメッセージ:

{"errors":[{"code":"INVALID_PARAMETER","message":"event&#95;id (o6dkt) is not a single event tag (SET)","parameter":"event&#95;id"}],"request":{"params":{"account&#95;id":"18ce552mlaq"}}}

​
リクエスト:

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

​
エラーメッセージ:

{"errors":[{"code":"INVALID_PARAMETER","message":"少なくとも1つのユーザー識別子を指定する必要があります","parameter":""}],"request":{"params":{"account&#95;id":"18ce552mlaq"}}}

​
リクエスト：

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion&#95;time": "2022-06-16T01:14:00.603Z", "event&#95;id":"o6dl3", "identifiers": [{"hashed&#95;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&#95;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&#95;time"}],"request":{"params":{"account&#95;id":"18ce552mlaq"}}}

​
401 Unauthorized

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

​
403 アクセス拒否 

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

​
404 Not Found 

理由種類エラーメッセージ
リクエストURLまたはパラメータがエンドポイントとして正しくありません404 Route Not Found要求されたリソースが見つかりませんでした
pixel_id/Universal website tag を所有するアカウントへのアクセス権がありません404 Not Foundユーザー <user_id> にはアカウント <account_id> へのアクセス権がありません。ユーザーのハンドルを取得するには ‘sn <user_id>’ を入力してください。使用中のユーザーを変更するには ‘twurl accounts’ と ‘twurl set default \u003Cusername\u003E’ を使用してください。
イベント 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&#95;id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' エラーメッセージ: {"errors":[{"code":"NOT_FOUND","message":"event&#95;id (abc) does not belong to provided account","parameter":"event&#95;id"},{"code":"INVALID_PARAMETER","message":"event&#95;id (abc) is not a single event tag (SET)","parameter":"event&#95;id"}],"request":{"params":{"account&#95;id":"18ce55gze09"}}}

​
API リファレンス索引

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

​
ウェブコンバージョン

コンバージョン APImeasurement/conversions/:pixel_id
Web Event Tagaccounts/:account_id/web_event_tags

​
ウェブコンバージョン

POST version/measurement/conversions/:pixel&#95;id 単一の Event Tag ID に対して、ウェブサイトのコンバージョンイベントを送信します。 成功（HTTP 200 OK）を確認するためにレスポンスコードをチェックしてください。エラーコードが返される場合に備えて、リトライ機構とベーシックなログ記録の実装を推奨します。 レート制限は、アカウントごとに15分あたり100,000件のリクエストです（各リクエストで最大500件のイベントが送信可能）。
リソースURL
https://ads-api.x.com/12/measurement/conversions/:pixel&#95;id
リクエストURLパラメータ
NameDescription
pixel_id
required		広告アカウントの Base Tag ID。広告アカウントの Base Tag ID を base36 でエンコードした値を表します。

Type: string

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

Type: array

Example: "conversions":[{"conversion&#95;time": "2022-02-18T01:14:00.603Z", "event&#95;id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion&#95;id": "23294827"}]
conversions オブジェクト
名前説明
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&#95;id-event-id）のいずれも可
identifiers
必須		コンバージョンイベントに照合するための識別子オブジェクトの一覧。サポートされる 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
任意		より詳細な情報を提供するための、特定の製品/コンテンツに関する詳細の一覧。サポートされる 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から抽出されたクリック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
場合によっては必須		ピリオドで区切られた 4 つの数値からなるドット表記の値。

IP アドレスは、他の識別子（twclid、メールアドレス、電話番号、またはユーザーエージェント）と組み合わせて渡すことが必須。

Type: string

Example: 8.25.197.25
**user_agent **
場合によっては必須		この識別子により、サーバーはリクエスト元ユーザーエージェントのアプリケーション、OS、ベンダー、またはバージョンを識別できる。

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 オブジェクト
名前説明
content_id
任意		SKU または GTIN。コンテンツを表す識別子。

型: string

例: jhp
content_group_id
任意		製品バリエーションのグループに関連付けられた ID。

型: integer

例: group 1
content_name
任意		製品またはサービスの名称。

型: string

例: radio flyer
content_price
任意		製品またはサービスの価格。

型: double

例: 5.00
content_type
任意		購入された製品のカテゴリ。

型: string

例: clothes
num_items
任意		購入された製品の数量。

型: integer

例: 1
レスポンスパラメーター
名前説明
conversions_processed正常に処理されたコンバージョンの数

型: integer

例: 1
debug_id後続の調査に使用できるデバッグ用UUID

型: string

例: 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 Event Tags

GET accounts/:account&#95;id/web_event_tags 現在のアカウントに関連付けられている Web イベントタグの詳細を、必要に応じて一部またはすべて取得します。

​
リソースURL

https://ads-api.x.com/12/accounts/:account&#95;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 レスポンス属性を含めます。

注意: このパラメーターと cursor は相互排他的です。

注意: 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": "トラッキング中",
          "type": "ダウンロード",
          "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&#95;id/web_event_tags/:web_event_tag_id
パラメータ
名称説明
account_id
必須		レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。

型: string

例: 18ce54d4x5t
web_event_tag_id
必須		リクエストで操作する Web イベントタグへの参照。

型: string

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

型: boolean

デフォルト: false
取りうる値: 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&#95;id/web_event_tags

​
パラメータ

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

型: string

例: 18ce54d4x5t
click_window
必須		このウェブタグのクリック計測ウィンドウ。

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

型: int

許容値: 1, 7, 14, 30
name
必須		ウェブタグの名前。

型: string

例: Sample single conversion event
retargeting_enabled
必須		このウェブタグでリターゲティングを有効にするかどうかを示します。

型: boolean

許容値: true, false
type
必須		ウェブタグのタイプ。

型: enum

許容値: 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
必須		このウェブタグのビュースルー計測ウィンドウ。この値は常に click_window の値以下である必要があります。

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

型: int

許容値: 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イベントタグ",
        "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": "未検証",
        "type": "サイト訪問",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "Webイベントタグ",
          "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&#95;id/web_event_tags/:web_event_tag_id

​
パラメーター

名前説明
account_id
必須		レバレッジドアカウントの識別子。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。

型: string

例: 18ce54d4x5t
web_event_tag_id
必須		現在のアカウント上の Web タグの識別子。

型: string

例: o3bk1
click_window
任意		この Web タグのクリック計測期間。

注意: 以下に列挙された値のみが受け付けられます。

型: int

取りうる値: 1, 7, 14, 30
name
任意		Web タグの名前。

型: string

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

型: boolean

取りうる値: true, false
type
任意		Web タグの種類。

型: enum

取りうる値: 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 の値以下でなければなりません。

注意: 以下に列挙された値のみが受け付けられます。

型: int

取りうる値: 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

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

​
リソース URL

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

型: string

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

型: string

例: 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"
        }
      }
    }