API Chuyển đổi offline

Sử dụng API Chuyển đổi offline để gửi các sự kiện chuyển đổi offline và xem có bao nhiêu khách hàng đã xem hoặc nhấp vào quảng cáo trên Meta trước khi chuyển đổi.

Trước khi bắt đầu

Để sử dụng API này, bạn cần có:

1. Trình quản lý kinh doanh trên Meta

Bạn hãy tạo trình này nếu chưa có.

2. ID ứng dụng trên Meta

Để truy cập API Marketing. Cách tạo ứng dụng trên Meta như sau:

• Truy cập Trình quản lý kinh doanh > Cài đặt cho doanh nghiệp.
• Chọn Ứng dụng.
• Nhấp vào Thêm ứng dụng mới rồi làm theo hướng dẫn.

3. Xét duyệt ứng dụng và quyền

Các quy tắc về xét duyệt ứng dụng và quyền phụ thuộc vào cách bạn đang triển khai API của chúng tôi:

4. Mã truy cập và người dùng hệ thống của Trình quản lý kinh doanh

Với quyền truy cập của người dùng hệ thống, ứng dụng của bạn có thể gửi dữ liệu cho Meta thông qua API này. Cách tạo như sau:

• Truy cập Trình quản lý kinh doanh > Cài đặt cho doanh nghiệp.
• Chọn Người dùng hệ thống.
• Nhấp vào Thêm người dùng hệ thống mới.
• Chọn Người dùng hệ thống là quản trị viên làm vai trò của người dùng hệ thống.

Mã truy cập cung cấp quyền truy cập vào dữ liệu trên Meta. Cách tạo mã truy cập dành cho người dùng hệ thống:

• Truy cập Trình quản lý kinh doanh > Cài đặt cho doanh nghiệp.
• Chọn Người dùng hệ thống.
• Chọn người dùng hệ thống rồi nhấp vào Tạo mã mới.
• Chọn ứng dụng của bạn > đối với phạm vi, chọn ads_management.

5. Tài khoản quảng cáo

Bạn cần có tài khoản quảng cáo để chạy chiến dịch quảng cáo trên Meta. Để tạo tài khoản, hãy xem bài viết API Marketing hoặc Trung tâm trợ giúp doanh nghiệp: Giới thiệu về cài đặt cho doanh nghiệp trong Trình quản lý kinh doanh trên Meta.

6. Cấp quyền truy cập vào tài khoản quảng cáo cho người dùng hệ thống

Cấp cho người dùng hệ thống quyền truy cập vào tài khoản quảng cáo của bạn.

• Truy cập Trình quản lý kinh doanh > Cài đặt cho doanh nghiệp.
• Chọn Người dùng hệ thống.
• Chọn người dùng hệ thống rồi nhấp vào Chỉ định tài sản.
• Chọn tài khoản quảng cáo của bạn.

7. Nhóm sự kiện offline

Đây là các tệp đã tải lên có dữ liệu chuyển đổi offline. Khi bạn tạo quảng cáo, hãy đặt tracking_spec thành ID nhóm sự kiện offline để ghi nhận chính xác các sự kiện. Sau đó, bạn có thể tạo các nhóm sự kiện, xem số liệu thống kê về các lần nhập, xóa và sửa đổi dữ liệu này trong Trình quản lý kinh doanh.

Với những hoạt động triển khai trước đó, bạn có thể thực hiện các thao tác CRUD cho nhóm sự kiện offline ở cấp độ Trình quản lý kinh doanh để chia sẻ nhóm sự kiện với những đối tượng và phần tử khác.

Tải dữ liệu sự kiện lên

Bạn cần có quyền truy cập cụ thể để tạo các nhóm sự kiện offline, tải lên hoặc xem dữ liệu của một nhóm sự kiện. Bạn cũng cần quyền truy cập này để chỉ định các quyền này cho một tài khoản quảng cáo. Bạn phải nắm giữ một trong những vai trò sau:

• Quản trị viên của Trình quản lý kinh doanh
• Người dùng hệ thống là quản trị viên (người đã tạo nhóm sự kiện offline đó)
• Quản trị viên trên ad_account được kết nối với nhóm sự kiện offline đó

Hãy xem Tài liệu tham khảo về Nhóm sự kiện chuyển đổi offline.

1. Tạo nhóm sự kiện offline

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

Thực hiện lệnh gọi 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

Phản hồi sẽ bao gồm id của nhóm sự kiện:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Thông số

2. Chỉ định các quyền cho tài khoản quảng cáo

Cách chỉ định quyền đọc và theo dõi cho một tài khoản quảng cáo:

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

Thông số

3. Thiết lập theo dõi quảng cáo

Khi bạn cập nhật tracking_spec, chúng tôi sẽ ghi đè thông số này. Đảm bảo thực hiện lệnh gọi GET trước, sau đó thêm String được liên kết của nhóm sự kiện offline vào tracking_spec hiện có. Hãy xem phần Quản lý quảng cáo hoặc sử dụng Trình quản lý quảng cáo. Ví dụ: cung cấp một quy cách theo dõi thích hợp như sau:

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>

