Xコンバージョンコネクタ構成ガイド

API情報

このコネクタは、次のベンダーAPIを使用します。

API名：X Conversions API
APIバージョン：v12
APIエンドポイント：https://ads-api.x.com/
レート制限：アカウントごとに15分間で60,000イベント
ドキュメント：X：Web Conversions API

前提条件

X Ads APIへのアクセス権
X Developerアカウント
対象の広告アカウントにイベントを送信する権限を持つXユーザーアカウント

すでに運用中のX Ads APIアプリケーションがある場合は、そのアプリケーションと既存のアクセストークンの両方をConversion APIで使用できます。詳細については、X：Conversion API Set Upを参照してください。

仕組み

X Conversion APIを使用して、コンバージョンイベントをXに渡す独立したサーバーサイドアプリケーションを作成し、キャンペーン全体の最適化、測定、アトリビューションに活用します。このAPIを使用すると、Xウェブサイトピクセルを使用せずにコンバージョンイベントを送信し、Xで広告を配信した効果を測定できます。

現在、照合識別子を使用して広告効果を測定する主なユースケースは、次の2つです。

X Click IDを使用した、ウェブサイトトラフィックキャンペーンのクリックスルーコンバージョン
メールアドレスを使用した、すべてのXキャンペーンのビュースルーコンバージョンおよびクリックスルーコンバージョン

広告キャンペーンに応じて、コンバージョントラッキングにより、次のウェブサイトアクションを1つ以上測定できます。

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

X Conversion APIの使用

X Conversion APIを使用するには、X Ads Managerで新しいコンバージョンイベントを作成するか、すでに作成され、X Pixelで使用されている既存のイベントを使用する必要があります。X PixelとX Conversion APIリクエスト間でコンバージョンを重複排除するには、Pixel用に作成した既存のイベントを使用します。

Ads Managerでの既存のコンバージョンイベントの使用

X Pixelで使用されている既存のイベントを使用するには、そのイベントのイベントIDを使用します。同じイベントにX PixelとX Conversion APIの両方を使用する場合は、X PixelのコードスニペットとX Conversion APIリクエストの両方で、重複排除キー（conversion_id）を必ず使用してください。重複排除の詳細については、Xのドキュメント「Conversion API Set Up」の「Testing Events and Deduplication」セクションを参照してください。

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

コンバージョンイベントをX Conversion APIに渡すには、イベント識別子としてX Click ID（twclid）またはメールアドレスを少なくとも1つ構成する必要があります。

コンバージョンイベントをX Conversion APIに正常に渡すには、次の構成を推奨します。

URLクエリパラメータにtwclid値が存在する場合は、常にその値を解析してEvent Streaming API Hubに渡します。
関連するフォームフィールドまたはコンバージョンイベント情報とともにデータを保存します。

重複排除

Xが定義するサイト訪問イベントとランディングページビューイベントを含むページビューイベントについて、Xでは重複排除のために30分間の時間枠を設けています。購入やリードなど、その他のイベントタイプは重複排除されません。

PixelまたはX Conversion APIリクエストに含めることができるconversion_idイベントパラメータを使用して、イベントの重複を管理します。

構成の構成

Xコンバージョンを使用するには、Xアカウントを許可リストに登録する必要があります。許可リストへの登録については、Xの担当者にお問い合わせください。

コネクタマーケットプレイスに移動し、新しいコネクタを追加します。詳細については、コネクタについてを参照してください。

コネクタを追加した後、次の項目を構成します。

イベントID
特定のイベントを表すbase36形式のIDです。この広告アカウント内にあらかじめ構成されているイベントと一致します。Events Managerの対応するイベントでは、IDと表示されます。この値は、次の方法で作成できます。
- Single-Event Websiteタグの構成内で作成します。https://ads.x.com/で広告アカウントにログインし、ToolsからEvents Managerを選択します。
- APIを使用します。詳細については、X：Web Event Tagsを参照してください。
- Xのアカウントマネージャーに問い合わせます。
Pixel ID
広告アカウントのUniversal Website Tag（UWT）IDです。これは、広告アカウントのUWT IDをbase36でエンコードした値です。
Pixel IDを取得するには、次の手順に従います。
1. https://ads.x.com/で広告アカウントにログインします。
2. インターフェイスの左上にあるToolsで、Events Managerをクリックします。
3. 左側のサイドバーにX Pixelイベントソースがまだない場合は、ページの右上にあるAdd event sourceを選択します。
4. APIで使用される、このイベントのPixel IDとイベントIDがインターフェイスに表示されます。

