アプリイベントAPI

アプリイベントAPIを使用すると、アプリのインストールイベントや購入イベントなど、モバイルアプリやウェブページで発生したアクションをトラッキングできます。これらのイベントをトラッキングすることにより、広告パフォーマンスを測定し、広告のターゲット設定で使うオーディエンスを作成できます。

ビジネスメッセージのアプリイベントのトラッキングについては、MessengerプラットフォームのドキュメントのビジネスメッセージのアプリイベントAPIをご覧ください。

仕組み

アプリイベントには、次の3つのタイプがあります。

• 自動的にログ記録されるイベント - Facebook SDKは、アプリのインストール、アプリのセッション、アプリ内購入を自動的にログ記録します。
• 標準イベント - Facebookで作成される一般的なイベント。
• カスタムイベント - アプリの開発者が作成するアプリ固有のイベント。

アプリイベントは、次の3つの要素で構成されます。

1. name - イベントを説明する必須の文字列です。アプリイベントがAnalyticsに送信されると、この名前がイベントログに表示されます。
2. valueToSum - Analyticsが同じ名前の他のアプリイベントのValueToSum値に追加する任意の値です。
3. parameters - アプリイベントに含める任意の値です。

使用できるイベント名の数は最大で1,000です。注: この上限に達すると、新しいイベントタイプはログ記録されなくなります。また、この上限を超過すると、ログで100 Invalid parameterのエラーが表示される場合があります。ただし、使わなくなったイベントを無効化することができます。イベントの上限について詳しくは、よくある質問をご覧ください。

開始する前に

以下の情報が必要です。

• 広告主ID、Androidデバイスの広告ID、またはAppleデバイスの広告識別情報(IDFA)。
• 認証するためのFacebookのアプリアクセストークン。アプリアクセストークンをクライアントに保管しないでください。

アプリのインストール

POSTリクエストをサーバーから/{app-id}/activitiesエンドポイントにapplication_tracking_enabledパラメーターとadvertiser_tracking_enabledパラメーターを指定して送信します。

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "success": true
}

警告

• 1人のユーザーにつき1回のインストールのみを報告してください。IDレベルとユーザーレベルでIDの重複を特定できる場合は、重複を除外してください。

利用できるパラメーターのリストについては、Facebookのアプリアクティビティリファレンスガイドをご覧ください。

広告トラッキングを有効にする

advertiser_tracking_enabledフィールドは、ユーザーのデバイス上で広告トラッキングが有効になっているかどうかを指定します。無効の場合は0、有効の場合は1を設定します。広告トラッキングを最適化またはコンバージョンに使用できるかどうかを判断できるようにするため、このデータを取得してFacebookに送信してください。Metaはデータに関するポリシーに準拠している(パートナーからMeta以外でのユーザーアクティビティに関する)イベントデータを使用します。これには、広告レポート、不正行為の検出、製品(Metaの広告配信製品を含む)の改善という目的が含まれます。しかし、ユーザーの広告をパーソナライズするために個人に関するデータを使用することは制限しています。iOS 6より前のバージョンが実行されているデバイスでは、このパラメーターをデフォルトの1にする必要があります。

ユーザーのトラッキングのステータスを調べるには、AppleのAdSuppportのリファレンスをご覧ください。

次のコードスニペットは、トラッキング対応フラグの値を取得する方法を示しています。

トラッキング対応フラグの現在の設定は、Settings.shared.isAdvertiserTrackingEnabledプロパティで確認できます。

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

広告トラッキングを無効にする

どのようなアプリにも、ユーザーがアプリ内で広告トラッキングをオフにできる設定を含めることができます。Facebookでは、パートナーに自社のSDKにこのオプションを含めることと、ユーザーの選択内容をインストールイベントやコンバージョンイベントと併せてFacebookに報告するよう要請しています。Facebookではインストールやコンバージョンのイベントを使用して広告レポートを作成していますが、これらのイベントを広告の最適化で使用することは制限しています。ユーザーの設定は、アプリの起動を繰り返しても持続しなければなりません。

