Lấy ID tài sản và mã truy cập

Sau khi người dùng cài đặt Tiện ích Facebook Business và bạn có mã truy cập dành cho người dùng của họ (sử dụng để thực hiện các lệnh gọi API cho người dùng), bạn cần lấy ID pixel, ID Instagram Business, ID Trang, ID Trình quản lý kinh doanh, ID tài khoản quảng cáo, ID danh mục (không bắt buộc) hoặc mã truy cập của người dùng đó để đặt cấu hình các tính năng liên quan. Các ID này sẽ được dùng cho điểm cuối API và cấu hình doanh nghiệp.

Với giải pháp OBO, khách hàng cũng có thể lấy mã truy cập bằng mã truy cập của người dùng hệ thống là quản trị viên Trình quản lý kinh doanh của đối tác, thay vì chỉ sử dụng mã truy cập của quản trị viên Trình quản lý kinh doanh của khách hàng.

Thu thập ID cho các điểm cuối API và cấu hình doanh nghiệp

Bạn có thể lấy thông tin đó theo cách dưới đây:

• Webhook - Bắt buộc đối với tất cả đối tác nền tảng muốn niêm yết trong App Store
• Điểm cuối API Cài đặt FBE - Khuyên dùng cho các doanh nghiệp tự lưu trữ dữ liệu

Tạo người dùng hệ thống

Sau khi người dùng cài đặt FBE, tiện ích này sẽ tạo một người dùng hệ thống là nhân viên trên Trình quản lý kinh doanh của khách hàng. Cách đặt tên cho người dùng hệ thống mới này sẽ tuân theo lược đồ sau {App Name} System User (FBE).

Người dùng hệ thống biểu thị máy chủ hoặc phần mềm thực hiện lệnh gọi API đến tài sản do Trình quản lý kinh doanh sở hữu hoặc quản lý.

Người dùng hệ thống này có quyền truy cập tất cả tài sản FBE được liên kết và có quyền thực hiện các tác vụ sau:

1. Trang: 'MANAGE'
2. Tài khoản quảng cáo: 'MANAGE'
3. Danh mục: 'MANAGE'
4. Pixel: 'EDIT'

Lấy mã người dùng hệ thống qua API

Nếu nhận được một mã truy cập dành cho người dùng thông qua Webhook hoặc phương thức Đăng nhập doanh nghiệp sau khi cài đặt FBE, bạn có thể dùng chính mã đó để lấy mã truy cập dành cho người dùng hệ thống của Trình quản lý kinh doanh. Để làm điều đó, hãy thực hiện lệnh gọi API sau đây:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

Đối với trường scope, hãy sử dụng quyền manage_business_extension, nhưng tùy theo trường hợp sử dụng, bạn cũng có thể cần có quyền ads_management hoặc catalog_management.

Đối với trường access_token, bạn có thể chuyển mã truy cập dành cho người dùng (user_access_token) hoặc Mã truy cập dành cho người dùng hệ thống là quản trị viên Trình quản lý kinh doanh của đối tác (partner_bm_admin_system_user_token). Hãy tìm hiểu thêm về Mã truy cập doanh nghiệp.

Webhook

Để được cập nhật ngay về hoạt động cài đặt, gỡ cài đặt và đặt cấu hình lại FBE, chúng tôi sẽ kích hoạt sự kiện Webhook mỗi khi một trong các doanh nghiệp của bạn cài đặt, sửa đổi hoặc gỡ cài đặt FBE.

Mỗi khi người dùng cài đặt hoặc sửa đổi FBE, ứng dụng của bạn sẽ kiểm tra cấu hình Webhook để biết được người dùng đã sửa đổi, thêm hoặc gỡ tài sản nào từ kết nối của họ với ứng dụng đó. Hành vi của ứng dụng sẽ cập nhật dựa trên tài sản được kết nối gần đây nhất.

Các yêu cầu khi thiết lập

1. Tạo điểm cuối trên một máy chủ bảo mật có thể xử lý các yêu cầu từ Facebook: Yêu cầu xác minh (GET) và Thông báo sự kiện (POST).
2. Đặt cấu hình gói đăng ký webhooks cho FBE trong Bảng điều khiển ứng dụng:
   • Trong phần Tiện ích Facebook Business của Bảng điều khiển ứng dụng, hãy chuyển đến tab Thiết lập, cuộn xuống thẻ Webhooks rồi nhấp vào Chỉnh sửa URL gọi lại.
   • Nhập URL của điểm cuối trong trường URL gọi lại và nhập một chuỗi vào trường Mã xác minh. Chúng tôi sẽ thêm chuỗi này vào tất cả các Yêu cầu xác minh.
   • Sau khi bạn nhấp vào Xác minh và lưu, chúng tôi sẽ gửi đến điểm cuối của bạn một yêu cầu xác minh mà bạn phải xác thực.
   • Hệ thống sẽ tự động đăng ký webhook fbe_install. Thẻ cũng có một nút chuyển dùng để vô hiệu hóa gói đăng ký nếu cần.

