Obtener identificadores de activos y token de acceso

Una vez que el usuario instala la extensión Facebook Business y tienes su token de acceso de usuario (que se utiliza para realizar llamadas a la API para el usuario), debes obtener los identificadores de píxel, de Instagram para empresas, de la página, del administrador comercial, de la cuenta publicitaria y del catálogo (opcional), o el token de acceso del usuario para configurar las funciones pertinentes. Estos identificadores se usarán para los puntos de conexión de la API y las configuraciones de la empresa.

Con la solución OBO, el cliente puede obtener el token de acceso y usar el token de acceso del sistema del administrador comercial del socio, en lugar de solo el token de acceso del administrador comercial del cliente.

Obtener identificadores de puntos de conexión de la API y configuraciones de la empresa

Puedes obtener la información de la siguiente manera:

• Webhook: se requiere para todos los socios de la plataforma que quieren aparecer en la App Store
• Punto de conexión de la API de instalaciones de la FBE: recomendado para empresas autoalojadas

Creación del usuario del sistema

Después de que el usuario instala la FBE, la extensión genera un usuario del sistema de empleado en el administrador comercial del cliente. La denominación de este nuevo usuario del sistema sigue el esquema {App Name} System User (FBE).

Los usuarios del sistema representan a servidores o software que hacen llamadas a la API en relación con activos de un administrador comercial o administrados por uno.

Este usuario del sistema tiene permisos para todos los activos de la FBE asociados con los siguientes permisos de tareas:

1. Página: 'MANAGE'
2. Cuenta publicitaria: 'MANAGE'
3. Catálogo: 'MANAGE'
4. Píxel: 'EDIT'

Obtener el token de usuario del sistema a través de la API

Si recibes un token de acceso de usuario mediante un webhook o el inicio de sesión comercial después de instalar la extensión Facebook Business, puedes usar ese mismo token para obtener el token de acceso de usuario del sistema del administrador comercial. Para eso, haz la siguiente llamada a la 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

En el campo scope, usa el permiso manage_business_extension, pero según el caso de uso, es posible que también necesites ads_management o catalog_management.

En el campo access_token, puedes pasar un token de acceso de usuario (user_access_token) o un token de acceso de usuario del sistema de administración del administrador comercial del socio (partner_bm_admin_system_user_token). Obtén más información acerca del token de acceso de empresa.

Webhook

Para recibir actualizaciones oportunas de instalaciones, desinstalaciones y reconfiguraciones de la FBE, activamos eventos de webhook cada vez que una de nuestras empresas instala, modifica o desinstala la FBE.

Cada vez que un usuario instala o modifica la FBE, tu app debería inspeccionar la configuración del webhook para determinar qué activos modificó, agregó o eliminó el usuario desde que se conectó con la app. Se espera que el comportamiento de tu app se actualice según los activos conectados más recientes.

Requisitos de configuración

1. Crea un punto de conexión en un servidor seguro que pueda procesar solicitudes de Facebook: solicitudes de verificación (GET) y notificaciones de eventos (POST).
2. Configura la suscripción a webhooks de la FBE en el panel de apps:
   • En la sección Extensión Facebook Business del panel de apps, ve a la pestaña Configuración, desplázate hacia abajo hasta la tarjeta Webhooks y haz clic en Editar URL de devolución de llamada.
   • Ingresa la URL del punto de conexión en el campo URL de devolución de llamada y luego ingresa una cadena en el campo Verificar token. Incluiremos esta cadena en todas las solicitudes de verificación.
   • Después de que hagas clic en Verificar y guardar, enviaremos al punto de conexión una solicitud de verificación que deberás validar.
   • El webhook fbe_install se suscribirá automáticamente. Además, la tarjeta también cuenta con un interruptor que se puede usar para desactivar la suscripción si es necesario.

Analizar eventos de webhooks

Cada vez que recibe un webhook de instalación, tu app debe realizar las siguientes acciones.

En instalaciones nuevas

1. Almacenar el token de acceso (y su tipo) y registrar los activos a los que se otorgó acceso a tu app.
2. Activar el conjunto de funciones según los activos que se otorgaron.
3. Si falta un activo obligatorio para una función específica, desactivar solo esa función. Por ejemplo, si a tu app se le otorgó acceso a un catálogo, pero no a un píxel, solo se debe implementar la función que usa el catálogo, pero no la que usa el píxel.
4. Informar al usuario con una descripción actualizada de la manera en que se comporta tu app según los activos a los que tiene acceso.

En instalaciones preexistentes

1. Actualizar el token de acceso, el tipo de token y el registro de activos a los que la app tiene acceso.
2. Actualizar el conjunto de funciones que tu app implementará en este negocio en función de los activos que se otorgaron.
3. Informar al usuario con una descripción actualizada de la manera en que se comporta tu app según los activos a los que tiene acceso.

Analizar el webhook durante la desinstalación

Sigue estos pasos durante la desinstalación:

1. Desactivar las funciones que implementa tu app para esta empresa.
2. Informa a la empresa sobre el cambio en la configuración.

Contenido de la carga del webhook

Campos de la respuesta

Ejemplo: carga con el campo booleano 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 de instalación de la FBE

Sobre cualquier empresa que tenga la FBE instalada, puedes consultar la información de instalación básica (pixel_id y una lista de perfiles con IG Business ID and/or Page ID) mediante el siguiente punto de conexión:

Ejemplo

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

Respuesta

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

La respuesta incluye los siguientes campos. Estos son ahora la fuente confiable en relación con los activos conectados de la lista "installed_features":

Respuesta de la API de configuración de funciones

El modelo incluye el identificador de instancia de cada función y los campos que consisten en una matriz de todas las nuevas funciones instaladas por la empresa (por ejemplo, llamadas a la acción de varias páginas).

En el caso de las funciones no personalizables, se muestra solo un identificador de instancia de función y una marca que indica que está habilitada. Solo puedes actualizar las funciones personalizables con una solicitud POST.

Este modelo es diferente al de la API de instalación de la FBE, ya que proporciona información adicional acerca de las funciones más allá de los activos relacionados, incluido el estado habilitado y personalizaciones de funciones específicas. Después de llamar a la API de instalación de la FBE, usa esta API si necesitas más información sobre el estado habilitado o la configuración de la función.

Leer

Puedes leer el estado de configuración actual de las funciones de cualquier empresa mediante la siguiente solicitud:

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

Actualizar

Para actualizar todas las funciones, usa la siguiente solicitud 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"

Respuesta

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

Próximos pasos

• Configurar funciones de la empresa
• Activar eventos del píxel
• Actualizar tu catálogo