Gửi sự kiện offline qua API Chuyển đổi

API Chuyển đổi là phương thức tích hợp mà Meta khuyên dùng để gửi sự kiện offline và sự kiện tại cửa hàng thực đến Meta cho mục đích đo lường, phân bổ cũng như nhắm mục tiêu quảng cáo. Trang này trình bày chi tiết cách gửi sự kiện offline thông qua tiện ích tích hợp trực tiếp hoặc tích hợp đối tác của API Chuyển đổi.

Điều kiện tiên quyết

Tập dữ liệu

Những sự kiện offline được gửi qua API Chuyển đổi phải được liên kết với một tập dữ liệu.

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.

Bạn có thể thực hiện lệnh gọi GET đến https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container để phát hiện xem tập dữ liệu của nhà quảng cáo có được hợp nhất hay không và do đó có đủ điều kiện để chuyển các sự kiện offline qua API Chuyển đổi hay không.

Quyền

Để tích hợp trực tiếp làm nhà quảng cáo, hãy làm theo hướng dẫn về quyền và điều kiện tiên quyết tại đây.
Để tích hợp nền tảng đối tác, vui lòng làm theo hướng dẫn về quyền và điều kiện tiên quyết tại đây.

Cấu hình

1. Thiết lập thông số sự kiện offline

Nhà quảng cáo có thể sử dụng cách thiết lập được đề cập ở đây và tham khảo nhóm thông số hiện tại mà có thể gửi qua API Chuyển đổi. Để gửi sự kiện offline và sự kiện tại cửa hàng thực, bạn có thể chia sẻ các trường sau đây trong phần tải dữ liệu:

Nhà quảng cáo cần gửi action_source là physical_store đối với tất cả sự kiện offline và sự kiện tại cửa hàng thực. Lưu ý rằng đây là thông số bắt buộc đối với mọi loại sự kiện trên máy chủ. Bằng cách sử dụng API Chuyển đổi, bạn đồng ý rằng thông số action_source là chính xác theo hiểu biết của bạn.
Bạn phải tuân theo tất cả những trường bắt buộc cho sự kiện trên máy chủ đối với API Chuyển đổi.
Thông số thông tin khách hàng (xem danh sách thông số phù hợp cho sự kiện offline và sự kiện tại cửa hàng thực ở bên dưới).
Thông số dữ liệu tùy chỉnh (xem danh sách thông số phù hợp cho sự kiện offline và sự kiện tại cửa hàng thực ở bên dưới).
Thông số không bắt buộc: những nhà quảng cáo sử dụng API cũ cho sự kiện offline vẫn có thể dùng thông số upload_tag cho lượt tải sự kiện offline lên.

Thông số thông tin khách hàng

Dưới đây là danh sách các thông số thông tin khách hàng thường dùng cho sự kiện offline và sự kiện tại cửa hàng thực:

Tên thông số	Thông số	Bắt buộc băm
Địa chỉ email	`email`	CÓ
Số điện thoại	`phone`	CÓ
Giới tính	`gen`	CÓ
Ngày sinh	`db`	CÓ
Họ	`ln`	CÓ
Tên	`fn`	CÓ
Tỉnh/thành phố	`ct`	CÓ
Tiểu bang của Hoa Kỳ	`st`	CÓ
Mã zip	`zip`	CÓ
Quốc gia	`country`	CÓ
Mã nhận dạng quảng cáo của Apple	`madid`	CÓ
ID quảng cáo của Android	`madid`	CÓ
ID người dùng của bên thứ ba	`external_id`	Đặc biệt khuyến nghị
ID khách hàng tiềm năng của Quảng cáo tìm kiếm khách hàng tiềm năng	`lead_id`	KHÔNG băm

Thông số dữ liệu tùy chỉnh

Phần dưới đây trình bày các thông số tùy chỉnh phổ biến mà sự kiện offline và sự kiện tại cửa hàng thực sử dụng. Để biết các trường dữ liệu tùy chỉnh khác, vui lòng tham khảo danh sách đầy đủ mà chúng tôi chấp nhận đối với API Chuyển đổi theo liên kết sau đây.

Thông số Mô tả