Cách cập nhật quy cách theo dõi của quảng cáo:

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>}]

Thông số

4. Tải các sự kiện offline lên

Bạn phải tải giao dịch lên trong vòng 62 ngày kể từ khi chuyển đổi diễn ra. Tải dữ liệu chuyển đổi lên:

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

Để gửi lượt chuyển đổi, hãy thực hiện lệnh gọi 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

Thông số

Hãy sử dụng cùng một upload_tag cho tất cả các lệnh gọi API tải sự kiện lên trong cùng một đợt để nhóm chúng lại với nhau. Qua đó, bạn có thể gỡ lỗi tải sự kiện lên. Bạn nên sử dụng cách này cho bất kỳ lượt tải sự kiện lên nào được thực hiện bằng nhiều lệnh gọi API.

Các thông số trong data bao gồm:

Ví dụ: bạn có thể tải thông tin lên bằng trường 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,
    }
  ],
}

Hãy sử dụng cùng một upload_tag cho tất cả lệnh gọi API tải sự kiện lên trong cùng một đợt để nhóm chúng lại với nhau. Qua đó, bạn có thể gỡ lỗi tải sự kiện lên. Bạn nên sử dụng cách này cho bất kỳ lượt tải sự kiện lên nào được thực hiện bằng nhiều lệnh gọi API.

Khóa so khớp

match_keys là một nhóm thông tin nhận dạng để khớp mọi người với cách phân bổ. Hãy xem phần Đối tượng tùy chỉnh từ dữ liệu CRM để chuẩn hóa và băm dữ liệu của bạn. Chúng tôi chỉ hỗ trợ mã hóa SHA256 và không chấp nhận các dữ liệu chưa băm.

Phản hồi:

Đối với các lỗi, bạn sẽ nhìn thấy trường hợp ngoại lệ, bao gồm các mục nhập không hợp lệ và lý do. Hãy sửa các lỗi đó hoặc bỏ qua những hàng dữ liệu có lỗi và thử lại lệnh gọi API.

Xem số liệu thống kê tải lên

Quản trị viên Trình quản lý kinh doanh hoặc người dùng hệ thống đã tạo nhóm sự kiện offline có thể truy xuất số liệu thống kê tải lên. Ngoài ra, mọi quản trị viên trên ad_account được kết nối với nhóm sự kiện offline đó đều có thể đọc dữ liệu này.

Cách xem số liệu thống kê về các nhóm sự kiện offline, chẳng hạn như mục nhập hợp lệ và mục nhập đã khớp:

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

Xem số liệu sự kiện offline chia nhỏ hàng ngày trong Offline Events Manager của Trình quản lý kinh doanh. Để xem số liệu chia nhỏ chính xác hơn, hãy thực hiện lệnh gọi sau:

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

Thông số

Tạo các chuyển đổi tùy chỉnh offline

Chuyển đổi tùy chỉnh offline hiện không hỗ trợ quảng cáo dự phòng. Chúng tôi không ghi nhận dữ liệu của các lần tải sự kiện lên được thực hiện trước khi bạn tạo chuyển đổi tùy chỉnh. Bạn không thể sử dụng dữ liệu chuyển đổi tùy chỉnh offline cho tối ưu hóa phân phối quảng cáo. Hãy xem Chuyển đổi tùy chỉnh, Tài liệu tham khảo.

Để tạo chuyển đổi tùy chỉnh bằng sự kiện offline của bạn, hãy thực hiện lệnh gọi 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

Thông số:

Phản hồi, khi thành công:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Đo lường bằng dữ liệu tùy chỉnh

Bạn có thể sử dụng trường custom_data để tạo các quy tắc mà sau này sẽ giúp xác định liệu một chuyển đổi có được tính hay không. Điều này tương tự với Đối tượng tùy chỉnh offline. Số lượng chuyển đổi tùy chỉnh tối đa mà bạn có thể có cho mỗi tài khoản quảng cáo là 40.

Chẳng hạn, thêm hạng mục sản phẩm kèm custom_data trong các lần tải lên:

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

Sau đó, sử dụng custom_data.{YOUR_CUSTOM_PARAM} để tạo quy tắc Chuyển đổi tùy chỉnh:

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"

Chuyển đổi offline dành cho đối tác

Để ghi nhận các sự kiện chuyển đổi offline cho quảng cáo của khách hàng, hãy làm theo các bước sau. Các lệnh gọi API cho hầu hết các bước này giống như khi một người quản lý nhóm sự kiện offline và quản lý chiến dịch của chính họ.

1. Đối tác - Tạo nhóm sự kiện offline
2. Đối tác - Chia sẻ nhóm sự kiện với Trình quản lý kinh doanh của khách hàng
3. Khách hàng - Chỉ định quyền theo dõi offline cho tài khoản quảng cáo
4. Khách hàng - Đặt tùy chọn theo dõi offline cho các quảng cáo
5. Đối tác - Tải sự kiện offline lên, xem các số liệu thống kê
6. Đối tác - Hiển thị thông tin chi tiết về quảng cáo cho khách hàng

