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:

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.

El campo token_type del webhook indica si el access_token que se recibió es un token de acceso de usuario o de usuario del sistema.

Si el usuario instala la FBE a través de Instagram, el webhook devuelve el token del usuario del sistema que se generó en el administrador comercial del cliente, de manera que no necesitas llamar a esta API.

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

CampoDescripción
ad_account_id

Tipo: cadena

Identificador de la cuenta publicitaria seleccionado por el usuario dentro de la FBE. Puedes usar esta cuenta publicitaria para administrar anuncios si tu app tiene permisos de ads_management. Consulta los activos relacionados de la lista installed_features.

business_manager_id

Tipo: cadena

Identificador del administrador comercial utilizado en la FBE. Consulta los activos relacionados de la lista installed_features.

catalog_id

Tipo: cadena

Identificador del catálogo seleccionado por un usuario con la FBE. Un usuario puede usar este identificador para administrar su catálogo de productos. Consulta los activos relacionados de la lista installed_features.

fbe_event

Tipo: cadena

Evento de la FBE que indica si la notificación del evento tiene que ver con una instalación o una desinstalación. Consulta los activos relacionados de la lista installed_features.

flow

Tipo: cadena

Proceso que indica con qué proceso se registró un usuario (por ejemplo, COMMERCE, CREATIVE, y así sucesivamente). Consulta los activos relacionados de la lista installed_features.

commerce_merchant_settings_id

Tipo: cadena

Identificador de configuración de comerciante que se usa para habilitar a los socios con el objetivo de que puedan leer información relacionada con la Configuración de comerciante de la FBE seleccionada. Consulta los activos relacionados de la lista installed_features.

onsite_eligible

Tipo: booleano

Cumplimiento de los requisitos para el comercio en el sitio. Indica si los activos seleccionados son aptos para el comercio en el sitio. De todos modos, el comerciante debe tener la intención de admitir el comercio en el sitio y seleccionar devoluciones/envíos/pagos en el sitio del socio. Consulta los activos relacionados de la lista installed_features.

profiles

Tipo: matriz

Lista de perfiles (un identificador de página de Facebook y/o un identificador del perfil de empresa de Instagram). Usa estos identificadores para crear solicitudes a la API Graph independientes en otras integraciones de Facebook que puedas tener. Consulta los activos relacionados de la lista installed_features.

pages

Tipo: matriz

Lista de identificadores de la página de Facebook Usa estos identificadores para crear solicitudes a la API Graph independientes en otras integraciones de la página de Facebook que puedas tener. Consulta los activos relacionados de la lista installed_features.

instagram_profiles

Tipo: matriz

Lista de identificadores de perfiles de empresa de Instagram. Usa estos identificadores para crear solicitudes a la API Graph independientes en otras integraciones de Facebook/Instagram que puedas tener. Si el campo no está incluido, significa que su alcance solo está relacionado con Instagram. Por ejemplo, instagram_basic no se incluye en el token de acceso y/o la empresa no tiene un perfil de empresa de Instagram conectado con la FBE. Consulta los activos relacionados de la lista installed_features.

pixel_id

Tipo: cadena

Identificador de pixel único de esta empresa que deberías almacenar y usar para activar eventos del pixel. Consulta los activos relacionados de la lista installed_features.

token_type

Tipo: cadena

Tipo de token. Indica si el access_token recibido es un token de acceso de usuario predeterminado o un token de acceso de usuario del sistema.

installed_features

Tipo: matriz

Lista de funciones que esta empresa tiene integradas o que instaló mediante los procesos de registro. Consulta la lista de funciones actual.

feature_instance_id

Tipo: matriz

Identificador que representa de manera única cada función instalada. Se puede usar en la función para modificar o desinstalar una instancia en particular. Es el mismo que el feature_instance_id al que se hace referencia en la API de configuración de funciones y el webhook.

feature_type

Tipo: cadena

Tipo de función instalada. En la tabla Lista de funciones, puedes ver todo el conjunto de funciones disponible. Solo tienes que hacer un seguimiento de las funciones que tienes habilitadas.

connected_assets

Tipo: matriz

Lista de activos específicos y relevantes para cada función. Las descripciones de los activos corresponden a los mencionados en la parte superior de esta tabla.

additional_info

Tipo: matriz

Información adicional sobre la función conectada.


Cuando recibes un evento de webhook para una nueva instalación, debes hacer lo siguiente: 1) mantener una asignación de business_id para este pixel_id ya que el identificador del píxel es único para esa empresa y tú deberías usarlo para activar eventos del píxel estándar, y 2) actualizar el inventario para esa empresa con una de las API push del catálogo, si están activadas.


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":

CampoDescripción

token_type

Tipo: cadena

Tipo de token que indica si el access_token recibido es un token de acceso de usuario o un token de acceso de usuario del sistema de manera predeterminada.

installed_features

Tipo: matriz

Lista de funciones que esta empresa tiene integradas o que instaló mediante los procesos de registro.

feature_instance_id

Tipo: cadena

Identificador único que representa cada función instalada. Se puede usar en la función para modificar o desinstalar una instancia en particular. Es el mismo que el feature_instance_id al que se hace referencia en la API de configuración de funciones y el webhook.

feature_name

Tipo: cadena

Nombre de una función única.

feature_type

Tipo: cadena

Tipo de función instalada. Solo tienes que hacer un seguimiento de las funciones que habilitaste.

connected_assets

Tipo: matriz

Lista de activos específicos de cada función.

additional_info

Tipo: cadena

Información adicional sobre el dispositivo conectado, incluidos shop_status y shop_status_info, que indican si una tienda se verá afectada por los próximos cambios. los valores de shop_status pueden ser "inactive_other", "inactive_offsite", "active" o "no_longer_available".

"Active" significa que la tienda es visible. "Inactive_offsite" significa que la tienda no es visible porque no está usando la función de finalización de compra en el sitio. "Inactive_other" significa que la tienda no es visible debido a alguna razón no relacionada con el estilo de finalización de compra. "No_longer_available" significa que esta tienda no está en los Estados Unidos o en un mercado clave y ya no está disponible.

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