離線轉換 API

使用離線轉換 API 傳送離線轉換事件，瞭解多少顧客在轉換前曾檢視或點擊 Meta 廣告。

準備工作

若要使用此 API，您需要：

1.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 是一組識別資料，用於比對用戶以利歸因。如需將資料正規化和進行雜湊處理，請參閱 CRM 資料的自訂廣告受眾。僅支援 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
        }
    ]
}

深入瞭解資料處理選項。