API Tầng điều khiển của Cổng API Chuyển đổi cho nhiều tài khoản

Tích hợp đối tác

Tổng quan

API tầng điều khiển của Cổng API Chuyển đổi cho nhiều tài khoản là một nhóm các API GraphQL có trên phiên bản Cổng. Với API này, nhà phát triển có thể quản lý tài khoản, nguồn dữ liệu và các cấu hình khác của một phiên bản Cổng theo cách lập trình. Đối tác có thể tích hợp API này để đưa vào giao diện người dùng dành cho nhà quảng cáo, đồng thời cung cấp cho nhà quảng cáo một quy trình tích hợp và quản lý liền mạch.

Trường hợp có thể sử dụng:

Nhà quảng cáo tích hợp với Cổng qua giao diện người dùng của đối tác và thực hiện các hành động tiếp theo thông qua cài đặt quản trị Cổng. Trường hợp sử dụng này yêu cầu nhà quảng cáo phải tích hợp một phần API tầng điều khiển.
Nhà quảng cáo thực hiện tất cả hành động trên giao diện người dùng của đối tác, bao gồm cả hành động tích hợp với Cổng và các hành động tiếp theo. Đây có thể là trường hợp sử dụng phù hợp dành cho các đối tác không muốn hiển thị giao diện người dùng của Cổng, nhưng vẫn muốn cung cấp Cổng dưới dạng dịch vụ cho nhà quảng cáo. Trường hợp sử dụng này yêu cầu tích hợp toàn bộ API tầng điều khiển.

Hãy tham khảo phần bên dưới để biết thêm chi tiết về các bước tích hợp.

API tầng điều khiển của Cổng API Chuyển đổi cho nhiều tài khoản hoặc Cổng được dùng thay thế cho nhau trong tài liệu này.

Hướng dẫn tích hợp

Tùy thuộc vào trường hợp sử dụng, bạn có thể tích hợp theo 2 cách sau đây (như minh họa trong sơ đồ bên dưới):

Tích hợp một phần API tầng điều khiển. Cách này không yêu cầu nhà quảng cáo phải xác thực.
Tích hợp đầy đủ với API tầng điều khiển. Cách này yêu cầu nhà quảng cáo phải xác thực thông qua Tiện ích Meta Business (MBE) hoặc quy trình tạo mã thủ công.

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

Đối với cả hai cách tích hợp, trước hết, đối tác cần hoàn tất các bước bên dưới:

Bước 1: Tích hợp dưới dạng máy chủ của phiên bản Cổng

Bước 2: Tạo tên tài khoản API và khóa bí mật API

Truy cập:

https://<Conversions API Gateway Endpoint>/hub/

Chuyển đến tab Cài đặt máy chủ, chọn trang Quản lý tài khoản API rồi nhấp vào nút Thêm API trong tài khoản.

Nhập lại mật khẩu của bạn. Nhấp vào Tiếp tục.

Nhập tên của tài khoản API. Nhấp vào Tiếp tục.

Tên tài khoản chỉ được chứa chữ cái và số, không được có dấu cách. Độ dài tối đa là 20.

Sao chép và lưu khóa bí mật được tạo. Bạn sẽ không thể xem lại khóa này.

Để gỡ một tài khoản API, hãy nhấp vào Xóa tài khoản API. Lưu ý rằng hành động này không hoàn tác được và có khả năng gây ra tình trạng gián đoạn cho bất kỳ ứng dụng hoặc dịch vụ nào của nhà quảng cáo mà có sử dụng API.

Tích hợp một phần

Trường hợp sử dụng khi tích hợp một phần:

Nhà quảng cáo chọn sử dụng dịch vụ Cổng thông qua giao diện người dùng của đối tác.
Đối tác tạo liên kết mời mà nhà quảng cáo có thể dùng để thiết lập mật khẩu và hoàn tất quá trình tạo tài khoản Cổng.
Nhà quảng cáo sử dụng các chức năng trên giao diện người dùng của Cổng để thực hiện những hành động như quản lý nguồn dữ liệu, cũng như quản lý người dùng tài khoản, miền và cách định tuyến.
Đối tác truy xuất cách sử dụng tài khoản của nhà quảng cáo và hóa đơn tương ứng.

