コンバージョンAPI

コンバージョンAPIを使用したオフラインイベントの送信

コンバージョンAPIは、広告の測定、アトリビューション、ターゲティングで使用するためにオフラインイベントと実店舗イベントをMetaに送信するためのおすすめの統合方法です。このページでは、コンバージョンAPIダイレクトまたはパートナー統合でオフラインイベントを送信する方法を詳しく説明します。

前提条件

データセット

コンバージョンAPIを通じて送信されたオフラインイベントは、データセットに関連付けられている必要があります。

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

  • Meta Pixel (website events)
  • App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
  • Offline Conversions API (Meta’s legacy API for offline events)
  • Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_containerに対してGETを呼び出して、広告主のデータセットが統合されていて、コンバージョンAPIを使用してオフラインイベントを渡す資格があるかどうかを検出します。

アクセス許可

  • 広告主として直接統合を実施するには、前提条件とアクセス許可について説明しているこちらの指示に従ってください。

  • パートナープラットフォーム統合を実施するには、前提条件とアクセス許可について説明しているこちらの手順に従ってください。

設定

1. オフラインイベントパラメーターを設定する

広告主はこちらに記載されている設定を使用し、コンバージョンAPI経由で送信できる現在のパラメーターセットを参照してください。オフラインイベントとストアイベントの送信については、以下のフィールドをペイロードで共有することができます。

  • 広告主はすべてのオフラインイベントとストアイベントにaction_sourceをphysical_storeとして送信する必要があります。このパラメーターはすべてのサーバーイベントタイプに必要であることに注意してください。コンバージョンAPIを使用することで、自分が知る限りaction_sourceパラメーターが正確であることに同意するものとします。
  • コンバージョンAPIに必要なサーバーイベントフィールドはすべて尊重される必要があります。
  • 顧客情報パラメーター(オフラインとストアイベントの適切なパラメーターのリストは以下を参照)。
  • カスタムデータパラメーター(オフラインとストアイベントの適切なパラメーターのリストは以下を参照)。
  • オプションパラメーター: upload_tagパラメーターは、オフラインイベント用のレガシーAPIを使用している広告主向けのオフラインイベントアップロードでもサポートされています。

顧客情報パラメーター

次のリストには、通常オフラインイベントやストアイベントで使用される顧客情報パラメーターが含まれています。

パラメーター名 パラメーター ハッシュ化が必須かどうか

メールアドレス(1つまたは複数)

email

必須

電話番号(1つまたは複数)

phone

必須

ジェンダー

gen

必須

生年月日

db

必須

姓

ln

必須

名

fn

必須

都市

ct

必須

米国の州

st

必須

郵便番号

zip

必須

国

country

必須

Appleの広告ID

madid

必須

Androidの広告ID

madid

必須

サードパーティのユーザーID

external_id

強く推奨される

リード獲得広告からのリードID

lead_id

ハッシュ化しない

カスタムデータパラメーター

以下のセクションには、オフラインとストアイベントで使用される一般的なカスタムパラメーターが含まれています。より多くのカスタムデータフィールドについては、以下のリンクにあるコンバージョンAPIに使用可能なリストを参照してください。

パラメーター説明

event_time

型: 整数

必須

コンバージョンイベントのUNIXタイムスタンプ。

例:
'1456870055'


event_name
型: 文字列

必須

イベントのタイプ。

例:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other


store_data
型: JSONディクショナリー

任意

コンバージョンイベントに関する位置情報データを保存します。

例:

"store_data":
    {
        "store_page_id": 8576093908, // FBID
        "brand_page_id": 10236898932// FBID
    }

currency
型: 文字列

必須

このコンバージョンイベントで使用する3文字のISO通貨コード。Purchaseイベントでは必須。

例:
USD


value
型: ダブル

必須

コンバージョンイベントの値。Purchaseイベントでは必須。

例:
16.00


content_type型: 文字列

任意

有効な Advantage+ カタログ広告content_type。

例:
product


contents

型: JSON配列

任意カタログに広告が組み込まれている場合は必須。

必須: id、quantity


推奨: price、category、brand

必須: [ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]


推奨: [ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]


custom_data

型: JSONディクショナリー

任意

このコンバージョンイベントに関する情報。

例: {category: 'ICECREAM'}


order_id

型: 文字列

任意

オフラインイベントセット内の取引または注文を区別するためのユニーク識別情報。例えば、小売りの場合は領収書IDを指定できます。

例: ATN10001、123456


item_number

型: 文字列

任意

同じ注文や取引内のイベントを区別するユニークな識別情報。

例: 1、a



2. イベントの送信

新しいイベントを送信するには、このパス(https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN})からコンバージョンAPIにPOSTをリクエストします。

このエッジに投稿すると、Metaは新しいオフラインイベントとストアイベントを作成します。詳細については、以下の開発者ドキュメントを参照してください。

以下は、パラメーターがペイロードの全体的なスキーマにどのように適合するかについての概要です。

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

オフラインデータを掲載中の広告のパフォーマンスとうまく一致させるため、最適化結果をリアルタイムで、または毎日アップロードすることをおすすめします。

event_timeには、イベントをMetaに送信する最大7日前の時間を指定できます。dataのevent_timeが7日より前である場合、リクエスト全体に対してエラーが返され、イベントは処理されません。physical_storeをaction_sourceとしたオフラインと実店舗のイベントの場合は、コンバージョンから62日以内にトランザクションをアップロードしてください。

データをアップロードするとリアルタイムで処理されるため、たいていの場合、追加するとすぐに結果を確認できます。オフラインイベントデータのベストプラクティスについてのヘルプセンターのドキュメントを参照してください。

3. 重複除外の設定

コンバージョンAPIとMetaピクセルイベント全体で設定された重複除外とは異なり、オフラインイベントは他のオフラインイベントに対してのみ重複除外できます。サポートされている重複除外方法は、order_idベースまたはuserベースの2つです。重複除外は、イベントのペイロードにおける方法に基づいて、dataset_id、event_time、event_name、item_number、キーフィールドの組み合わせを使用します。

デフォルトの重複除外は、上記のフィールドの組み合わせでorder_idを使用します。order_idがペイロードに存在しない場合、ユーザーベースの重複除外ロジックを使用します。

例えば、order_idが同じevent_timeやevent_name、またはorder_idがないものの顧客情報パラメーターのセットが同じ2つの注文がある場合は重複イベントとみなされ、最初のイベントが実行されます。ユーザーベースの重複除外方法は、2つのペイロード内の同じ顧客情報パラメーターフィールドでのみ機能します。

重複除外期間は最大7日間です。

4. トラブルシューティングイベント

ペイロードデータの生成のためにペイロードヘルパーツールを使用することができます。

  • 該当する場合は、physical_storeアクションソースを選択してください。コンバージョンAPIを使用することで、自分が知る限りaction_sourceパラメーターが正確であることに同意するものとします。
  • Metaに送信されるイベントの情報を入力します。
  • これによりイベントペイロードが生成されます。このペイロードは、コンバージョンAPI統合のテンプレートとして使用できます。

テストにはイベントマネージャのテストイベントツールを使用します。テストイベントツールはウェブイベントとアプリイベントのみに対応しています。

参考情報

ビジネスヘルプセンターの記事