Hướng dẫn chuyển: MBE v2 sang MBE v3

Hướng dẫn này mô tả những thay đổi cần phải thực hiện khi chuyển các ứng dụng dành cho Doanh nghiệp hiện có trên Tiện ích Meta Business (MBE v2) để tương thích với MBE v3. Từ nay trở đi, MBE sẽ yêu cầu những cập nhật này và không tương thích ngược với phiên bản API Đồ thị tiếp theo.

Lợi ích chính của MBE v3

Với MBE v3, nhà phát triển ứng dụng bên thứ ba có thể:

1. Cung cấp quy trình tích hợp đơn giản hơn cho doanh nghiệp.

2. Giúp giảm số người rời mạng.

3. Cho phép doanh nghiệp quản lý linh hoạt các tính năng mà họ muốn bật cho mỗi ứng dụng dành cho Doanh nghiệp. Ví dụ: ban đầu, người bán online có thể thiết lập các tính năng nhắn tin cho một ứng dụng dành cho doanh nghiệp, sau đó chọn bật Cửa hàng trên Facebook cho chính ứng dụng này. Đây là một cách tuyệt vời để bán nâng cấp nhiều tính năng của FBE cho doanh nghiệp.

4. Hỗ trợ nhiều loại hình doanh nghiệp trong quá trình tích hợp với FBE. Ví dụ: ứng dụng bên thứ ba có thể cung cấp một loại tiện ích tích hợp cho nhóm nhỏ doanh nghiệp chỉ yêu cầu công cụ dành cho nhà quảng cáo, đồng thời cung cấp riêng một loại tiện ích tích hợp khác cho những doanh nghiệp chỉ yêu cầu công cụ nhắn tin.

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

Hãy đảm bảo rằng người quản lý đối tác của bạn tại Meta biết bạn đang thực hiện hoạt động nâng cấp này, như vậy họ có thể hỗ trợ bạn đúng cách trong trường hợp bạn cần trợ giúp.

Tổng quan

Thuật ngữ

Tính năng: Một tiện ích tích hợp cụ thể có thể mang lại kết quả cho doanh nghiệp của bạn. Mỗi tiện ích tích hợp đều có yêu cầu triển khai riêng biệt và bạn có thể đặt những tính năng mà mình muốn bật. Ví dụ như page_cta, chat_plugin, v.v. Hãy xem Danh sách tính năng này để biết danh sách đầy đủ.

Ngành dọc: Biểu thị loại hình doanh nghiệp. Bạn có thể tích hợp với một hoặc nhiều ngành dọc, tùy thuộc vào loại hình doanh nghiệp mà bạn cung cấp. Bạn cũng có thể thiết lập một hoặc nhiều ngành dọc cho một doanh nghiệp, tùy thuộc vào nhu cầu của doanh nghiệp đó. Hãy xem Danh sách ngành dọc này để biết danh sách đầy đủ.

Ý định: Ý định là tên MBE cho một trường hợp sử dụng cụ thể. Ví dụ: ý định CATALOG_ADS là tên của trường hợp sử dụng mà theo đó, ứng dụng của bạn có thể chạy quảng cáo danh mục, đồng bộ và quảng bá các sản phẩm cũng như dịch vụ trong danh mục đó. Ý định sẽ hiển thị trên menu tính năng và ánh xạ đến một nhóm gồm nhiều tính năng mà doanh nghiệp nhận được.

Ý định trong v3 tương tự như "kênh" trong v2. Bạn không cần phải đặt cấu hình ý định trong quy trình đăng nhập. Tuy nhiên, cấu hình này sẽ nhắc người bán/nhà quảng cáo hoàn tất việc tích hợp với ý định đã chỉ định trước khi xem các ý định có sẵn còn lại trong menu tính năng. Nếu bạn không đặt cấu hình ý định trong quy trình đăng nhập, hệ thống sẽ hiển thị cho người bán/nhà quảng cáo menu tính năng gồm tất cả ý định có sẵn cho ngành dọc của bạn, đồng thời cho phép họ chọn ý định của riêng mình khi bắt đầu MBE.

Hãy xem Danh sách ý định theo ngành dọc này để biết danh sách đầy đủ.

Điểm khác biệt chính giữa v2 và v3

MBE v3 giới thiệu chi tiết hơn và kiểm soát các tính năng mà doanh nghiệp có thể bật trong quá trình tích hợp. Do đó, chúng tôi đang nâng cấp giao diện người dùng cũng như thay đổi phản hồi webhook và phản hồi API của mình để thể hiện mức độ chi tiết này của tính năng.

