コンバージョンAPIのセットアップ

前提条件

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

コンバージョンAPIを使用するための第一条件は、開発者アカウントと広告APIアクセスを持っていることです。プロセスは広告APIの概要ガイドに記載されています。次の点に注意してください。

手順1:開発者アカウント

開発者アカウントを申請する際には、**Essentialアクセス**を申請することですぐに承認が得られます。コンバージョンAPIを使用する場合にはElevatedアクセスは必要ありません。また、Elevatedアクセスでは追加の審査期間が必要となります。アクセスレベルのガイドラインを参照してElevatedアクセスが必要だと判断した場合を除き、Essentialアクセスを選択してください。
注: 自社の公式Twitterユーザー名を使用して開発者アカウントを作成し、広告APIアクセスを申請することを強くおすすめします。開発者アカウントが開発者のユーザー名に関連付けられている場合、それらの認証情報を移管する方法はありません。継続的な管理のためには企業アカウントにユーザー名を関連付け、必要に応じて複数ユーザーログインを使用することをおすすめします。それ以外の場合は、少なくともデフォルト以外の設定（ヘッダー画像、アバター、プロフィールの説明、プロフィールのURL）でアカウントを設定し、二段階認証を使用してください。

手順2:広告APIアプリケーション

広告APIアプリケーションに正しいアプリIDを含めるようにしてください。アプリIDは [開発者ポータル} の [プロジェクトとアプリ] にあります。例: 16489123
[広告APIアプリケーション] の「広告APIをどのように使用する予定ですか？」で [コンバージョンAPI] を選択します。
新たに作成したアプリケーションの場合、広告APIアクセスは少数のアクセストークンに制限されます。デフォルトの制限を超えてアクセス権を引き上げる必要がある企業の場合は、ドキュメント「アクセス権の引き上げ」を参照し、オンボーディング担当者かアカウントマネージャーまで連絡してください。

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

すでに使用しているアクティブな広告APIアプリケーションがある場合は、アプリケーションと既存のアクセストークンの両方をコンバージョンAPIに使用できます。

アクセストークン

広告APIアプリケーションを所有しているユーザーのユーザー名のユーザーアクセストークンは、開発者ポータルから直接生成、取得できます。自身のTwitterユーザー名で使用することが想定されているため、これは「パーソナルアクセストークン」と呼ばれています。認証と開発者ポータルに関する詳しい情報はこちらに掲載されています。
広告APIアプリケーションを所有していないユーザーのユーザー名のユーザーアクセストークンは、3レッグOAuthフローを使用して生成する必要があります。3レッグOAuthでは、次のいずれかの方法でアクセストークンを生成できます。
コンバージョンAPIで使用するすべてのユーザートークンは、アクセスレベルがAD_MANAGERかACCOUNT_ADMINのユーザーに使用する必要があります。アクセスレベルはauthenticated_user_accessエンドポイントから確認できます。
注: トークンそのものは、（上記の手順に従って作成した後）アクセスレベルがAD_MANAGERまたはACCOUNT_ADMINではないユーザーと共有して使用できます。

手順

コンバージョンAPIイベントの作成

コンバージョンAPIを使用するには、広告マネージャーに新しいコンバージョンイベントを作成するか、作成済みでTwitterピクセルに使用している既存のイベントを使用する必要があります。ピクセルとコンバージョンAPIイベント間の重複を排除するには、ピクセル用に作成した既存のイベントを使用する必要があります。

オプション1: 広告マネージャーで既存のコンバージョンイベントを使用する

Twitterピクセルですでに使用している既存のイベントを使用することは可能ですが、そのイベントからイベントIDを取得する必要があります。同じイベントでピクセルとコンバージョンAPIの両方を使用する場合は、ピクセルコードスニペットとコンバージョンAPIリクエスト（conversion_id）の両方で重複排除キーを使用し、同じイベントでピクセルとコンバージョンAPI間のイベントの重複を排除してください。セクションdを参照してください。詳細については、「イベントと重複排除のテスト」を参照してください。

オプション2: 広告マネージャーで新しいコンバージョンイベントを作成する

イベントを作成する前に、イベントマネージャーでイベントソースをあらかじめ作成しておくことが重要です。アカウントにイベントソース（Twitterピクセル）が追加されていることを確認するには、[イベントマネージャー] にアクセスして、左側のメニューにTwitterピクセルがあるか確認してください。

まだイベントソースを追加していない場合は、以下の手順に従ってイベントソースを作成してください。

ads.twitter.comにアクセスします。
左上の [ツール] セクションに移動し、[イベントマネージャー] をクリックします。
左側のサイドバーにTwitterピクセルイベントソースをまだ追加していない場合は、[Add an event source（イベントソースを追加）] の右上にある [Add event source（イベントソースを追加）] を選択します。
1. [ピクセルID] がTwitterピクセルイベントソースのIDです。

これでイベントソースとピクセルIDができました。追跡対象のコンバージョンイベント用のイベントソース内にイベントを作成する必要があります。

