オフラインコンバージョンAPI

オフラインコンバージョンAPIは、オフラインコンバージョンイベントを送信したり、コンバージョンの前にMeta広告を表示またはクリックした顧客の数を確認したりするために使います。

開始する前に

このAPIを使用するには、以下が必要です。

1.Metaビジネスマネージャ

ない場合は、作成してください。

2.Meta App ID

マーケティングAPIへのアクセスに必要です。Metaアプリを作成するには以下のことを実行します。

• [ビジネスマネージャ] > [ビジネス設定]にアクセスします。
• [アプリ]を選択します。
• [新しいアプリを追加]をクリックし、指示に従います。

3.アプリレビューとアクセス許可

アプリレビューとアクセス許可に関するルールは、APIの実装方法によって異なります。

4.ビジネスマネージャのシステムユーザーとトークン

システムユーザーのアクセス権があれば、アプリはAPI経由でMetaにデータを送信できます。これを作成するには、次の手順に従います。

• [ビジネスマネージャ] > [ビジネス設定]にアクセスします。
• [システムユーザー]を選択します。
• [新しいシステムユーザーを追加]をクリックします。
• システムユーザーの役割として[管理者システムユーザー]を選択します。

Metaのデータにアクセスするには、アクセストークンが必要です。システムユーザーのアクセストークンを作成するには、次の手順に従います。

• [ビジネスマネージャ] > [ビジネス設定]にアクセスします。
• [システムユーザー]を選択します。
• システムユーザーを選択し、[新しいトークンを生成]をクリックします。
• アプリを選択し、[適用範囲]としてads_managementを選択します。

5.広告アカウント

Metaで広告キャンペーンを実施するには、広告アカウントが必要です。作成方法については、マーケティングAPIまたはビジネスヘルプセンターの「Metaビジネスマネージャのビジネス設定について」をご覧ください。

6.システムユーザーに広告アカウントへのアクセスを許可する

システムユーザーに広告アカウントへのアクセスを許可します。

• [ビジネスマネージャ] > [ビジネス設定]にアクセスします。
• [システムユーザー]を選択します。
• システムユーザーを選択し、[アセットを割り当てる]をクリックします。
• 広告アカウントを選択します。

7.オフラインイベントセット

これは、オフラインコンバージョンデータとともにアップロードされたファイルです。広告セットを作成する際に、イベントを正しくアトリビューションするために、tracking_specをオフラインイベントセットIDに設定します。これにより、イベントセットの作成、インポート時の統計情報の表示、ビジネスマネージャでの当該データの削除や変更ができるようになります。

以前の実装では、ビジネスマネージャレベルでオフラインイベントセットのCRUD操作を実行して、イベントセットをほかのオブジェクトおよびエンティティと共有することができました。

イベントデータのアップロード

オフラインイベントセットを作成し、イベントセットのデータをアップロードまたは表示するには、特定のアクセス権が必要です。このアクセス権は、これらのアクセス許可を広告アカウントに割り当てる場合にも必要です。次のいずれかであることが必要です。

• ビジネスマネージャ管理者
• オフラインイベントセットを作成した管理者システムユーザー
• オフラインイベントセットに関連付けられているad_accountの管理者

オフラインコンバージョンイベントセット、リファレンスをご覧ください。

1.オフラインイベントセットを作成する

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

HTTP POSTを実行します。

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

応答にはイベントセットidが含まれます。

{
  "id": <OFFLINE_EVENT_SET_ID>
}

パラメーター

2.広告アカウントにアクセス許可を割り当てる

広告アカウントにトラッキングおよび読み取りアクセス許可を割り当てるには

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

パラメーター

3.広告のトラッキングを設定する

tracking_specを更新すると、上書きされます。最初にGETを実行し、オフラインイベントセットの関連するStringを既存のtracking_specの末尾に付加します。広告管理を参照するか、広告マネージャを使用してください。例えば、次のように適切なトラッキングスペックを指定します。

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

広告のトラッキングスペックを更新するには、次のようにします。

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

パラメーター

4.オフラインイベントをアップロードする

コンバージョン後62日以内に取引をアップロードする必要があります。次のようにコンバージョンデータをアップロードします。

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

コンバージョンを送信するには、HTTP POSTを実行します。

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

パラメーター

同じバッチ内のすべてのイベントアップロードAPI呼び出しに同じupload_tagを使用して、それらをグループ化します。こうすると、イベントのアップロードをデバッグするのに役立ちます。複数のAPI呼び出しで行われるイベントアップロードにご利用ください。

data内にあるパラメーターは次のとおりです。

例えば、dataフィールドで次のように情報をアップロードできます。

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

同じバッチ内のすべてのイベントアップロードAPI呼び出しに同じupload_tagを使用して、それらをグループ化します。こうすると、イベントのアップロードをデバッグするのに役立ちます。複数のAPI呼び出しで行われるイベントアップロードにご利用ください。

一致キー

match_keysは、利用者とアトリビューションをマッチングするための識別情報のセットです。データの正規化とハッシュ化については、CRMデータにからのカスタムオーディエンスをご覧ください。SHA256のみがサポートされており、ハッシュ化されていないデータは受け入れられません。

応答:

エラーが発生すると、無効なエントリとその理由を含む例外が表示されます。エラーを修正するか、エラーのあるデータ行をスキップしてAPI呼び出しを再試行してください。

アップロードの統計情報を表示する

ビジネスマネージャの管理者、またはオフラインイベントセットを作成したシステムユーザーは、アップロードの統計情報を取得できます。オフラインイベントセットに関連付けられているad_accountの管理者も、このデータを読み取ることができます。