コンバージョンイベント

POSTリクエストを/{app-id}/activitiesエンドポイントに、eventをCUSTOM_APP_EVENTSに設定し、advertiser_tracking_enabledをそれぞれの個別のイベントに設定して送信します。advertiser_idまたはattributionパラメーターは必須です。

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

成功すると、アプリは次の応答を受け取ります。

{
  "success": true
}

アトリビューション

attributionエンドポイントは、過去28日以内の広告でのクリック数に基づいて、インストール数とコンバージョン数を返します。広告マネージャは、1日のビュースルーと28日のクリックスルーのアトリビューションモデルを使用しています。インサイトは、インストールやコンバージョン時間ではなく、インプレッションまたはクリック時間に基づいています。これは、自分のレポートとFacebook広告マネージャのレポートを比較する際に覚えておく必要があります。通常の広告クリックのアプリイベントの取得に加えて、以下のシナリオも考慮してください。

• ビュースルーのアトリビューションの取得 - consider_views=TRUEを設定すると、アカウントセンターアカウントが28日以内に広告をクリックしていない場合は、広告インプレッションの1日以内に発生したインストールのアトリビューションデータを返します。返される応答ではis_view_through=TRUEとなり、view_timeがclick_timeと置き換えられます。他のすべてのアトリビューションは、広告のクリックアトリビューションデータと同様です。

• クロスキャンペーンの取得 - 広告主は、アプリイベントにつながったすべての広告のパフォーマンスをトラッキングできます。Facebookは、キャンペーンの目的がモバイルアプリインストールまたはモバイルアプリエンゲージメントに設定されていない限り、イベント取得リクエストを広告キャンペーンから送信します。このデータは、広告主が広告の[モバイルアプリイベントのトラッキング]フィールドにアプリを追加している場合にのみ表示されます。

• ユーザー事例 — ユーザーをモバイルサイトに誘導するページ投稿広告またはウェブサイト広告のクリックによって生成されたインストールをトラッキングしたいクライアントは、広告マネージャでそのように設定することができます。その場合Facebookは該当するアプリのインストールを取得します。

• クロスデバイスの取得 - 複数のプラットフォームに広告を掲載している広告主は、これらの複数プラットフォームの広告がきっかけとなったアプリのインストールのデータを表示できます。

• 使用例 — ユーザーがiPhoneでアプリの広告をクリックし、同じアプリをiPadでインストールしたとします。この場合、Facebookは、広告のターゲット設定に関係なく、iPadでのアプリのインストールをiPhone広告にアトリビューションできます。

詳細マッチング

詳細マッチングを使用してFacebookに顧客データを送信すると、Facebookはそのデータにより、広告に反応してアクションを起こしたアカウントセンターアカウントをより正確に特定することができます。Facebookはこのデータを使ってコンバージョンイベントを顧客とマッチングすることで、広告を最適化して、より多くのリマーケティングオーディエンスを構築できます。

udパラメーターに顧客のトラッキングに使用できるパラメーター(顧客のメールアドレスや電話番号など)を指定して、POSTリクエストを/{app-id}/activitiesエンドポイントに送信します。顧客データはすべてハッシュ化されていなければなりません。そうでないとFacebookにより無視されます。必ず個々のイベントごとにadvertiser_tracking_enabledを設定してください。

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "success": true
}

すべてのユーザーデータはFacebookに送信する前に、SHA256でハッシュ化されたタグを付ける必要があります。Facebookはハッシュ化されていないデータを無視します。

重複除外

アプリイベントでは、ウェブイベントに対するものと同じ重複除外機能が適用されます。このロジックは、event_idおよびevent_nameフィールドに基づく重複除外を使用します。event_idパラメーターは、類似したイベントを区別するための識別情報です。イベントIDが不正確だと、コンバージョンが誤って重複除外され、コンバージョンレポートとキャンペーンパフォーマンスにさらに影響が及ぶ可能性があります。

範囲拡大されたデバイス情報

