使用轉換 API 傳送離線事件

轉換 API 是 Meta 推薦的整合方法，可將離線和實體商店事件傳送到 Meta，以用於廣告成效衡量、歸因和目標設定。本頁面詳細說明如何透過轉換 API 直接整合或合作夥伴整合來傳送離線事件。

必要條件

資料集

透過轉換 API 傳送的離線事件必須與資料集相關聯。

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

您可以發出 GET 呼叫至 https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container，偵測廣告主的資料集是否已整合，因而有資格使用轉換 API 來傳遞離線事件。

權限

若要以廣告主身分實作直接整合，請按照這裡的必備條件和權限相關指示操作。
若要實作合作夥伴平台整合，請按照這裡的必備條件和權限相關指示操作。

配置

1.設定離線事件參數

廣告主可以使用這裡提及的設定，並參考可透過轉換 API 傳送的目前參數組合。若要傳送離線和商店事件，可以在裝載中分享下列欄位：

針對所有離線和商店事件，廣告主需要傳送 action_source 做為 physical_store。請注意，這是所有伺服器事件類型的必要參數。使用轉換 API，即表示您同意 action_source 參數就您所知是正確的。
轉換 API 的所有必要伺服器事件欄位都必須填寫。
顧客資訊參數（如需離線和商店事件適用的參數清單，請參閱下文）。
自訂資料參數（如需離線和商店事件適用的參數清單，請參閱下文）。
選用參數：針對使用舊版 API 來處理離線事件的廣告主，仍支援使用 upload_tag 參數來進行離線事件上傳。

顧客資訊參數

下列清單包含通常用於離線和商店事件的顧客資訊參數：

參數名稱	參數	必須雜湊
電郵地址（可複數）	`email`	是
手機號碼（可複數）	`phone`	是
性別	`gen`	是
出生日期	`db`	是
姓氏	`ln`	是
名字	`fn`	是
城市	`ct`	是
美國州份	`st`	是
郵遞區號	`zip`	是
國家／地區	`country`	是
Apple 廣告識別碼	`madid`	是
Android 廣告編號	`madid`	是
第三方用戶編號	`external_id`	強烈建議
名單型廣告的潛在顧客編號	`lead_id`	請勿雜湊

自訂資料參數

以下部分包含離線和商店事件使用的常見自訂參數。如需其他自訂資料欄位，請參閱此連結，查看我們接受用於轉換 API 的完整清單。

參數說明

參數	說明
`event_time` 類型：整數	必要項目轉換事件的 UNIX 時間戳記。範例： `'1456870055'`
`event_name` 類型：字串	必要項目事件類型。範例： `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`currency` 類型：字串	必要項目用於此轉換事件的 3 位字母 ISO 幣別代碼。`Purchase` 事件的必要項目。範例： `USD`
`value` 類型：雙精度浮點數	必要項目轉換事件的值。`Purchase` 事件的必要項目。範例： `16.00`
`content_type` 類型：字串	選用項目任何有效的高效速成+ 目錄廣告`content_type`。範例： `product`
`contents` 類型：JSON 陣列	選用項目。若您要將廣告與目錄整合，則為必填。必填：`id`、`quantity` 建議使用：`price`、`brand`、`category` 必填：`[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` 建議使用：`[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` 類型：JSON 字典	選用項目。此轉換事件相關資訊。範例：`{category: 'ICECREAM'}`
`order_id` 類型：字串	選用項目。不重複的識別資料，代表離線事件組合中的每一筆交易或訂單。例如，對零售商來說，此識別資料可以是收據編號。範例：`ATN10001`、`123456`
`item_number` 類型：字串	選用項目。不重複的識別資料，用於區分同一筆訂單或交易中的事件。範例：`1`、`a`

event_time

類型：整數

必要項目

轉換事件的 UNIX 時間戳記。

範例：
'1456870055'

event_name
類型：字串

必要項目

事件類型。

範例：
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

currency
類型：字串

必要項目

用於此轉換事件的 3 位字母 ISO 幣別代碼。Purchase 事件的必要項目。

範例：
USD

value
類型：雙精度浮點數

必要項目

轉換事件的值。Purchase 事件的必要項目。

範例：
16.00

content_type 類型：字串

選用項目

任何有效的高效速成+ 目錄廣告content_type。

範例：
product

contents

類型：JSON 陣列

選用項目。若您要將廣告與目錄整合，則為必填。

必填：id、quantity

建議使用：price、brand、category

必填：[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]

建議使用：[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]

custom_data

類型：JSON 字典

選用項目。

此轉換事件相關資訊。

範例：{category: 'ICECREAM'}

order_id

類型：字串

選用項目。

不重複的識別資料，代表離線事件組合中的每一筆交易或訂單。例如，對零售商來說，此識別資料可以是收據編號。

範例：ATN10001、123456

item_number

類型：字串

選用項目。

不重複的識別資料，用於區分同一筆訂單或交易中的事件。

範例：1、a

2.傳送事件

若要傳送新的事件，請從下列路徑發出 POST 要求至轉換 API：https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

當您發佈到此關係連線時，Meta 會建立新的離線和商店事件。如需詳細資訊，請參閱此開發人員文件。

以下概述這些參數在裝載整體架構中的適當位置：

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

我們建議即時或每天上傳以獲得最佳化成果，以便離線資料能夠與任何刊登中的廣告成效有效地進行比對。

event_time 最早可以是您傳送事件至 Meta 前 7 天。如果 data 中的任何 event_time 在過去大於 7 天，我們會針對整個要求傳回錯誤，且不會處理任何事件。若是以 physical_store 做為 action_source 的離線和實體商店事件，則應在轉換後 62 天內上傳交易。

系統會即時處理您上傳的資料，因此通常在新增資料後即可查看結果。您可以參閱使用說明文件中的離線事件資料最佳作法。

3.重複資料刪除設定

與跨轉換 API 和 Meta 像素事件的重複資料刪除設定不同，離線事件只能針對其他離線事件進行重複資料刪除。我們支援兩種重複資料刪除方法：依據 order_id 或依據 user。重複資料刪除設定使用下列欄位的組合：dataset_id、event_time、event_name、item_number，以及根據給定事件裝載中的方法而定的索引鍵欄位。

預設重複資料刪除設定使用 order_id 以及上述欄位的組合。如果裝載中沒有 order_id，則會使用依據 user 的重複資料刪除邏輯。

例如，如果有兩筆訂單具有相同的 event_time，event_name 具有相同的 order_id，或具有同一組顧客資訊參數但沒有 order_id，我們會將其視為重複事件，並採用第一個事件。依據 user 的重複資料刪除方法僅適用於兩個裝載中的相同顧客資訊參數欄位。

最長重複資料刪除期限為 7 天。

4.事件疑難排解

您可以使用裝載協助工具來產生裝載資料：

選擇 physical_store 集客力動作來源（若適用）。使用轉換 API，即表示您同意 action_source 參數就您所知是正確的。
針對將傳送到 Meta 的事件填寫資料
這會產生事件裝載，可用來做為轉換 API 整合的範本

請使用事件管理工具中的測試事件工具進行測試。請注意，測試事件工具僅支援網路和應用程式事件。

使用轉換 API 傳送離線事件

必要條件

資料集

權限

配置

1.設定離線事件參數

顧客資訊參數

自訂資料參數

2.傳送事件

3.重複資料刪除設定

4.事件疑難排解

另請參閱

企業商家使用說明文章