コネクタアクション

アクション名	訪問プロファイル	イベントデータ
コンバージョンイベントを送信	✓	✓

Continueをクリックして、コネクタアクションを構成します。アクションの名前を入力し、ドロップダウンメニューからアクションタイプを選択します。

次のセクションでは、各アクションのパラメータとオプションを構成する方法について説明します。

コンバージョンイベントを送信

バッチ制限

このコネクタは、ベンダーへの大量データ転送に対応するため、リクエストをバッチ処理します。詳細については、[バッチアクション]。(/ja/server-side/connectors/batched-actions/)を参照してください。次のいずれかのしきい値に達するか、プロファイルが公開されるまで、リクエストはキューに格納されます。

リクエストの最大数：500
最も古いリクエストからの最大経過時間：10分
リクエストの最大サイズ：1 MB

ユーザーデータ

次のパラメータのうち、少なくとも1つを指定する必要があります。

パラメータ	タイプ	説明
X Click ID	文字列	クリックスルーURLから解析されたX Click IDです。X Click IDまたはメールアドレスのいずれかを指定する必要があります。照合率を高めるには、両方を使用してください。
メールアドレス（SHA256でハッシュ化済み）	文字列	前後の空白文字を削除し、小文字に変換して、SHA256でハッシュ化済みのメールアドレスを指定します。
メールアドレス（SHA256ハッシュを適用）	文字列	プレーンテキストのメールアドレスを指定します。コネクタが前後の空白文字を削除し、小文字に変換して、SHA256でハッシュ化します。
電話番号（SHA256でハッシュ化済み）	文字列	前後の空白文字を削除し、小文字に変換して、SHA256でハッシュ化済みのE164形式の電話番号を指定します。
電話番号（SHA256ハッシュを適用）	文字列	プレーンテキストの電話番号を指定します。コネクタが前後の空白文字を削除し、小文字に変換して、SHA256でハッシュ化します。
`ip_address`	文字列	この値は、4つの数字をピリオドで区切ったドット区切り10進表記で記述します。
`user_agent`	文字列	この識別子により、サーバーはリクエスト元ユーザーエージェントのアプリケーション、オペレーティングシステム、ベンダー、バージョンのいずれか、または複数を識別できます。

追加パラメータ

パラメータ	説明
イベント ID の上書き	広告マネージャーおよび広告 API では Website Tag ID と呼ばれ、X 広告プラットフォームの Events Manager で確認できます。このパラメータは必須フィールドであり、この構成によって構成セクションで使用されている Event Source ID が上書きされます。
ピクセル ID の上書き	広告アカウントの Universal Website Tag（UWT）ID。このパラメータは、広告アカウントの UWT ID を base36 でエンコードした値を表します。例：`o5h34`。この構成によって、構成セクションで使用されている Pixel ID が上書きされます。
コンバージョン時刻	（必須）コンバージョンイベントの発生時刻。ISO 8601 形式で表されたイベントの日時を指定します。指定しない場合は、イベントの発生時刻が値として使用されます。例：`2020-11-01T08:00:00.000Z`。
コンバージョン値	購入される商品の価格で、`price_currency` の通貨単位で表されます。
商品数	購入される商品の数。0 より大きい正の数でなければなりません。商品数を指定しない場合は、コンテンツ配列内の要素の総数が使用されます。
通貨	結果の絞り込みに使用する通貨の種類。ISO 4217 形式で識別されます。`USD` などの 3 文字の文字列です。
コンバージョン ID	ピクセルによるコンバージョンと Conversion API によるコンバージョンの重複排除に使用します。同じイベントタグにおける Web Pixel と Conversion API のコンバージョン間で重複排除に使用できる、コンバージョンイベントの識別子です。詳細については、X：Conversion API のセットアップを参照してください。
説明	コンバージョンに関する追加情報を含む説明。
検索文字列	広告主のウェブサイトで検索されたテキスト。

コンテンツ属性

省略可能なパラメータ：

パラメータ	説明
コンテンツ ID	コンテンツを表す SKU または GTIN（国際取引商品番号）識別子。
コンテンツグループ ID	商品バリエーションのグループに関連付けられた ID。
コンテンツ名	商品またはサービスの名前。
コンテンツ価格	商品またはサービスの価格。
コンテンツタイプ	購入された商品のカテゴリー。
商品数	購入された商品の数。