Dựa trên những tính năng bạn chọn bật và ngành dọc bạn chuyển cho doanh nghiệp, MBE sẽ hiển thị một menu tính năng trong quy trình tích hợp. Tại đây, doanh nghiệp có thể chọn các tính năng mà họ muốn cài đặt. Sau đó, doanh nghiệp có thể quản lý những tính năng này trong chế độ xem Quản lý, cũng như thêm tính năng khác bằng cách vào lại quy trình đó trên giao diện của bạn hoặc thông qua giao diện chế độ xem Quản lý.

Đề xuất

Nhóm tính năng mà doanh nghiệp bật khá linh động và không bắt buộc, do đó, bạn nên xây dựng một khuôn khổ để lưu giữ bản ghi. Đối với mỗi doanh nghiệp:

1. Lưu giữ danh sách các tính năng đã bật và tài sản được liên kết của tính năng.
2. Đồng bộ hóa với API Meta để đảm bảo bản ghi các tính năng đã bật này luôn cập nhật và chính xác.

Yêu cầu

Với MBE v3, người dùng trong doanh nghiệp có thể:

• Chọn sử dụng nhóm nhỏ tính năng của ứng dụng phù hợp với người dùng đó

• Thêm hoặc gỡ tính năng theo thời gian, độc lập với các tính năng khác

Do đó, quá trình tích hợp ứng dụng cần:

1. Chú ý các thông tin mới. Hệ thống sẽ gửi webhook mỗi lần doanh nghiệp thực hiện quy trình hoặc cập nhật các tính năng hỗ trợ doanh nghiệp.

2. Sau khi nhận được webhook, hãy kiểm tra xem những tính năng nào đã được bật bằng cách gọi API Cài đặt FBE. Mỗi lần thực hiện quy trình thì doanh nghiệp đều có thể bật hoặc vô hiệu hóa các tính năng.

3. Trong nền tảng của bạn, hãy cập nhật bản ghi các tính năng đã được bật cho doanh nghiệp này.

4. Bật từng tính năng dựa trên thông tin chi tiết về cách triển khai của đối tác trong Danh sách tính năng. Ví dụ: nếu đã bật nhiều tính năng (mỗi tính năng yêu cầu một danh mục riêng), bạn phải duy trì đồng bộ cho từng danh mục. Lấy từ API Cấu hình tính năng nếu cần thêm thông tin về tính năng.

Ứng dụng của bạn không nên giả định rằng hệ thống sẽ trả về mọi tài sản mà ứng dụng đó hỗ trợ. Ví dụ:

• Doanh nghiệp thiết lập Cửa hàng cũng có thể làm vậy bằng chính tài khoản Instagram của doanh nghiệp mình. Vì thế, ứng dụng của bạn không nên yêu cầu doanh nghiệp thiết lập Trang để bật tính năng này.

• Doanh nghiệp thiết lập bảng feed Chuyển đổi để cải thiện hiệu quả quảng cáo có thể thực hiện việc này mà không cần thiết lập nút kêu gọi hành động (CTA) trên Trang hay Instagram. Ứng dụng của bạn không nên yêu cầu doanh nghiệp thiết lập Trang hay tài khoản Instagram để bật tính năng này.

Cập nhật tiện ích tích hợp của bạn lên v3

Phần này giải thích cách cập nhật những thay đổi bắt buộc đối với MBE v3 cho tiện ích tích hợp của bạn. Về cơ bản, MBE v3 khác với MBE v2, do đó, bạn nên tuân thủ các nguyên tắc triển khai dưới đây để giảm khả năng người dùng bị gián đoạn.

Bước 1: Thiết lập tính năng và phản hồi các cập nhật

• Cập nhật quy trình Webhook: Chú ý những webhook cho biết rằng doanh nghiệp đã cập nhật nhóm tính năng mà họ muốn bật.

• Cập nhật tiện ích tích hợp qua API Cài đặt FBE: Tìm hiểu những tính năng mà doanh nghiệp đã bật bằng cách gọi API Cài đặt FBE và cập nhật bản ghi của bạn.

• Cập nhật tiện ích tích hợp qua API Cấu hình tính năng: Đặt cấu hình từng tính năng và gọi API Cấu hình tính năng để lấy thêm thông tin về mỗi tính năng khi cần.

Bước 2: Đặt cấu hình các tính năng mà ứng dụng hỗ trợ