Thông số	Mô tả
`event_time` loại: số nguyên	Bắt buộc Nhãn thời gian UNIX của sự kiện chuyển đổi. Ví dụ: `'1456870055'`
`event_name` loại: chuỗi	Bắt buộc Loại sự kiện. Ví dụ: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`currency` loại: chuỗi	Bắt buộc Mã đơn vị tiền tệ theo tiêu chuẩn ISO gồm 3 chữ cái cho sự kiện chuyển đổi này. Bắt buộc đối với các sự kiện `Purchase`. Ví dụ: `USD`
`value` loại: double	Bắt buộc Giá trị của sự kiện chuyển đổi. Bắt buộc đối với các sự kiện `Purchase`. Ví dụ: `16.00`
`content_type` loại: chuỗi	Không bắt buộc Mọi `content_type` hợp lệ của quảng cáo danh mục Advantage+. Ví dụ: `product`
`contents` loại: mảng JSON	Không bắt buộc. Bắt buộc nếu bạn tích hợp quảng cáo với danh mục. Bắt buộc: `id`, `quantity` Khuyên dùng: `price`, `brand`, `category` Bắt buộc: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` Khuyên dùng: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` loại: từ điển JSON	Không bắt buộc. Thông tin về sự kiện chuyển đổi này. Ví dụ: `{category: 'ICECREAM'}`
`order_id` loại: chuỗi	Không bắt buộc. Thông tin nhận dạng duy nhất của từng giao dịch hoặc đơn đặt hàng trong một nhóm sự kiện offline. Ví dụ: đối với giao dịch bán lẻ thì mã này có thể là ID biên lai. Ví dụ: `ATN10001`, `123456`
`item_number` loại: chuỗi	Không bắt buộc. Thông tin nhận dạng duy nhất để phân biệt các sự kiện trong cùng một giao dịch hoặc đơn đặt hàng. Ví dụ: `1`, `a`

event_time

loại: số nguyên

Bắt buộc

Nhãn thời gian UNIX của sự kiện chuyển đổi.

Ví dụ:
'1456870055'

event_name
loại: chuỗi

Bắt buộc

Loại sự kiện.

Ví dụ:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

currency
loại: chuỗi

Bắt buộc

Mã đơn vị tiền tệ theo tiêu chuẩn ISO gồm 3 chữ cái cho sự kiện chuyển đổi này. Bắt buộc đối với các sự kiện Purchase.

Ví dụ:
USD

value
loại: double

Bắt buộc

Giá trị của sự kiện chuyển đổi. Bắt buộc đối với các sự kiện Purchase.

Ví dụ:
16.00

content_type loại: chuỗi

Không bắt buộc

Mọi content_type hợp lệ của quảng cáo danh mục Advantage+.

Ví dụ:
product

contents

loại: mảng JSON

Không bắt buộc. Bắt buộc nếu bạn tích hợp quảng cáo với danh mục.

Bắt buộc: id, quantity

Khuyên dùng: price, brand, category

Bắt buộc: [ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]

Khuyên dùng: [ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]

custom_data

loại: từ điển JSON

Không bắt buộc.

Thông tin về sự kiện chuyển đổi này.

Ví dụ: {category: 'ICECREAM'}

order_id

loại: chuỗi

Không bắt buộc.

Thông tin nhận dạng duy nhất của từng giao dịch hoặc đơn đặt hàng trong một nhóm sự kiện offline. Ví dụ: đối với giao dịch bán lẻ thì mã này có thể là ID biên lai.

Ví dụ: ATN10001, 123456

item_number

loại: chuỗi

Không bắt buộc.

Thông tin nhận dạng duy nhất để phân biệt các sự kiện trong cùng một giao dịch hoặc đơn đặt hàng.

Ví dụ: 1, a

2. Gửi sự kiện

Để gửi sự kiện mới, hãy gửi yêu cầu POST đến API Chuyển đổi từ đường dẫn sau: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

Khi bạn gửi yêu cầu POST đến cạnh này, Meta sẽ tạo sự kiện offline mới và sự kiện mới tại cửa hàng thực. Để biết thêm chi tiết, vui lòng tham khảo tài liệu dành cho nhà phát triển dưới đây.