有効なエントリや一致するエントリなどのオフラインイベントセットに関する統計情報を表示するには

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

ビジネスマネージャのOffline Events Managerには、オフラインイベントの1日の内訳が表示されます。より正確な内訳を表示するには、次の呼び出しを行います。

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

パラメーター

オフラインカスタムコンバージョンの作成

現在、オフラインカスタムコンバージョンはバックフィルを行いません。カスタムコンバージョンを作成する前に行われたイベントのアップロードからのデータは、アトリビューションされません。オフラインカスタムコンバージョンデータを広告配信の最適化に使用することはできません。カスタムコンバージョンリファレンスをご覧ください。

オフラインイベントを使用してカスタムコンバージョンを作成するには、POSTを実行します。

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

パラメーター:

成功すると、次の応答が返されます。

{
  "id": <CUSTOM_CONVERSION_ID>
}

カスタムデータによる測定

custom_dataフィールドを使用して、コンバージョンをカウントするかどうかを後で判断するルールを作成できます。これはオフラインカスタムオーディエンスに似ています。広告アカウントあたりのカスタムコンバージョンの最大数は40です。

例えば、custom_dataを使用してアップロードに製品カテゴリを含めるには、次のようにします。

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

次に、custom_data.{YOUR_CUSTOM_PARAM}を使用して、カスタムコンバージョンルールを作成します。

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

パートナーのオフラインコンバージョン

オフラインコンバージョンイベントをクライアントの広告にアトリビューションするには、次の手順に従います。これらの手順のほとんどにおけるAPI呼び出しは、自分のオフラインイベントセットとキャンペーンを管理する場合と同じです。

1. パートナー - オフラインイベントセットを作成する
2. パートナー - イベントセットをクライアントのビジネスマネージャと共有する
3. クライアント - 広告アカウントにオフライントラッキングアクセス許可を割り当てる
4. クライアント - 広告にオフライントラッキングを設定する
5. パートナー - オフラインイベントをアップロードし、統計情報を表示する
6. パートナー - クライアントの広告インサイトを表示する

これらの手順は、クライアントの広告アカウントでパートナーまたはエージェンシーの権限をどのように設定するかによって異なります。

• クライアントのすべての広告アカウント、イベントセット、その他のアセットを所有している場合。
• クライアントのアセットに対して特定のアクションを実行する権限がある場合。

これらの権限を設定するには、ビジネスマネージャのアセットをご覧ください。

パートナー - イベントセットを共有する

イベントセットをクライアントのビジネスマネージャと共有します。クライアントは広告トラッキングにイベントセットを使用できるようになります。

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

パラメーター

クライアント - 広告アカウントにオフライントラッキングアクセス許可を割り当てる

パートナーが作成したオフラインイベントセットをクライアントと共有します。広告と広告アカウントのトラッキングを有効にするには、ビジネスマネージャの管理者、またはオフラインイベントセットを作成した管理者システムユーザーである必要があります。オフラインイベントセットに関連付けられている広告アカウントの管理者である場合も、これを行うことができます。このAPI呼び出しを行うには、呼び出し内のビジネスがオフラインイベントセットにアクセスできる必要があります。

この呼び出しにより、オフラインイベントのトラッキングと表示のアクセス許可を広告アカウントに割り当てることができます。

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

パラメーター

外部IDを提供する

顧客を表す独自の外部IDを提供し、それを特定の利用者とマッチングするケースがあるかもしれません。これを行うには、以下のガイドラインに従ってextern_idを使用してください。

マッチング処理を行ったデータパートナーは、パートナーIDをネームスペースIDとして使用し、extern_idをtpidとして使用できます。

match_keysのみを指定する

Metaでは、match_keysを使って、シェアされたコンバージョンデータをMetaユーザーとマッチングできるかどうかの判定を試みます。match_keysを指定する場合、同時にnamespace_idパラメーターも指定することはできません。

match_keysとextern_idの両方を指定する

Metaでは、match_keysを使ってMetaの利用者を検索し、{dataset_id, extern_id}から{facebook_user_id}へのマッピングの転送を試みます。match_keysとextern_idを指定する場合、同時にnamespace_idパラメーターも指定することはできません。

extern_idのみを指定する

すでにmatch_keysとextern_idが含まれるデータを送信した場合、Metaは{dataset_id, extern_id}を使って{facebook_user_id}を取得します。

namespace_idを指定する

namespace_idパラメーターは、API呼び出し全体に適用されます。これを使用して、ビジネスまたはパートナーのプロフィールIDによってアクセスできる(または所有されている)別のオフラインイベントセットを参照できます。すでにmatch_keysとextern_idが含まれるデータを送信した場合、Metaは{namespace_id, extern_id}を使って{facebook_user_id}を取得します。データの1行につき1つのextern_idのみを指定してください。

インサイトとアトリビューション

利用者が表示またはクリックした広告にアトリビューションするオフラインイベントを表示します。オフラインコンバージョンは1日以上経過してからアトリビューションされます。つまり、アトリビューションウィンドウを28d_viewまたはaction_attribution_windows=['28d_view']'に設定する必要があります。そうしないと、レポートにコンバージョンが表示されません。インサイトAPIとインサイトガイドをご覧ください。

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

パラメーター

結果は次のようになります。

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

例: 次のようにして、アトリビューションを表示します。

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

結果は次のようになります。

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

米国のユーザーに適用されるデータ処理オプション

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

詳しくは、データ処理オプションをご覧ください。