Получение ID объектов и маркеров доступа

После того как пользователь установит расширение Facebook Business и вы получите маркер доступа пользователя для выполнения вызовов API, для настройки различных функций вам также потребуются ID пикселя, ID Instagram Business, ID Страницы, ID Business Manager, ID рекламного аккаунта, ID каталога (необязательно) или маркер доступа пользователя. Эти ID используются для конечных точек API и настройки компании.

С помощью решения OBO клиент может получить маркер доступа, используя в том числе маркер доступа системного пользователя администратора Business Manager партнера, а не только маркер доступа администратора Business Manager клиента.

Получение ID для конечных точек API и настройки компании

Эту информацию можно получить следующим образом:

• Webhooks — обязательный способ для всех партнеров платформы, которые хотят находиться в списках App Store;
• конечная точка API FBE Installs — рекомендуемый способ для компаний, размещенных на собственных серверах.

Создание системного пользователя

После установки пользователем расширение Facebook Business генерирует системного пользователя в Business Manager клиента. Имя такого системного пользователя создается по схеме {App Name} System User (FBE).

Используйте системных пользователей для представления серверов или программного обеспечения, выполняющих вызовы API к ресурсам, которые принадлежат Business Manager или которыми управляет Business Manager.

У этого системного пользователя есть разрешения для всех связанных объектов расширения Facebook Business и следующие разрешения задач:

1. Страница: 'MANAGE'.
2. Рекламный аккаунт: 'MANAGE'.
3. Каталог: 'MANAGE'.
4. Пиксель: 'EDIT'.

Получение маркера системного пользователя с помощью API

Если вы получили маркер доступа пользователя с через Webhooks или вход от имени компании после установки расширения Facebook Business, его можно использовать для получения маркера доступа системного пользователя Business Manager. Для этого выполните следующий вызов API:

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

Используйте разрешение manage_business_extension для поля scope. В зависимости от сценария использования может также потребоваться ads_management или catalog_management.

В поле access_token можно передать маркер доступа пользователя (user_access_token) или маркер доступа системного пользователя администратора Business Manager партнера (partner_bm_admin_system_user_token). Подробнее см. в статье о маркерах доступа компании.

Webhooks

Каждый раз, когда какая-либо из ваших компаний устанавливает или удаляет расширение Facebook Business, мы инициализируем события Webhooks, что позволяет быстро получить информацию об установке, удалении или изменении настроек расширения Facebook Business.

Каждый раз, когда пользователь устанавливает или изменяет расширение Facebook Business, ваше приложение должно проверять конфигурацию Webhooks и определять, какой объект пользователь изменил, добавил или удалил из подключения с вашим приложением. Работа вашего приложения должна обновляться в соответствии с актуальными подключенными ресурсами.

Требования к настройке

1. Создайте на защищенном сервере конечную точку, которая может обрабатывать запросы подтверждения (GET) и уведомления о событиях (POST) от Facebook.
2. Настройка подписок на Webhooks для расширения Facebook Business на панели приложений:
   • На панели приложений в разделе Расширение Facebook Business перейдите на вкладку Настройка, прокрутите вниз до карточки Webhooks и нажмите Редактировать URL обратного вызова.
   • Введите URL конечной точки в поле URL обратного вызова и введите строку в поле Маркер подтверждения. Мы добавим эту строку во все запросы подтверждения.
   • Когда вы нажмете кнопку Подтвердить и сохранить, мы отправим на вашу конечную точку запрос, который нужно будет подтвердить.
   • Будет автоматически оформлена подписка на Webhooks fbe_install. Кроме того, на карточке есть переключатель, с помощью которого можно деактивировать подписку при необходимости.

Анализ события Webhooks

При получении Webhooks установки ваше приложение должно выполнить следующие действия.

Новые установки

1. Сохранить маркер доступа и его тип и записать ресурсы, к которым ваше приложение получило доступ.
2. Включить набор функций в зависимости от полученных ресурсов.
3. Если необходимый для какой-либо функции ресурс отсутствует, отключить только эту функцию. Например, если вашему приложению предоставили доступ к каталогу, но не к пикселям, реализуйте только функцию, работающую с каталогом, но не функцию, работающую с пикселями.
4. Проинформировать пользователя о том, как работает ваше приложение в зависимости от того, к каким ресурсам у него есть доступ.

Существующие установки

1. Обновить маркер доступа и его тип и записать ресурсы, к которым ваше приложение получило доступ.
2. Обновить набор функций вашего приложения, которые будут включены для компании в соответствии с предоставленными платформе ресурсами.
3. Проинформировать пользователя о том, как работает ваше приложение в зависимости от того, к каким ресурсам у него есть доступ.

Анализ Webhooks при удалении

При удалении выполните следующие действия.

1. Отключите функции, которые ваше приложение реализует для компании.
2. Проинформируйте компанию об изменении ее конфигурации.

Что содержит полезная нагрузка Webhooks?

Поля ответа

Пример: полезная нагрузка с логическим значением в поле onsite_commerce_eligible

{
  "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 FBE Installation

Для каждой компании, установившей расширение Facebook Business, можно запросить базовую информацию об установке (pixel_id и список профилей с IG Business ID and/or Page ID). Для этого используется следующая конечная точка:

Пример

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>'

Ответ

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

Ответ содержит перечисленные ниже поля. Это достоверные значения для подключенных ресурсов из списка "installed_features".

Ответ API Feature Configuration

Модель содержит ID экземпляра функции для каждой функции и поля, в которых указан массив всех функций такого типа, установленных соответствующей компанией (пример: призывы к действию для нескольких страниц).

Для ненастраиваемых функций отображаются только ID экземпляра функции и включенный флаг. Чтобы обновить только настраиваемые функции, используйте запрос POST.

Эта модель отличается от API FBE Installation, так как она, помимо данных о связанных объектах, предоставляет дополнительную информацию о функциях, в том числе статус включения и определенные настройки функций. После вызова API FBE Installation используйте этот API, чтобы получить дополнительную информацию об активированном статусе или конфигурациях для определенной функции.

Чтение

Вы можете узнать текущий статус конфигурации функций для любой компании, выполнив следующий запрос:

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

Обновление

Чтобы обновить все функции, выполните следующий запрос POST:

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"

Ответ

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

Дальнейшие действия

• Настройка функций для компаний
• Инициализация событий пикселя
• Обновление каталога