應用程式事件 API

應用程式事件讓您可以追蹤流動應用程式或網頁中發生的動作，例如應用程式安裝和購買事件。透過追蹤這些事件，您可以衡量廣告成效及為鎖定目標的廣告建立廣告受眾。

如需了解有關追蹤商家訊息的應用程式事件資訊，請參閱 Messenger 平台文件中的商家訊息應用程式事件 API。

運作方式

應用程式事件共有三種：

• 自動記錄事件：Facebook SDK 可以自動記錄應用程式安裝次數、應用程式工作階段和應用程式內購買次數。
• 標準事件：Facebook 為您建立的常用事件。
• 自訂事件：由您建立的應用程式專屬事件。

應用程式事件有三個部分：

1. name：用來描述事件的必要字串。當應用程式事件傳送至分析工具時，這個名稱將會顯示在事件記錄中。
2. valueToSum：選用值，分析工具可在名稱相同的應用程式事件中將其加入至其他 Value To Sum 值。
3. parameters：選用值，這些值會包含在您的應用程式事件中。

最多可以擁有 1,000 個相異的事件名稱。備註：一旦到達此數目上限，便無法記錄新的事件類型。若超出此上限，記錄時就會出現 100 Invalid parameter 的錯誤訊息。不過，您可以停用已經不再使用的事件。在常見問題中進一步查看事件的數目上限規定。

準備工作

您必須使用：

• 您的廣告客戶編號、Android 裝置中的廣告編號或 Apple 裝置中的廣告識別碼（IDFA）
• 可供 Facebook 驗證身分的應用程式存取憑證。請勿將您的應用程式存取憑證儲存在用戶端。

應用程式安裝次數

從您的伺服器向 /{app-id}/activities 端點傳送 POST 要求，並在其中使用 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 將出於以下目的使用事件資料（由合作夥伴提供有關用戶在 Meta 站外的活動資料），包括廣告分析報告、欺詐偵測，以及開發和改進我們的產品（包括我們的廣告刊登產品），但我們也會限制使用該名用戶的資料，將用途僅限於僅為該名用戶提供個人化廣告。如果是運行 iOS 6 之前的版本，此參數應預設為 1。

請瀏覽 Apple AdSuppport 參考文件以獲取用戶的追蹤狀態。

以下程式碼片段說明了如何擷取已啟用追蹤標記的值。

您可以從 Settings.shared.isAdvertiserTrackingEnabled 屬性中獲取已啟用追蹤標記的目前設定。

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

停用廣告追蹤

所有應用程式都能選擇加入設定，讓用戶關閉應用程式內的廣告追蹤功能。Facebook 會要求合作夥伴在他們的 SDK 中加入此選項，並向 Facebook 回報用戶的選擇及安裝或轉換事件。Facebook 會將安裝或轉換事件用於廣告報告，但禁止將之用於優化廣告。每次應用程式啟動時，用戶的設定必須維持不變。

轉換事件

向 /{app-id}/activities 端點傳送 POST 要求，將其中的 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 廣告管理員報告時，這一點很重要。除了標準廣告點擊應用程式事件領取之外，您還應留意下列情況：

• 瀏覽歸因領取：如果帳戶管理中心帳戶未在 28 天內點擊廣告，則設定 consider_views=TRUE 將傳回展示廣告的 1 天內發生的安裝歸因數據。系統傳回的回應將為 is_view_through=TRUE，並會將 view_time 替換為 click_time。所有其他歸因將與廣告點擊歸因數據相同。

• 跨宣傳活動領取 - 廣告客戶可以追蹤所有帶來應用程式事件的廣告之成效。只要未將宣傳活動目標設定為流動應用程式安裝或流動應用程式互動，Facebook 就會為來自廣告宣傳活動的事件傳送歸因領取。只有在廣告客戶已將應用程式加至其廣告的「流動應用程式事件追蹤」欄位時，此數據才會顯示。

• 使用情況：如果您的客戶希望追蹤由專頁帖子廣告帶來的安裝事件，或由會傳送用戶前往流動版網站的網站點擊廣告帶來的安裝事件，他們可以在廣告管理員中執行此操作，Facebook 便會領取相關的應用程式安裝事件。

• 跨裝置歸因領取：如果廣告客戶在多個平台上發佈應用程式，則可以查看這些平台廣告帶來的應用程式安裝數據。

• 使用情況：用戶點擊某個應用程式的 iPhone 廣告，然後在其 iPad 安裝了相同的應用程式。不論廣告指定目標為何，我們都可以隨後將 iPad 應用程式安裝事件歸因於 iPhone 廣告。

進階配對

透過進階配對，您可以將顧客數據傳送至 Facebook，讓我們透過這些數據更準確地確定哪些帳戶管理中心帳戶針對您的廣告採取了行動。憑藉這些數據，Facebook 可以將轉換事件與您的顧客配對，以優化您的廣告並建立更大型的再營銷受眾。

向 /{app-id}/activities 端點傳送 POST 要求，將其中的 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 由 iOS 版 Facebook 應用程式使用 CFUUIDCreateString 建立，並以 128 位元 UUID 字串表示。

獲取 Cookie 編號和 IDFA，並將其以識別資料的形式傳送至 Facebook：

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

if (advertiserID) {
  // do stuff
}

X-Forwarded-For HTTP 標題

如果 POST 要求是透過伺服器或代理等中心位置發起（即伺服器至伺服器呼叫），則必須使用 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. 使用 Graph API 工具傳送 AE-API 要求。
6. 您的互動數據很快便會在「測試事件」分頁中顯示。

差異

客戶若在比較流動衡量合作夥伴報告與 Facebook 報告時發現差異，以下是需要檢查的一些項目：

如果 Facebook 報告的安裝事件少於 MMP：

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

如果 Facebook 報告的安裝事件多於 MMP：

• 歸因期是否相同？一般而言，Facebook 的歸因期比大多數流動成效衡量合作夥伴的長。
• MMP SDK 是否已正確地整合？
• 客戶是否使用了錯誤的應用程式編號？
• 差異是否僅限於 iOS 7？MMP 是否已從裝置接收 Apple 廣告識別碼 (IDFA)，並將之正確地傳送至 Facebook？

參考資料

應用程式活動延伸資訊

如需詳細了解應用程式延伸裝置資訊，請瀏覽 /application/activites 參考指南。

用戶數據參數

標準事件名稱

標準事件參數

另請參閱

• 應用程式事件
• 應用程式事件最佳操作實例
• 處理錯誤
• GDPR 合規要求
• Facebook 廣告管理員
• Facebook 應用程式管理中心