Những tính năng bạn đặt cấu hình trong Bảng điều khiển dành cho nhà phát triển MBE sẽ hiển thị với người bán trong menu tính năng.

Bước 3: Đặt cấu hình ngành dọc

Khi bạn đặt cấu hình ngành dọc, hãy nhớ gửi ngành dọc thích hợp cho từng doanh nghiệp trong phần cấu hình bổ sung thuộc business_vertical. Ví dụ: nếu doanh nghiệp là tiệm làm tóc, hãy gửi ‘APPOINTMENTS’. Nếu doanh nghiệp là Cửa hàng bán sản phẩm, hãy gửi ‘ECOMMERCE'.

Nếu một doanh nghiệp thuộc nhiều ngành dọc, hãy gửi các ngành dọc khác nhau cho mỗi điểm bắt đầu trên giao diện của bạn (tùy thuộc vào mục tiêu mà doanh nghiệp đó đang cố gắng đạt được). Ví dụ: nếu một tiệm làm tóc không chỉ sắp xếp cuộc hẹn mà còn bán sản phẩm chăm sóc tóc, bạn có thể gửi ‘APPOINTMENTS’ từ điểm bắt đầu 1 và ‘ECOMMERCE’ từ điểm bắt đầu 2. Mỗi điểm bắt đầu sẽ cần phải đặt cấu hình các tính năng dành riêng cho từng ngành dọc để hoạt động đúng cách.

Người bán/nhà quảng cáo tích hợp cả hai ngành dọc sẽ được "liên kết" với cùng một Trình quản lý kinh doanh cho mỗi ngành dọc, nếu sử dụng cùng một external_id. Tài sản (Trang, pixel, danh mục) từ ngành dọc đầu tiên mà người bán tích hợp sẽ được chọn trước trong ngành dọc thứ hai. Tuy nhiên, người bán có thể chọn các tài sản khác nhau cho ngành dọc thứ hai. Bạn có thể đọc tất cả tính năng do người bán cài đặt trên API Cấu hình tính năng.

Bước 4: Thay đổi giao diện người dùng

Trong quy trình tích hợp mới cập nhật (quy trình tích hợp tối thiểu), bạn sẽ thấy một "menu tính năng" hiển thị danh sách các ý định. Đây là các nhóm gồm một hoặc nhiều tính năng mà bạn đã bật cho doanh nghiệp của mình. Doanh nghiệp có thể chọn những ý định mà họ muốn cài đặt. Nếu bạn muốn doanh nghiệp của mình cài đặt một ý định cụ thể trước rồi mới xem menu tính năng, hãy chuyển thông số intent vào đối tượng setup. Bạn có thể chọn thông số này trong danh sách ý định. Nếu bạn muốn thử nghiệm bản cập nhật giao diện người dùng hoặc không muốn dùng giao diện người dùng mới cập nhật này, thông số use_minimal_onboarding trong đối tượng flow_config sẽ xác định giao diện người dùng cần hiển thị. Nếu bạn đặt Use_minimal_onboarding là false, giao diện người dùng MBE v2 sẽ được giữ nguyên.

Bước 5: Chế độ xem Quản lý

Chế độ xem Quản lý ở v3 hiển thị tất cả những tính năng mà doanh nghiệp đã cài đặt, cùng với liên kết để doanh nghiệp cài đặt nhiều tính năng hơn nữa. Liên kết đến Chế độ xem Quản lý đã được cập nhật thành:

<a href=”https://business.facebook.com/latest/business_app_store/manage_external_business_connection?asset_id=<page_id>&business_id=<business_id>&app_id=<app_id>&external_business_id=<external_business_id>"><button>Launch Management View</button></a>

Bước 6: Cho phép các thay đổi về tính năng

Để cho phép các thay đổi về tính năng nêu trên, chúng tôi đã cập nhật những API sau:

Cập nhật đối với webhook

Hệ thống sẽ gửi webhook mỗi khi có lượt cài đặt và lượt gỡ cài đặt. Webhook này chỉ bao gồm các tính năng mà doanh nghiệp đã cài đặt.

Khi có lượt gỡ cài đặt, hệ thống cũng sẽ gửi webhook cùng với phản hồi chỉ bao gồm các tính năng đã cài đặt (ví dụ: không bao gồm các tính năng đã gỡ cài đặt). Mỗi lần hệ thống gửi webhook, hãy lấy từ API Cài đặt FBE để biết nguồn đáng tin cậy.

