應用程式事件 API

我們不再建議將應用程式事件 API 用於新的整合。轉換 API 現在支援網絡、應用程式和離線事件,因此我們建議廣告客戶使用轉換 API 代替應用程式事件 API。應用程式事件 API 的現有用戶仍可繼續使用此 API,但相關開發工作將終止。未來我們會為轉換 API 推出更多創新。進一步了解應用程式事件的轉換 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 欄位指明用戶有否在 iOS 14.5+ 裝置上啟用廣告追蹤。如已停用,欄位會設為 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 端點會根據 30 天內某則廣告的點擊次數傳回安裝和轉換事件。廣告管理員會使用 1 天的閱覽歸因和 28 天點閱歸因模型,根據展示或點擊時間顯示洞察報告,而非根據安裝或轉換時間。當比較您的分析報告與 Facebook 廣告管理員報告時,這一點很重要。除了標準廣告點擊應用程式事件領取之外,您還應留意下列情況:

  • 瀏覽歸因領取:如果帳戶管理中心帳戶未在 30 天內點擊廣告,則設定 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

參考資料

獲取流動 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 參考指南。

用戶數據參數

請下載這個 CSV 檔案

,查看下方經正確標準化和雜湊資料處理的參數範例。



下載(點擊右鍵 > 另存連結為)

客戶資訊數據參數

數據 參數 範例 格式準則

城市

ct

menlopark

小楷城市名稱(移除空格)。

國家/地區

country

US

兩個字母的國家/地區代碼,須使用 ISO 3166-1 alpha-2 格式

出生日期

db

19911226

出生日期,包括年份、月份和日期,如 19971226 表示 1997 年 12 月 26 日

電郵

em

jsmith@example.com

小寫個人電郵地址

名字

fn

john

小楷名字

性別

ge

m

f 或 m,如果未知,請留空

姓氏

ln

smith

小寫姓氏

手機

ph

16505551212

手機號碼,只限數字,包括國碼/區碼、區號和電話號碼

州份

st

ca

兩個字母的州/省代碼

郵遞區號

zp

94035

五位數郵遞區號

標準事件名稱

Event Name Event Parameters _valueToSum

AdClick

fb_ad_type

AdImpression

fb_ad_type

With App Ads, revenue of ads from a third-party platform appears on-screen within your app.

Contact

CustomizeProduct

Donate

fb_mobile_achievement_unlocked

fb_description

fb_mobile_activate_app *

fb_mobile_add_payment_info

fb_success

fb_mobile_add_to_cart

fb_content_type, fb_content_id and fb_currency

Price of item added

fb_mobile_add_to_wishlist

fb_content_type, fb_content_id and fb_currency

Price of item added

fb_mobile_complete_registration

fb_registration_method

fb_mobile_content_view

fb_content_type, fb_content_id and fb_currency

Price of item viewed (if applicable)

fb_mobile_initiated_checkout

fb_content_type, fb_content_id, fb_num_items, fb_payment_info_available and fb_currency

Total price of items in cart

fb_mobile_level_achieved

fb_level

fb_mobile_purchase

fb_num_items, fb_content_type, fb_content_id and fb_currency

Purchase price

fb_mobile_rate

fb_content_type, fb_content_id and fb_max_rating_value

Rating given

fb_mobile_search

fb_content_type, fb_search_string and fb_success

fb_mobile_spent_credits

fb_content_type and fb_content_id

Total value of credits spent

fb_mobile_tutorial_completion

fb_success and fb_content_id

FindLocation

Schedule

StartTrial

fb_order_id and fb_currency

Price of subscription

SubmitApplication

Subscribe

fb_order_id and fb_currency

Price of subscription

*Use fb_mobile_activate_app event in addition to install reporting to exclude users from seeing ads for this app. Do not use this event if you have automatic event logging enabled.

標準事件參數

事件參數名稱 值 說明

_logTime

整數

指定事件時間的推薦參數,以 unixtime 指定

_valueToSum

浮點

個別事件的數值,會在報告中顯示總額,請見上方查看可附加的推薦事件

fb_content_id

字串

若情況許可,適用國際商品編號(EAN)或其他產品或內容識別資料。若為多個產品,例如:「[\"1234\",\"5678\"]」

fb_content

字串

此為 JSON 物件清單,包含國際商品編碼(EAN)(如適用)或其他商品或內容識別資料,以及商品的數量和價格。必要項目:id, quantity,例如:「[{\"id\": \"1234\", \"quantity\": 2,}, {\"id\": \"5678\", \"quantity\": 1,}]」。

fb_content_type

字串

product 或 product_group

fb_currency

字串

ISO 4217 代碼,例如:「EUR」、「USD」、「JPY」。當傳遞 _valueToSum 作為價格或購買金額時,必須提供此參數。

fb_description

字串

字串描述

fb_level

字串

遊戲關卡

fb_max_rating_value

整數

評分級別的上限,例如 5 粒星的上限為 5

fb_num_items

整數

產品數量

fb_payment_info_available

布林值

1 代表是,0 代表否

fb_registration_method

字串

Facebook、電郵、Twitter 等等

fb_search_string

字串

用於搜尋的文字字串

fb_success

布林值

1 為是;0 為否