画面の幅や高さなどのデバイス情報を、/{app-id}/activities?extinfoを使用してアプリイベント呼び出しで送信します。値はコンマで区切り、/application/activitesリファレンスガイドでインデックス化されている順番で指定する必要があります。extinfoを使用する際は、すべての値が必須です。

• Androidの場合、versionはa2でなければなりません
• iOSの場合、versionはi2でなければなりません

リファレンス

• ApplicationActivitiesパラメーター
• Android開発者ドキュメント - 表示指標
• Android開発者ドキュメント - 外部ストレージ
• Apple開発者ドキュメント - 表示指標
• Apple開発者ドキュメント - 外部ストレージ
• Apple開発者ドキュメント - スクリーンサイズ

モバイルCookieを取得する

アプリイベントは、advertiser_idと関連付けることをおすすめします。しかし、AndroidデバイスとiOS 6より前のiOSデバイスの場合、attributionパラメーターをデバイスのモバイルCookieに設定して使用することもできます。

注: モバイルCookieは、ユーザーまたはデバイスのアトリビューションから派生するものではありません。これらのCookieは永続的でなく、頻繁に更新されるように設計されています。広告のリターゲティングにはモバイルCookieを使用しないでください。

Android

Cookieは、22文字のランダムな英数字文字列です。

ContentProviderを使用して、FacebookアトリビューションIDを取得します。

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

対象とするAndroidアプリの広告IDを取得することも必要です。

iOS

モバイルCookieは、Facebook iOSアプリがCFUUIDCreateStringを使用して作成する、128ビットのUUIDの文字列表現です。

次のように、Cookie IDとIDFAの両方を取得し、それらを識別情報としてFacebookに送信します。

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

X-Forwarded-For HTTPヘッダー

POSTリクエストがサーバーやプロキシなどから一元的に行われ、基本的にはサーバー間呼び出しである場合は、場所とデバイス情報を確実に正確なものにするため、X-Forwarded-For HTTPヘッダーが必要です。送信されるアプリイベントの各リクエストで、デバイスのIPアドレス(IPv4またはIPv6形式)を、X-Forwarded-For HTTPヘッダーのパラメーターで送ります。これにより、Facebookはadvertiser_idと正しいIPアドレスをペアリングして、それをFacebookのプラットフォームで使用することができます。

IPv6の例

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

IPv4の例

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

テスト

1. イベントマネージャを開きます。
2. ページの左側にある[データソース]アイコンをクリックします。
3. データの名前とIDを選択します。
4. [イベントのテスト]をクリックして、アプリとしてチャネルを選択してください。
5. グラフAPIツールでAE-APIリクエストを送信してください。
6. インタラクションはすぐに[イベントのテスト]タブに表示されます。

不一致

クライアントがモバイル測定パートナーのレポートとFacebookレポートを比較したときに不一致が見られる場合は、以下の項目を確認してください。

Facebookレポートのインストール数がMMPよりも少ない場合

• FB SDKが適切に統合されているかどうか。
• クライアントが間違ったアプリIDを使用していないか。

Facebookレポートのインストール数がMMPよりも多い場合

• アトリビューションウィンドウが同じになっているかどうか。通常、Facebookではモバイル測定パートナーよりも幅広いアトリビューションウィンドウを設けています。
• MMP SDKが適切に統合されているかどうか。
• クライアントが間違ったアプリIDを使用していないか。
• 不一致が見られるのはiOS 7のみかどうか。MMPがデバイスからAppleの広告ID (IDFA)を受け取り、それをFBに正しく渡しているかどうか。

リファレンス

アプリアクティビティExtinfo

アプリの追加情報の詳細については、/application/activitesリファレンスガイドをご覧ください。

ユーザーデータパラメーター

標準イベント名

標準イベントのパラメーター

参考情報

• アプリイベント
• アプリイベントのベストプラクティス
• エラーのハンドリング
• GDPRの遵守
• Facebook広告マネージャ
• Facebookアプリダッシュボード