X変換コネクタ構成ガイド

API情報

このコネクタは以下のベンダーAPIを使用します：

• API名：X Ads API
• APIバージョン：v12
• APIエンドポイント：https://ads-api.x.com/
• レート制限：アカウントあたり15分間に60,000イベント

前提条件

• 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で使用されている既存のイベントを使用するには、そのイベントのEvent 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に渡されるためには、少なくとも1つのX Click ID（twclid）またはメールアドレスがイベント識別子として構成されている必要があります。

X Conversion APIに変換イベントを正常に構成するために、以下の構成を推奨します：

• URLクエリパラメータにtwclid値が存在する場合は常に解析し、Tealium EventStream API Hubに渡します。
• データを関連するフォームフィールドや変換イベント情報と一緒に保存します。

重複排除

Page Viewイベント、つまりX定義のSite VisitおよびLanding Page Viewイベントについては、Xは重複排除のための30分間のウィンドウを提供します。PurchaseやLeadなどの他のイベントタイプは重複排除されません。

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

コネクタアクション

アクション名	AudienceStream	EventStream
変換イベントの送信	✓	✓

構成の構成

X変換は、あなたのXアカウントでの許可リストが必要です。許可リストの構成については、Xの担当者にお問い合わせください。

コネクタマーケットプレイスに移動し、新しいコネクタを追加します。コネクタの追加方法の一般的な指示については、About Connectorsの記事を参照してください。

コネクタを追加した後、以下の構成を構成します：

• イベントID
  特定のイベントの基数36のIDです。これは、この広告アカウント内に含まれる事前に構成されたイベントと一致します。これは、Events Manager内の対応するイベントでIDと呼ばれます。 この値は以下の方法で作成できます：

  • Single-Event Websiteタグ構成内で。ads.x.comで広告アカウントにログインし、Toolsの下でEvents Managerを選択します。
  • APIを使用します。詳細については、Web Event Tagsを参照してください。
  • Xのアカウントマネージャーにお問い合わせください。

• Pixel ID
  広告アカウントのUniversal Website Tag（UWT）IDです。これは、広告アカウントのUWT IDの基数36エンコード値を表します。
  Pixel IDを取得するには：

  1. ads.x.comに移動します。
  2. インターフェースの左上隅で、Toolsの下でEvents Managerをクリックします。
  3. まだ左側のサイドバーにX Pixelイベントソースがない場合、ページの右上隅でAdd event sourceを選択します。
  4. インターフェースは、APIで使用されるこのイベントのPixel IDとEvent IDを表示します。

アクション構成 - パラメータとオプション

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

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

アクション - 変換イベントの送信

ユーザーデータ

以下のパラメータのうち少なくとも1つを提供する必要があります：

| パラメータ | タイプ |説明 | | — | — | | X Click ID | String | クリックスルーURLから解析されたX Click ID。X Click IDまたはEmailのいずれかを指定する必要があります。マッチ率を向上させるために、両方を指定することが推奨されます。 | | Email Address (already SHA256 hashed) | String | すでに空白をトリムし、小文字にし、SHA256でハッシュ化されたメールアドレスを提供します。 | | Email Address (apply SHA256 hash) | String | プレーンテキストのメールアドレスを提供し、コネクタはこの値を空白をトリムし、小文字にし、SHA256ハッシュを使用してハッシュ化します。 | | Phone Number (already SHA256 hashed) | String | すでに空白をトリムし、小文字にし、SHA256でハッシュ化し、E164形式にした電話番号を提供します。 | | Phone Number (apply SHA256 hash) | String | プレーンテキストの電話番号を提供し、コネクタはこの値を空白をトリムし、小文字にし、SHA256ハッシュを使用してハッシュ化します。 | | ip_address | String | この値はドットで区切られた10進表記で書かれており、ピリオドで区切られた4つの数字があります。 | | user_agent | String | この識別子により、サーバーはリクエストするユーザーエージェントのアプリケーション、オペレーティングシステム、ベンダー、および/またはバージョンを識別できます。 |

追加パラメータ

パラメータ	説明
Event Source ID Override	これはAds ManagerとAds APIでWebsite Tag IDと呼ばれ、X AdsプラットフォームのEvents Managerで見つけることができます。このパラメータは必須フィールドであり、この構成は構成セクションで使用されるEvent Source IDを上書きします。
Pixel ID Override	広告アカウントのUniversal Website Tag（UWT）IDです。このパラメータは、広告アカウントのUWT IDの基数36エンコード値を表します。例：o5h34。この構成は、構成セクションで使用されるPixel IDを上書きします。
Conversion Time	必須。変換イベントの時間。イベントの日時をISO 8601で指定します。提供されていない場合、イベントの時間が使用されます。例：2020-11-01T08:00:00.000Z。
変換値	購入されるアイテムの価格値。‘price_currency’通貨で表されます。
アイテム数	購入されるアイテムの数。ゼロより大きい正の数でなければなりません。アイテム数が提供されていない場合、Contents配列の要素の総数が使用されます。
通貨	結果をフィルタリングする通貨の種類。 ISO 4217を使用して識別します。これは’USD’のような3文字の文字列です。
変換ID	ピクセルと変換APIの変換間の重複排除用。同じイベントタグ内のWeb PixelとConversion APIの変換間で重複排除に使用できる変換イベントの識別子。詳細は変換ガイドを参照してください。
説明	変換に関する追加情報の説明。
検索文字列	広告主のウェブサイトで検索されたテキスト。
コンテンツID	コンテンツを表すSKUまたはGTIN識別子。
コンテンツグループID	製品バリアントのグループに関連付けられたID。
コンテンツ名	製品またはサービスの名前。
コンテンツ価格	製品またはサービスの価格。
コンテンツタイプ	購入された製品のカテゴリ。
アイテム数	購入された製品の数。

モバイル測定変換イベントの送信

パラメータ

パラメータ	説明
変換タイプ	変換イベントのタイプ。可能な値: PURCHASE, SIGN_UP, INSTALL, RE_ENGAGE, UPDATE, TUTORIAL_COMPLETE, RESERVATION, ADD_TO_CART, ADD_TO_WISHLIST, LOGIN, CHECKOUT_INITIATED, SEARCH, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, CONTENT_VIEW, SHARE, INVITE, ADDED_PAYMENT_INFO, SPENT_CREDITS, RATED.
APP ID	(必須)
変換時間	(必須)
ハッシュ化されたデバイスID	(必須)
オペレーティングシステムタイプ	(必須)
デバイスIPアドレス	変換イベントが発生したときのデバイスのIPv4またはIPv6アドレス。
クリックウィンドウ	このイベントのクリックウィンドウ（日数）。注: クリックウィンドウはビュースルーウィンドウ以上でなければなりません。デフォルト: 14。可能な値: 1, 7, 14, 30.
レベル	このイベントに関連するレベル。
非Xエンゲージメント時間	変換前の最後の非Xエンゲージメントの時間。
非Xエンゲージメントタイプ
アイテム数	このイベントに関連するアイテムの数。
価格通貨	このイベントに関連する通貨（ISO 4217形式）。
価格マイクロ	このイベントに関連する価格額（マイクロ）。
ユーザー支払い情報	このイベントに関連するアプリにユーザーの支払い情報が保存されているかどうかを示すブール値。
ビュースルーウィンドウ	このイベントのビュースルーウィンドウ（日数）。デフォルト: 1。可能な値: 0, 1, 7, 14, 30.