アプリイベント用のコンバージョンAPI

コンバージョンAPIを使用すると、広告主は複数のソースではなく単一のエンドポイントでウェブ、アプリ、実店舗、ビジネスメッセージイベントをMetaに送信できるようになります。この統合により、データセットを使用することで広告主のテクノロジースタックが簡素化され、Metaイベントマネージャ内でのより包括的なビューを実現できます。

このドキュメントは、アプリイベントをコンバージョンAPIに統合するためのガイダンスを提供しています。

前提条件

1.データセット

コンバージョン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}/is_consolidated_containerに対してGET呼び出しをして、広告主のデータセットが統合されていて、コンバージョンAPIでアプリイベントを渡せるかどうかを検出することができます。

2.アクセス許可

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

設定

コンバージョンAPIへのアプリイベントの送信

a.データセットIDとアプリIDのリンク

イベントマネージャでは、次の2つの方法でアプリとデータセットをリンクすることができます。

[データソース]タブを選択し、アプリの[設定]タブを見つけてリンクを実行する。
アプリの[概要]タブで[データソース]タブを選択し、[すべてのアクティビティ]セクションの[データセットへのリンク]ボタンを使用します。

リンクが完了すると、データセットにリンク済みのアプリが含められます。

b.必須フィールド

こちらから、コンバージョンAPI経由で送信可能な現在のパラメーターセットを参照することができます。アプリイベントを送信する場合、以下のserver_event fieldsをペイロードで共有することができます。

パラメーターaction_sourceは、アプリイベントの値appを含んでいる必要があります。
重複除外のセットアップケースにはevent_idが必要です。
app_dataフィールド
user_dataフィールド
custom_dataフィールド

アプリデータフィールド

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

顧客情報パラメーター

パラメーター	説明
`anon_id` 文字列	ハッシュ処理なし。インストールID。このフィールドは、固有のアプリケーションインストールインスタンスを表しています。
`madid` 文字列	ハッシュ処理なし。モバイル広告主ID、Androidデバイスの広告ID、またはAppleデバイスの広告識別情報(IDFA)。

カスタムデータ

パラメーター	説明
`description` 文字列	任意。文字列、イベント説明、カスタム。
`level` 文字列	任意。文字列、ゲームのレベル、カスタム。
`max_rating_value`	任意。評価スケールの上限。例えば、5つ星スケールの5。カスタム。
`success` ブーリアン	任意。はい: `1`、いいえ: `0`、カスタム。

要約すると、コンバージョンAPIを使用して共有されたアプリイベントには、以下のデータパラメーターが必要になります。

action_source: ‘アプリ’に設定する必要があります。(コンバージョンAPIを使うことで、action_sourceパラメーターが自分の知る限り正確であることに同意するものとします)
event_id: 重複除外の設定に必須です。詳細は「複数チャネルの重複除外を設定する」セクションをご覧ください。
advertiser_tracking_enabled
application_tracking_enabled
extinfo

以下はextinfoの例です。以下のサブパラメーターがすべて入力され、順番通りになっていることを確認してください。何か欠けている場合は、空の文字列をプレースホルダーとして使用してください。

サブパラメーター名	必須	データ型	例
消滅情報バージョン	はい	文字列	`i2` (バージョンはAndroidの場合はa2、iOSの場合はi2でなければなりません)
アプリパッケージ名	いいえ	文字列	`com.facebook.sdk.samples.hellofacebook`
簡易バージョン	いいえ	文字列	`1.0`
長いバージョン	いいえ	文字列	`1.0 long`
OSバージョン	はい	文字列	`13.4.1`
デバイスのモデル名	いいえ	文字列	`iPhone5,1`
ロケール	いいえ	文字列	`En_US`
タイムゾーンの略語	いいえ	文字列	`PDT`
携帯電話会社	いいえ	文字列	`AT&T`
画面の幅	いいえ	文字列	`320`
画面の高さ	いいえ	文字列	`568`
画面密度	いいえ	文字列	`2`
CPUコア	いいえ	文字列	`2`
外部ストレージサイズ	いいえ	文字列	`13`
外部ストレージサイズのフリースペース	いいえ	文字列	`8`
デバイスのタイムゾーン	いいえ	文字列	`USA/New York`

c.複数のチャネルの重複除外を設定する

コンバージョンAPIの統合とSDK、MMP、アプリイベントAPIを含むアプリイベントとのほかのすべての統合間の重複イベントトラフィックを削除するには、重複除外メカニズムが必要になります。

アプリイベントでは、ウェブイベントに対するものと同じ重複除外機能が適用されます。このロジックでは、フィールドevent_idとevent_nameベースの重複除外(コンバージョンAPIとSDK / App Events APIイベントは同じevent_id)を利用します。event_idパラメーターは、類似するイベントを一意に区別できる識別子です。イベントIDが不正確だと、コンバージョンが誤って重複除外され、コンバージョンレポートとキャンペーンパフォーマンスにさらに影響が及ぶ可能性があります。

重複除外の設定を実装するには、以下の開発者ドキュメントを参照してください。

以下は、カスタムイベントの記録方法の例です。記録するには、イベントの名前をiOS SDKのAppEvents.Nameとして渡します。

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

アプリのインストールイベントでは、過去90日間のウィンドウに1つのインストールしかアトリビューション分析されていないことを確認する重複除外メカニズムがすでに存在しています。Metaでは最初のイベントを維持し、後のイベントはそのアクションソースに関係なくドロップします。インストールイベントに関連するアプリイベントの重複除外を実装する必要はありません。

d.イベントの送信

新しいイベントを送信するには、このパス(https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN})からコンバージョンAPIにPOSTをリクエストしてください。このエッジにPOSTリクエストを送信すると、Metaは新しいアプリサーバーイベントを作成します。詳細については、以下の開発者ドキュメントを参照してください。

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

** トラブルシューティング**

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

該当する場合にはappアクションソースを選択します
Metaに送信されるイベントの情報を入力します
これによりイベントペイロードが生成されます。このペイロードは、コンバージョンAPI統合のテンプレートとして使用できます

テストにはイベントマネージャのテストイベントツールを使用します。