應用程式事件 API

應用程式事件可讓您追蹤發生在行動應用程式或網頁內的動作，例如應用程式安裝和購買事件。透過追蹤這些事件，您可以衡量廣告成效，並針對廣告目標設定建立廣告受眾。

如需追蹤企業商家訊息功能應用程式事件的資訊，請參閱 Messenger 開放平台文件中的企業商家訊息功能應用程式事件 API。

運作方式

有三種類型的應用程式事件：

• 自動記錄的事件 - Facebook SDK 會自動記錄應用程式安裝、應用程式連線階段和應用程式內購買。
• 標準事件 - Facebook 已為您建立的熱門活動。
• 自訂事件 - 針對應用程式特別建立的事件。

應用程式事件包含三個部分：

1. name - 說明事件的必要字串。當應用程式事件傳送至分析工具時，這個名稱會顯示在事件記錄中。
2. valueToSum - 分析工具從相同名稱的應用程式事件加到其他加總值的選用數值。
3. parameters - 應用程式事件所包含的選用數值。

最多可有 1,000 種不同的事件名稱。注意：一旦達此上限，就不會記錄任何新的事件類型，且若超過此限制，記錄時會發生 100 Invalid parameter 錯誤。不過，您可停用已過時事件。如需有關事件限制的更多資訊，請參閱常見問題。

準備工作

必備資料：

• 您的廣告主編號（亦即 Android 裝置的廣告編號或 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
}

注意事項

• 針對每位用戶只能回報一次安裝。編號和用戶層級的編號可重複。

請造訪我們的應用程式活動參考指南，以取得可用的參數清單。

啟用廣告追蹤

advertiser_tracking_enabled 欄位指定用戶是否已在其裝置上啟用廣告追蹤。設定為 0 表示停用，設定為 1 表示啟用。您應擷取此資料並將其傳回 Facebook，以確定廣告追蹤是否可用於最佳化或轉換。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 將傳回 1 天內因廣告曝光所發生安裝的歸因資料，但前提是帳號管理中心帳號未在 28 天內點擊廣告。傳回的回應將為 is_view_through=TRUE 且 view_time 將取代 click_time。其他所有歸因資料與廣告點擊歸因資料相同。

• 跨行銷活動歸因資料 - 廣告商能追蹤所有歸因於某應用程式事件的廣告成效。Facebook 傳送來自廣告行銷活動的事件的歸因資料，前提是行銷活動目標不能設為行動應用程式安裝或行動應用程式互動。只有當廣告商在廣告的「行動應用程式事件追蹤」欄位中加入該應用程式，才會顯示這項資料。

• 用戶案例 - 如果粉絲專頁貼文廣告或網站點擊廣告將用戶資料傳送至行動網站，而您的客戶想要追蹤因廣告產生的安裝次數，便可在廣告管理員中進行上述操作，Facebook 會歸因相關的應用程式安裝次數。

• 跨裝置歸因資料 - 在多個平台有應用程式的廣告商可以查看在多個平台上因廣告驅動的應用程式安裝次數的資料。

• 使用案例 - 用戶點擊 iPhone 應用程式廣告，接著在 iPad 安裝相同應用程式。雖然廣告目標設定不同，但還是可將此 iPad 應用程式安裝歸因於該 iPhone 廣告。

進階配對

進階配對可讓您將顧客資料傳送至 Facebook，然後我們將使用此資料更準確地判斷哪些帳號管理中心帳號對您的廣告採取行動回應。透過這項資料，Facebook 可將轉換事件與顧客配對，以最佳化您的廣告並建立更多的再行銷廣告受眾。

傳送 POST 要求至 /{app-id}/activities 端點，並將 ud 參數設為可協助追蹤顧客的參數，例如顧客的電子郵件或電話號碼。所有顧客資料都必須經過雜湊處理，否則 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
}

所有用戶資料都必須經過 SHA256 雜湊處理，才能傳送至 Facebook。Facebook 將忽略未經雜湊處理的資料。

刪除重複項目

針對應用程式事件，我們套用與網路事件相同的刪除重複項目功能。該邏輯利用以欄位 event_id 和 event_name 為基礎的刪除重複項目。event_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 裝置，也可以使用設為裝置行動 Cookie 的 attribution 參數。

注意：行動 Cookie 並非衍生自任何用戶或裝置屬性。這些 Cookie 並非持續性，且設計為經常重新整理。請勿將行動 Cookie 用於再次鎖定廣告。

Android

此 Cookie 是含有 22 個字元的隨機英數字元字串。

使用 ContentProvider 取得 Facebook 歸因編號：

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 應用程式的廣告編號。

iOS

行動 Cookie 是由 Facebook iOS 應用程式使用 CFUUIDCreateString 建立，目前採用 128 位元 UUID 字串表示式。

同時取得 Cookie 編號和 IDFA，並傳送至 Facebook 做為識別碼：

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

if (advertiserID) {
  // do stuff
}

X-Forwarded-For HTTP 標頭

如果 POST 要求是從伺服器或 Proxy 等中央位置發出（基本上為伺服器對伺服器的呼叫），則需要 X-Forwarded-For HTTP 標頭，以確保準確的位置和裝置資訊。在您發送的每個應用程式事件要求中，透過 X-Forwarded-For HTTP 標頭參數發送裝置的 IP 位址（IPv4 或 IPv6 格式）。如此我們才能將 advertiser_id 與正確的 IP 位址配對，然後可以在平台中使用。

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. 選擇資料名稱和編號。
4. 點擊「測試事件」，然後選擇管道作為「應用程式」。
5. 使用圖形 API 工具傳送 AE-API 要求。
6. 您的互動工具很快將顯示在「測試事件」頁籤中。

數據差異

如果用戶在行動衡量合作夥伴 (MMP) 與 Facebook 的分析報告之間發現數據差異，請檢查以下項目：

如果 Facebook 回報的安裝次數少於 MMP：

• 是否正確整合 FB SDK？
• 用戶是否使用錯誤的應用程式編號？

如果 Facebook 回報的安裝次數大於 MMP：

• 歸因期間是否一樣？Facebook 的歸因期間通常大於大部分行動衡量合作夥伴的歸因期間。
• 是否正確整合 MMP SDK？
• 客戶是否使用錯誤的應用程式編號？
• 數據差異是否僅限於 iOS7？MMP 是否接收裝置的 Apple 廣告識別碼（IDFA）並正確傳遞給 FB？

參考資料

應用程式活動 Extinfo

請造訪/application/activites參考指南，以取得關於應用程式延伸資訊的詳細資訊。

用戶資料參數

標準事件名稱

標準事件參數

另請參閱

• 應用程式事件
• 應用程式事件最佳作法
• 處理錯誤
• GDPR 合規性
• Facebook 廣告管理員
• Facebook 應用程式主控板