Sau đây là thông tin tổng quan về cách sắp xếp thông số theo lược đồ chung trong phần tải dữ liệu:

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

Bạn nên tải lên theo thời gian thực hoặc hàng ngày để đạt kết quả tối ưu hóa tốt nhất. Như vậy, dữ liệu offline sẽ được so khớp hiệu quả với hiệu quả của bất kỳ quảng cáo nào mà bạn đang chạy.

event_time có thể sớm hơn thời điểm bạn gửi sự kiện cho Meta tối đa 7 ngày. Nếu bất kỳ event_time nào trong data sớm hơn thời điểm bạn gửi quá 7 ngày, chúng tôi sẽ trả về lỗi đối với toàn bộ yêu cầu và không xử lý sự kiện nào. Đối với sự kiện offline và sự kiện tại cửa hàng thực có physical_store là action_source, bạn nên tải giao dịch lên trong vòng 62 ngày kể từ ngày chuyển đổi.

Dữ liệu bạn tải lên được xử lý theo thời gian thực, vì vậy, bạn thường có thể xem kết quả ngay khi thêm. Bạn có thể tham khảo tài liệu về Cách làm tốt nhất đối với dữ liệu sự kiện offline trong Trung tâm trợ giúp.

3. Thiết lập quy trình bỏ trùng lặp

Khác với cách thiết lập quy trình bỏ trùng lặp giữa sự kiện API Chuyển đổi và sự kiện Meta Pixel, bạn chỉ có thể bỏ trùng lặp giữa các sự kiện offline với nhau. Chúng tôi hỗ trợ 2 phương thức bỏ trùng lặp, đó là: dựa trên order_id hoặc dựa trên user. Quy trình bỏ trùng lặp sử dụng kết hợp các trường dataset_id, event_time, event_name, item_number và trường khóa dựa trên phương thức trong phần tải dữ liệu của sự kiện cụ thể.

Quy trình bỏ trùng lặp mặc định sử dụng order_id kết hợp với các trường nêu trên. Nếu phần tải dữ liệu không có order_id, hệ thống sẽ sử dụng logic bỏ trùng lặp dựa trên user.

Ví dụ: trong trường hợp 2 đơn đặt hàng có event_time giống nhau, event_name có cùng order_id hoặc cùng nhóm Thông số thông tin khách hàng mà không có order_id, chúng tôi sẽ xem những đơn đặt hàng đó là sự kiện trùng lặp và chọn sự kiện đầu tiên. Phương thức bỏ trùng lặp dựa trên user chỉ hiệu quả trong trường hợp 2 phần tải dữ liệu có cùng các trường Thông số thông tin khách hàng.

Khoảng thời gian bỏ trùng lặp tối đa là 7 ngày.

4. Khắc phục sự cố về sự kiện

Bạn có thể dùng công cụ Trình trợ giúp phần tải dữ liệu để tạo dữ liệu cho phần tải dữ liệu:

Chọn nguồn hành động physical_store, nếu có. Bằng cách sử dụng API Chuyển đổi, bạn đồng ý rằng thông số action_source là chính xác theo hiểu biết của bạn.
Điền thông tin cho các sự kiện sẽ được gửi đến Meta
Thao tác này sẽ tạo phần tải dữ liệu sự kiện mà bạn có thể dùng làm mẫu để tích hợp API Chuyển đổi

Sử dụng công cụ Sự kiện thử nghiệm trong Trình quản lý sự kiện để thử nghiệm. Vui lòng lưu ý rằng công cụ Sự kiện thử nghiệm chỉ hỗ trợ sự kiện trên web và sự kiện trong ứng dụng.

Gửi sự kiện offline qua API Chuyển đổi

Điều kiện tiên quyết

Tập dữ liệu

Quyền

Cấu hình

1. Thiết lập thông số sự kiện offline

Thông số thông tin khách hàng

Thông số dữ liệu tùy chỉnh

2. Gửi sự kiện

3. Thiết lập quy trình bỏ trùng lặp

4. Khắc phục sự cố về sự kiện

Xem thêm

Bài viết trong Trung tâm trợ giúp doanh nghiệp