離線轉換 API

使用離線轉換 API 傳送離線轉換事件，了解在轉換前曾經觀看或點擊 Meta 廣告的顧客人數。

準備工作

如要使用此 API，您需要準備以下內容：

1.Meta 企業管理平台

如果您還沒有 Meta 企業管理平台，請先建立一個。

2.Meta 應用程式編號

用於存取推廣 API。若要建立 Meta 應用程式，請按照下列步驟操作：

• 前往企業管理平台 > 企業管理平台設定。
• 選擇應用程式。
• 點擊新增新應用程式，按照相關指示操作。

3.應用程式審查與權限

應用程式審查和權限的相關規則需視乎您安裝 API 的具體方式而定：

4.企業管理平台系統用戶與憑證

有了系統用戶存取權限，您的應用程式就可以使用 API 傳送資料至 Meta。若要建立系統用戶存取權限，請按照下列步驟操作：

• 前往企業管理平台 > 企業管理平台設定。
• 選擇系統用戶。
• 點擊新增新系統用戶。
• 選擇管理員系統用戶作為系統用戶角色。

「存取憑證」讓您可以存取 Meta 資料。若要建立「系統用戶存取憑證」：

• 前往企業管理平台 > 企業管理平台設定。
• 選擇「系統用戶」。
• 選擇系統用戶，然後點擊產生新存取憑證。
• 選擇您的應用程式 > 選擇 ads_management 作為範圍。

5.廣告帳戶

您需要有廣告帳戶，才能在 Meta 推出廣告宣傳活動。若要建立帳戶，請參閱推廣 API 文章或企業商家幫助中心：關於 Meta 企業管理平台中的企業管理平台設定。

6.向廣告帳戶授予系統用戶存取權限

向您的廣告帳戶授予系統用戶存取權限。

• 前往企業管理平台 > 企業管理平台設定。
• 選擇「系統用戶」。
• 選擇系統用戶，然後點擊分配資產。
• 選擇您的廣告帳戶。

7.離線事件組合

這些是含有離線轉換資料的已上載檔案。建立廣告時，您可以將 tracking_spec 設定為離線事件組合編號，以便準確地為事件歸因。然後，您可以建立事件組合、檢視匯入資料的統計數據、刪除並修改企業管理平台上的此等資料。

透過先前的執行範例，您可以在企業管理平台級別執行離線事件組合 CRUD 操作，從而向其他物件和實體分享事件組合。

上載事件資料

您需要有特定存取權限，才可以建立離線事件組合、上載或查看事件組合的資料。您亦需要此存取權限才能分配這些權限至廣告帳戶。您的身分必須是下列其中一者：

• 企業管理平台管理員
• 建立離線事件組合的管理員系統用戶
• 已連結至離線事件組合的 ad_account 之管理員

請參閱離線轉換事件組合的參考資料。

1.建立離線事件組合

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

執行 HTTP POST：

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

回應會包含事件組合 id：

{
  "id": <OFFLINE_EVENT_SET_ID>
}

參數

2.分配廣告帳戶權限

若要分配追蹤與讀取權限給廣告帳戶：

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

參數

3.設定廣告追蹤

當您更新 tracking_spec 時，我們會將其覆寫。確保首先執行 GET，然後再將與離線事件組合連結的 String 附加至現有 tracking_spec。請參閱廣告管理文章，或使用廣告管理員。舉例來說，您需要提供合適的追蹤規格：

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

若要更新廣告的追蹤規格，請如下操作：

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

參數

4.上載離線事件

您需要在轉換後的 62 天內上載交易。上載轉換資料：

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

若要傳送轉換內容，請執行 HTTP POST：

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

參數

同一批的所有事件上載 API 呼叫應使用相同的 upload_tag，以便將其分組。此操作有助您為上載事件除錯；若您在多個 API 呼叫中都有上載事件，則應為每次上載使用此欄位。

data 中的參數包括：

例如，您可以使用 data 欄位上載資訊：

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

同一批的事件上載 API 呼叫均應使用相同的 upload_tag，以便將其分組。此操作有助您為上載事件除錯；若多於一次的 API 呼叫執行了事件上載，我們建議您使用此欄位。

配對金鑰

match_keys 是一組識別資料，用於配對用戶以進行歸因。請參閱根據客戶關係管理資料建立的自訂廣告受眾一文，了解如何對資料作標準化和雜湊處理。我們僅支援 SHA256，且不接受未經雜湊處理的資料。

回應：

若出現錯誤，您會看到包含無效項目與原因的異常。修正錯誤或略過有錯誤的資料列，並再次傳送 API 呼叫。

檢視上載統計資料

企業管理平台管理員或建立離線事件組合的系統用戶都可以擷取上載狀態。此外，已連結至離線事件組合的 ad_account 上的所有管理員均可讀取此資料。