Quy trình của người dùng ở cấp độ cao có thể như sau:

Để đạt được như vậy, đối tác có thể tích hợp một nhóm nhỏ API tầng điều khiển, bao gồm:

Lấy mã truy cập API
Tạo tài khoản cho nhà quảng cáo
Lấy cách sử dụng tài khoản, ví dụ như cho mục đích lập hóa đơn

Tích hợp đầy đủ

Trường hợp sử dụng khi tích hợp đầy đủ:

Nhà quảng cáo chọn sử dụng dịch vụ Cổng thông qua giao diện người dùng của đối tác.
Đối tác tích hợp tài khoản Cổng của nhà quảng cáo và nhận quyền quản lý tài khoản này; nhà quảng cáo ủy quyền cho đối tác sử dụng Tiện ích Meta Business (MBE) hoặc quy trình tạo mã thủ công.
Nhà quảng cáo có thể quản lý nguồn dữ liệu, cũng như quản lý người dùng tài khoản, miền và cách định tuyến trên giao diện người dùng của đối tác.
Đối tác truy xuất cách sử dụng tài khoản của nhà quảng cáo và hóa đơn tương ứng.

Quy trình của người dùng ở cấp độ cao có thể như sau:

Đối với cách tích hợp này, đối tác cần yêu cầu ủy quyền và lấy mã truy cập dành cho người dùng hệ thống thông qua quy trình xác thực để gửi sự kiện thay mặt cho nhà quảng cáo.

Xác thực

Đối tác có 2 phương án xác thực dưới đây đối với Meta Pixel không do mình quản lý:

Phương án 1 - Tiện ích Meta Business (MBE)

Trước khi bắt đầu, bạn cần:

Hoàn tất mọi yêu cầu để triển khai MBE
Liên hệ với đại diện của Meta để thêm ứng dụng của bạn vào danh sách cho phép đối với Quyền riêng tư: open_bridge_configuration_management

MBE cung cấp một điểm cuối để truy xuất mã truy cập dành cho người dùng hệ thống được tạo trong Trình quản lý kinh doanh của nhà quảng cáo. Đối tác có thể làm theo Bước 4 trong hướng dẫn tích hợp MBE. Đảm bảo rằng bạn:

Đặt giá trị của thông số kênh trong đối tượng cấu hình thiết lập là CONVERSIONS_API_GATEWAY_ADVERTISER.
Có thể nhận phản hồi webhook khi tích hợp xong.
Sử dụng mã truy cập được trả về qua MBE và chuyển đổi mã đó thành Mã truy cập dành cho người dùng hệ thống bằng cách thực hiện một lệnh gọi API khác.
Lưu bản sao của external_business_id, pixel_id, business_id và mã truy cập dành cho người dùng hệ thống vào hệ thống của bạn.

Phương án 2 - Mã truy cập dành cho người dùng hệ thống ứng dụng

Đối với phương án này, đối tác có thể yêu cầu nhà quảng cáo:

Tạo mã truy cập dành cho người dùng hệ thống theo cách thủ công qua API Chuyển đổi trong phần Cài đặt của Trình quản lý sự kiện (EM)
Chia sẻ pixel_id, business_id và mã truy cập dành cho người dùng hệ thống với đối tác rồi lưu lại một bản sao.

Tích hợp

Đối tác có thể tích hợp toàn bộ nhóm API tầng điều khiển. Bạn có thể xem thêm chi tiết trong Tài liệu tham khảo về API.

Tính tương đương của API và giao diện người dùng

Chúng tôi đang đảm bảo tính tương đương của API và giao diện người dùng bằng cách công khai các điểm cuối API giống nhau được sử dụng trên giao diện người dùng của Cổng. Tuy nhiên, bất kỳ điểm cuối API nào không được đề cập trong Tài liệu tham khảo về API đều có thể thay đổi trong quá trình phát triển sau này. Để giảm thiểu ảnh hưởng không mong muốn, những điểm cuối API không được đề cập sẽ trả về Mã lỗi: 418. Bạn vẫn có thể sử dụng API nhưng phải tự chịu rủi ro.