Phản hồi

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

Trường phản hồi

Cập nhật đối với API Cài đặt FBE

Mô hình API được cập nhật sẽ gửi danh sách từng tính năng mà doanh nghiệp đã bật và các tài sản được kết nối của từng tính năng. Việc bổ sung thêm trường installed_features là sự thay đổi chính. Phần tải dữ liệu này giống như phản hồi Webhook.

Sau khi nhận được webhook, hãy làm theo các bước được đề xuất dưới đây:

1. Gọi API Cài đặt FBE bằng ID doanh nghiệp bên ngoài và mã truy cập đã nhận được. API này chứa nguồn đáng tin cậy cho các tính năng đã cài đặt và tài sản được kết nối của tính năng. Lưu giữ bản ghi phù hợp về các cấu hình tính năng này.

2. Bật các tính năng này cho doanh nghiệp đó (thông tin cụ thể về ý nghĩa của thao tác "bật" có trong bảng danh sách tính năng) và lấy thêm mọi thông tin cần thiết về các tính năng đó từ API Cấu hình tính năng.

Mã mẫu dưới đây minh họa một yêu cầu mẫu gửi đến API Cài đặt FBE và phản hồi API tương ứng. Trong phản hồi này, chúng tôi sẽ nêu bật các trường bổ sung trong v3.

Yêu cầu

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": [{
    "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>",
<!--UPDATES BELOW-->
    "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
            }
        }
    ]
  }]
}

Cập nhật đối với Phản hồi API Cấu hình tính năng

Mô hình được cập nhật sẽ thêm ID phiên bản tính năng cho mỗi tính năng và các trường mới. Các trường này sẽ 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 được mô tả trong danh sách tính năng, chỉ ID phiên bản tính năng và cờ đã bật sẽ 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,
    },
  ],
  ...
}

Thử nghiệm

Trước khi thử nghiệm, hãy gửi cho người đại diện của Meta những nội dung sau:

1. Các tính năng mà bạn muốn bật.

2. ID người dùng của những người sẽ thử nghiệm quy trình.

3. ID ứng dụng thử nghiệm của bạn để chúng tôi có thể đưa ứng dụng đó vào danh sách cho phép sử dụng v3.

4. Cấp cho người đại diện của Meta một vai trò trong ứng dụng thử nghiệm của bạn nếu bạn cần trợ giúp trong quá trình thử nghiệm.

Để thử nghiệm các thay đổi của v3 này, hãy thực hiện quy trình tích hợp và đảm bảo:

1. Bạn nhận được webhook sau khi cài đặt và gỡ cài đặt.

2. Webhook, API Cài đặt và API Cấu hình tính năng có các cập nhật đã đề cập ở trên (cho biết chính xác các tính năng đã cài đặt và gỡ cài đặt).

3. Menu Tính năng hiển thị các tính năng bạn muốn doanh nghiệp của mình cài đặt (theo ngành dọc).

Bạn có thể thử nghiệm quy trình tích hợp bằng cách:

1. Thực hiện quy trình Đăng nhập cho doanh nghiệp.

2. Sử dụng Ứng dụng dành cho doanh nghiệp (nếu có)

Đảm bảo gửi đúng đối tượng cấu hình doanh nghiệp cho những tính năng bạn muốn bật, cũng như giao diện người dùng bạn muốn thấy trong quy trình Đăng nhập cho doanh nghiệp và Ứng dụng dành cho doanh nghiệp.

Danh sách tính năng

Dưới đây là các tính năng của MBE v3 mà bạn có thể bật cho doanh nghiệp mình. Bạn có thể chuyển tất cả tính năng này qua API Cài đặt FBE (trong quy trình cài đặt). Tuy nhiên, như đã lưu ý trong bảng, không phải tính năng nào cũng có thể đặt cấu hình qua API Cấu hình tính năng (sau khi người bán/nhà quảng cáo đã cài đặt MBE).

Mã mẫu cho messenger_chat

<div class="fb-customerchat"
            page_id=PAGE_ID 
</div>

Danh sách ngành dọc

Xác định (các) ngành dọc cho ứng dụng của bạn:

Ý định (trường hợp sử dụng) theo ngành dọc

Quảng cáo

Nội dung

Thương mại điện tử

Cuộc hẹn

Đặt trước

Ẩm thực

Quảng cáo tìm kiếm khách hàng tiềm năng

Đo lường và tối ưu hóa

Tích hợp dữ liệu