Các bước này khác nhau tùy vào cách thiết lập quyền của đối tác hoặc đại lý với tài khoản quảng cáo của khách hàng:

• Bạn có thể sở hữu tất cả các tài khoản quảng cáo, nhóm sự kiện hoặc bất kỳ tài sản nào khác của khách hàng.
• Bạn có thể có quyền đối với các tài sản của khách hàng để thực hiện một số hành động nhất định.

Để thiết lập các quyền này, hãy xem Tài sản trong Trình quản lý kinh doanh.

Đối tác - Chia sẻ nhóm sự kiện

Chia sẻ nhóm sự kiện với Trình quản lý kinh doanh của khách hàng. Sau đó, khách hàng của bạn có thể sử dụng nhóm sự kiện để theo dõi quảng cáo.

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

Thông số

Khách hàng - Chỉ định quyền theo dõi offline cho tài khoản quảng cáo

Chia sẻ các nhóm sự kiện offline mà đối tác tạo với khách hàng. Bạn cần là quản trị viên Trình quản lý kinh doanh hoặc người dùng hệ thống có quyền quản trị đã tạo nhóm sự kiện offline để có thể theo dõi các quảng cáo trong tài khoản quảng cáo. Nếu là quản trị viên trên tài khoản quảng cáo được kết nối với nhóm sự kiện offline, bạn cũng có thể thực hiện điều này. Để thực hiện lệnh gọi API này, doanh nghiệp trong lệnh gọi phải có quyền truy cập vào nhóm sự kiện offline.

Bạn có thể chỉ định các quyền xem và theo dõi sự kiện offline cho một tài khoản quảng cáo bằng lệnh gọi sau:

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

Thông số

Cung cấp các ID bên ngoài

Có thể có những trường hợp trong đó bạn cung cấp ID bên ngoài của riêng mình để đại diện cho một khách hàng và so khớp họ với một người nào đó trên Meta. Để thực hiện điều này, hãy sử dụng extern_id theo các nguyên tắc sau.

Các đối tác cung cấp dữ liệu thực hiện quy trình khớp có thể sử dụng id đối tác làm id vùng tên và extern_id làm tpid của bạn.

Chỉ cung cấp match_keys

Chúng tôi sử dụng match_keys để tìm cách xác định xem dữ liệu chuyển đổi mà bạn chia sẻ có thể khớp với người dùng Meta hay không. Nếu cung cấp match_keys, bạn cũng không thể cung cấp thông số namespace_id.

Cung cấp cả match_keys và extern_id

Chúng tôi sử dụng match_keys để cố gắng tìm người dùng trên Meta và chuyển tiếp các phần ánh xạ từ {dataset_id, extern_id} đến {facebook_user_id}. Nếu cung cấp match_keys và extern_id, bạn cũng không thể cung cấp thông số namespace_id.

Chỉ cung cấp extern_id

Nếu bạn đã gửi dữ liệu cùng với match_keys và extern_id, Meta sẽ sử dụng {dataset_id, extern_id} để truy xuất {facebook_user_id}.

Cung cấp namespace_id

Thông số namespace_id áp dụng cho toàn bộ lệnh gọi API. Bạn có thể sử dụng thông số này để tham chiếu đến một nhóm sự kiện offline khác có thể truy cập được hoặc thuộc sở hữu của một doanh nghiệp hoặc ID hồ sơ đối tác. Nếu bạn đã gửi dữ liệu cùng với match_keys và extern_id, Meta sẽ sử dụng {namespace_id, extern_id} để truy xuất {facebook_user_id}. Bạn chỉ nên cung cấp một extern_id cho mỗi hàng dữ liệu.

Thông tin chi tiết và ghi nhận

Xem các sự kiện offline được ghi nhận cho quảng cáo mà một người đã xem hoặc nhấp vào. Chúng tôi ghi nhận các chuyển đổi offline sau hơn 1 ngày. Nghĩa là bạn cần đặt khoảng thời gian phân bổ thành 28d_view hoặc action_attribution_windows=['28d_view']'. Nếu không, bạn sẽ không nhìn thấy bất kỳ chuyển đổi nào trong báo cáo. Hãy xem API Thông tin chi tiết và Hướng dẫn về thông tin chi tiết.

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

Thông số

Kết quả sẽ có dạng như sau:

{
  "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
        },
      ],
      ...
    }
  ]
}

Ví dụ: để xem cách phân bổ:

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

Kết quả sẽ có dạng như sau:

{
  "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"
    }
  }
}

Tùy chọn xử lý dữ liệu cho người dùng tại Hoa Kỳ

{
    "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
        }
    ]
}

Tìm hiểu thêm về Tùy chọn xử lý dữ liệu.