Phân tích cú pháp sự kiện Webhook

Mỗi khi nhận được một webhook cài đặt, ứng dụng của bạn cần thực hiện các hành động sau.

Đối với hoạt động cài đặt mới

1. Lưu trữ mã truy cập và loại mã, cũng như ghi lại các tài sản mà ứng dụng của bạn đã được cấp quyền truy cập.
2. Kích hoạt nhóm tính năng dựa trên tài sản đã được cấp quyền truy cập.
3. Nếu thiếu tài sản cần thiết cho một tính năng cụ thể, bạn chỉ cần vô hiệu hóa tính năng đó. Ví dụ: nếu ứng dụng của bạn đã được cấp quyền truy cập vào danh mục, chứ không phải pixel, hãy chỉ triển khai tính năng dựa trên danh mục, chứ không triển khai tính năng dựa trên pixel.
4. Gửi cho người dùng thông tin mới về cách ứng dụng của bạn đang hoạt động dựa trên tài sản mà họ có quyền truy cập.

Đối với hoạt động cài đặt hiện có

1. Cập nhật mã truy cập, loại mã và ghi lại các tài sản mà ứng dụng của bạn đã được cấp quyền truy cập.
2. Cập nhật nhóm tính năng mà ứng dụng của bạn sẽ triển khai cho doanh nghiệp này dựa trên tài sản được cấp quyền truy cập.
3. Gửi cho người dùng thông tin mới về cách ứng dụng của bạn đang hoạt động dựa trên tài sản mà họ có quyền truy cập.

Phân tích cú pháp Webhook khi gỡ cài đặt

Khi gỡ cài đặt, hãy thực hiện các bước sau:

1. Vô hiệu hóa các tính năng mà ứng dụng của bạn triển khai cho doanh nghiệp này.
2. Thông báo cho doanh nghiệp về thay đổi đối với cấu hình của họ.

Phần tải dữ liệu webhook có những nội dung gì

Trường phản hồi

Ví dụ - Phần tải dữ liệu có trường onsite_commerce_eligible là boolean

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            "feature_name" : string, 
            "feature_type": enum,
            "connected_assets": {
                "ad_account_id": "<ad_account_id>",
                "business_manager_id": "<business_manager_id>",
                "catalog_id": "<catalog_id>",
                "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
                "ig_profile_id": "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

API Cài đặt FBE

Đối với bất kỳ doanh nghiệp nào đã cài đặt FBE, bạn có thể truy vấn thông tin cài đặt cơ bản (pixel_id và danh sách trang kinh doanh kèm theo IG Business ID and/or Page ID) bằng cách sử dụng điểm cuối sau:

Ví dụ

CURL -X GET 'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Phản hồi

{
  "data": [{
    "token_type": "<token_type>"
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

Phản hồi chứa các trường sau đây. Đây hiện là nguồn đáng tin cậy trong các tài sản được kết nối của danh sách "installed_features":

Phản hồi API Cấu hình tính năng

Mô hình này sẽ thêm ID phiên bản tính năng cho mỗi tính năng và các trường chứa một mảng gồm tất cả tính năng thuộc loại đó mà doanh nghiệp đã cài đặt (ví dụ: nhiều nút CTA trên trang).

Đối với những tính năng không thể tùy chỉnh, chỉ có ID phiên bản tính năng và cờ đã bật hiển thị. Bạn chỉ có thể cập nhật các tính năng tùy chỉnh được qua yêu cầu POST.

Mô hình này khác với API Cài đặt FBE vì cung cấp thêm thông tin về tính năng ngoài các tài sản được kết nối, bao gồm cả trạng thái đã bật và phần tùy chỉnh tính năng cụ thể. Sau khi gọi API Cài đặt FBE, hãy dùng API này nếu cần có thêm thông tin về trạng thái đã bật hoặc cấu hình của tính năng.

Đọc

Bạn có thể đọc trạng thái cấu hình tính năng hiện tại của mọi doanh nghiệp thông qua yêu cầu dưới đây:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Cập nhật

Để cập nhật tất cả tính năng, hãy sử dụng yêu cầu POST dưới đây:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

Phản hồi

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

Các bước tiếp theo

• Đặt cấu hình tính năng cho doanh nghiệp
• Kích hoạt sự kiện pixel
• Cập nhật danh mục