若要檢視離線事件組合的狀態，例如有效的條目與配對的項目：

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

在企業管理平台中的 Offline Events Manager 上檢視離線事件的每日資料細節。若要更精準的資料細節，可執行此呼叫：

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

參數

建立離線自訂轉換

目前，離線自訂轉換不會回填。如果是在建立自訂轉換前處理的事件上載資料，我們就不會進行歸因。您無法將離線自訂轉換資料用於廣告刊登優化。請參閱自訂轉換事件的參考資料。

若要使用您的離線事件建立自訂轉換，請執行 POST：

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

參數：

成功的話，回應會是：

{
  "id": <CUSTOM_CONVERSION_ID>
}

透過自訂資料衡量成效

您可以使用 custom_data 欄位建立規則，以便日後用於判斷轉換是否成立。這與離線自訂廣告受眾類似。每個廣告帳戶自訂轉換的數量上限為 40。

舉例來說，利用 custom_data 在上載項目中加入產品類別：

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

然後使用 custom_data.{YOUR_CUSTOM_PARAM} 建立自訂轉換規則：

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

合作夥伴的離線轉換事件

若要將離線轉換事件歸因至客戶的廣告，請按照這些步驟操作。這些步驟中使用的 API 呼叫跟用戶管理自己的離線事件組合與宣傳活動管理時使用的呼叫一樣。

1. 合作夥伴：建立離線事件組合
2. 合作夥伴：與客戶企業管理平台分享事件組合
3. 客戶：分配離線追蹤權限給廣告帳戶
4. 客戶：設定廣告的離線追蹤
5. 合作夥伴：上載離線事件、檢視統計資料
6. 合作夥伴：提供廣告分析報告給客戶

取決於您的合作夥伴或代理商的客戶廣告帳戶權限設定，這些步驟可能會有所不同：

• 您可能會擁有客戶的所有廣告帳戶、事件組合或其他廣告素材。
• 您可能會擁有客戶廣告素材的使用權限，並可執行特定動作。

若要設定這些權限，請參閱企業管理平台資產。

合作夥伴：分享事件組合

與客戶企業管理平台分享事件組合。這樣您的客戶就能使用事件組合來追蹤廣告。

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

參數

客戶：分配離線追蹤權限給廣告帳戶

與合作夥伴的客戶分享其建立的離線事件組合。您需要是企業管理平台管理員或建立離線事件組合的管理系統用戶才能在廣告帳戶中啟用廣告追蹤。如果您是連結至離線事件組合的廣告帳戶的管理員，您也可以執行此操作。若要執行此 API 呼叫，呼叫中的企業必須擁有使用離線事件組合的權限。

您可以使用此呼叫來向廣告帳戶分配追蹤及檢視離線事件的權限：

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

參數

提供外部編號

有時候您可能會提供自己的外部編號來代表顧客，並用以配對用戶。如要做到這一點，請按照以下指引來使用 extern_id。

如果資料合作夥伴已完成配對流程，可以將合作夥伴編號用作命名空間編號，並將 extern_id 用作您的 tpid。

僅提供 match_keys

我們會使用 match_keys 來嘗試判斷您分享的轉換資料可否與 Meta 用戶配對。如果您提供 match_keys，就無法再提供 namespace_id 參數。

同時提供 match_keys 和 extern_id

我們會使用 match_keys 來嘗試找出 Meta 用戶，並將 {dataset_id, extern_id} 的對應資料傳送至 {facebook_user_id}。如果您提供 match_keys 和 extern_id，就無法再提供 namespace_id。

僅提供 extern_id

如果您在傳送 match_keys 和 extern_id 時有一併傳送資料，Meta 就會使用 {dataset_id, extern_id} 來檢索 {facebook_user_id}。

提供 namespace_id

namespace_id 參數適用於整個 API 呼叫。您可以用此參數來指明另一個可由企業或合作夥伴個人檔案編號存取或擁有的離線事件組合。如果您在傳送 match_keys 和 extern_id 時一併傳送資料，Meta 就會使用 {namespace_id, extern_id} 來檢索 {facebook_user_id}。您只應為每一列資料提供一個 extern_id。

洞察報告及歸因

查看被檢視或點擊過的廣告的離線事件歸因。我們會在超過 1 天之後將離線轉換事件歸因。這就表示您需要將您的歸因期設定為 28d_view 或 action_attribution_windows=['28d_view']'，否則您將無法在報告中看到任何轉換。請參閱洞察報告 API 和洞察報告指南。

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

參數

結果看起來如下：

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

舉例來說，若要查看歸因結果：

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

得出的結果會如下所示：

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

適用於美國用戶的資料處理選項

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

進一步了解資料處理選項。