Twitterピクセルイベントソース内で、右側にある [Add events（イベントを追加）]を選択します。
[コンバージョンAPI] で [インストール] を選択します。
APIで使用するこのイベントの [ピクセルID] と [イベントID] が表示されます。
1. [イベントID] がイベントのIDです。
[保存] をクリックすると、コンバージョンイベントが作成され、使用できるようになります。

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

現在、コンバージョンイベントの識別子として、少なくともTwitterクリックID（twclid）かメールアドレスのいずれかが必要です。

1.TwitterクリックID識別子の準備

可能な限り、コンバージョンリクエストには常にクリックIDを含めることをおすすめします。メールを利用できる場合、クリックIDは不要です。どちらか一方だけでも十分ですが、両方使用することでマッチ率が上がります。

ユーザーがアクセス先のウェブサイトに移動した後でクリックIDを利用できる場合は、クエリ文字列パラメータtwclidから解析する必要があります。

基本的なJavaScriptコードの例:

var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Recommended next steps: Logging, insert into local storage

推奨事項は以下のとおりです。

URLクエリパラメータにtwclid値がある場合は、必ず解析します。
関連するフォームフィールドまたはコンバージョンイベント情報とともにデータを格納します。

クリックIDをコンバージョンイベントとワークフロー情報に紐づけることで、バッチ処理やアルゴリズムなどのシナリオに対応し、複数のウェブサイトナビゲーションフローに基づいてコンバージョンイベントを分析、作成し、一括アップロードを実行できるようになります。

イベントソースURLはURLエンコードし、イベントをトリガーしたウェブページを表す必要があります。

2.メール識別子の準備

サポート対象の顧客照合フィールドは送信できますが正規化し、必要に応じてプライバシー保護のためにハッシュ化してください。

情報はSHA256を使用してsaltなしでハッシュ化する必要があります。

例: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

正規化とハッシュ化に関するガイドラインを以下にまとめました。

顧客照合フィールド	正規化	ハッシュ化の要否
メールアドレス	先頭と末尾のスペースを削除	必要（SHA256）

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

`POST: version/measurement/conversions/:pixel_id`

特定の広告アカウントのコンバージョンイベントを送信します。応答コードで成功（HTTP 200 OK）を確認する必要があります。エラーコードが返された場合に備えて、再試行メカニズムと基本的なログインを用意しておくことをおすすめします。

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

リクエストの例（読みやすくするために書式設定済み）

twurl -H 'ads-api.twitter.com' -X POST '/11/measurement/conversions/o9d7n' --data '
{
   "conversions":[
      {
         "conversion_time":"2022-02-18T01:14:00.603Z",
         "event_id":"o9d2g",
         "identifiers":[
            {
               "twclid":"23opevjt88psuo13lu8d020qkn"
            },
            {
               "hashed_email":"63dc92389e3326e3ee3d7e6e715fda270977b9d293d97760f89105c86b3e2f11"
            }
         ],
         "value":"250.00",
         "number_items":3,
         "conversion_id":"23294827",
         "description":"Pet supply purchases",
         "contents":[
            {
               "content_id":"1",
               "content_price":50.00,
               "num_items":1,
            },

            {
               "content_id":"2",
               "content_price":100.00,
               "num_items":2,
            }         ]
      }
   ]
}' --header 'Content-Type: application/json'

応答の例

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

レート制限

レート制限は、15分の時間枠で1つのアカウントにつき6万イベントまでです。

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

イベントごとに正しいコンバージョンデータを送信できるようにするための、ユーザーアクション（ロギング）のインストルメント化
関連するプライバシーの選択肢を使用したユーザーのコンバージョンイベントを除外するのに必要なあらゆるロジック（広告主のウェブサイトでユーザーが個人情報のトラッキングや販売をオプトアウトした場合など）
イベントのキャプチャとコンバージョンの送信を目的とした、イベントトリガーおよびページとの統合

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

イベントのテスト

イベントでコンバージョンイベントを正常に受信すると、そこから12～24時間以内に広告マネージャーの [コンバージョントラッキング] ページで [Single event web tag（単一イベントウェブタグ）] のステータスに「TRACKING」と表示されます。コンバージョンAPIを使用してコンバージョンを送信する、実施中のキャンペーンには影響しません。

また、次の方法でもタグIDごとのコンバージョンイベントのアナリティクス結果を確認できます。

広告マネージャーのデータエクスポート（ウェブサイトコンバージョントラッキングヘルプページのアナリティクス）
広告APIを使用したデータのエクスポート（segmentation_type=CONVERSION_TAGS）

ピクセルとコンバージョンAPI間の重複

ピクセルリクエストとコンバージョンAPIリクエスト間のコンバージョンで重複を排除するために、重複排除キーとしてconversion_idが用意されています。重複排除はSETレベルでのみ行われます。つまり、ピクセルリクエストとCAPIリクエスト間の重複を排除するには、広告主は、同じconversion_idだけでなくピクセルリクエストとCAPIリクエストの両方で同じSETイベントを使用する必要があります。48時間以内に受信したイベントでのみ重複排除が行われます。