Obtener los identificadores de recursos y el identificador de acceso

Después de que el usuario descargue la extensión de Facebook para empresas y de que tú tengas su identificador de acceso de usuario (que se usa para realizar llamadas a la API para el usuario), tienes que obtener el identificador del píxel, el identificador de Instagram para empresas, el identificador de la página, el identificador de Business Manager, el identificador de la cuenta publicitaria, el identificador del catálogo (opcional) o el identificador de acceso del usuario para configurar las funciones pertinentes. Estos identificadores se usarán para los extremos de la API y las configuraciones de la empresa.

Con la solución OBO, el cliente también puede obtener el identificador de acceso mediante el identificador de acceso del usuario administrador del sistema de Business Manager del socio en lugar de únicamente el identificador de acceso del administrador de Business Manager del cliente.

Obtener identificadores para los extremos de la API y las configuraciones empresariales

Para obtener esta información, sigue estos pasos:

Creación de un usuario del sistema

Cuando un usuario instala la extensión de Facebook para empresas, la extensión genera un usuario del sistema del empleado en la cuenta de Business Manager del cliente. La nomenclatura de este nuevo usuario del sistema sigue el esquema {App Name} System User (FBE).

Los usuarios del sistema representan servidores o software que realizan llamadas a la API a recursos que pertenecen a una cuenta de Business Manager o están administrados por ella.

Este usuario del sistema tiene permisos para todos los recursos de la extensión de Facebook para empresas asociados a los siguientes permisos de tarea:

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

Obtener el identificador de usuario del sistema mediante la API

Si recibes un identificador de acceso de usuario mediante un webhook o el inicio de sesión empresarial después de una descarga de FBE, puedes utilizarlo para obtener el identificador de acceso de usuario del sistema de Business Manager. Para ello, 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, utiliza el permiso manage_business_extension, pero en función del caso de uso también podrías necesitar ads_management o catalog_management.

En el campo access_token, puedes pasar un identificador de acceso de usuario (user_access_token) o un identificador de acceso de usuario administrador del sistema de Business Manager del socio (partner_bm_admin_system_user_token). Obtén más información sobre el identificador de acceso de la empresa.

El campo token_type del webhook indica si el access_token recibido es un identificador de acceso de usuario o un identificador de acceso de usuario del sistema.

Si el usuario descarga la extensión de Facebook para empresas a través de Instagram, el webhook devolverá el identificador del usuario del sistema que se generó en la cuenta de Business Manager del cliente, por lo que no es necesario llamar a esta API.

Webhook

Para recibir actualizaciones inmediatas sobre las descargas, desinstalaciones y reconfiguraciones de la extensión de Facebook para empresas, activamos eventos de webhook cada vez que una de tus empresas descarga, modifica o desinstala la extensión de Facebook para empresas.

Cada vez que un usuario descarga o modifica la extensión de Facebook para empresas, la aplicación debe inspeccionar la configuración del webhook para entender qué recursos ha modificado, añadido o eliminado el usuario de su conexión con la aplicación. El comportamiento de la aplicación debe actualizarse en función de los recursos conectados más actuales.

Requisitos de configuración

  1. Crea un extremo en un servidor seguro que pueda procesar las solicitudes de Facebook: solicitudes de verificación (GET) y notificaciones de eventos (POST).
  2. Configura la suscripción a webhooks de la extensión de Facebook para empresas en el panel de aplicaciones:
    • En la sección Extensión de Facebook para empresas del panel de aplicaciones, ve a la pestaña Configuración, desplázate hacia abajo hasta la tarjeta Webhooks y, a continuación, haz clic en Editar URL de devolución de llamada.
    • Introduce la URL del extremo en el campo URL de devolución de llamada y añade una cadena en el campo Verificar identificador. Incluiremos esta cadena en todas las solicitudes de verificación.
    • Una vez que hagas clic en Verificar y guardar, enviaremos una solicitud de verificación a tu extremo, que deberás validar.
    • El webhook fbe_install se suscribirá automáticamente. La tarjeta también tiene un botón que puedes usar para desactivar la suscripción en caso necesario.

Analizar los eventos de webhooks

Cada vez que se recibe un webhook de descarga, la aplicación tiene que realizar las siguientes acciones.

Para las nuevas descargas

  1. Almacenar el identificador de acceso y el tipo de identificador, y registrar los recursos a los que se ha concedido acceso a la aplicación.
  2. Activar el conjunto de funciones en base a los recursos que han obtenido acceso.
  3. Si falta un recurso necesario para una función específica, desactivar únicamente esa función. Por ejemplo, si a la aplicación se le ha concedido acceso a un catálogo, pero no a un píxel, debe implementar únicamente la función accionada por el catálogo, no la que se acciona con el píxel.
  4. Informar al usuario del comportamiento de la aplicación con una actualización en función de los recursos a los que tiene acceso.

Para las descargas existentes

  1. Actualizar el identificador de acceso, el tipo de identificador y el registro de recursos a los que se ha concedido acceso a la aplicación.
  2. Actualizar el conjunto de funciones que la aplicación implementará para esta empresa en base a los recursos que han obtenido acceso.
  3. Informar al usuario del comportamiento de la aplicación con una actualización en función de los recursos a los que tiene acceso.

Analizar un webhook al desinstalar

Realiza los siguientes pasos al desinstalar:

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

Qué incluye la carga útil del webhook

Campos de la respuesta

CampoDescripción
ad_account_id

Tipo: cadena

Identificador de la cuenta publicitaria que selecciona el usuario en FBE. Puedes utilizar esta cuenta publicitaria para administrar los anuncios si la aplicación tiene permisos ads_management. Consulta los activos conectados de la lista installed_features.

business_manager_id

Tipo: cadena

Identificador de Business Manager utilizado para FBE. Consulta los activos conectados de la lista installed_features.

catalog_id

Tipo: cadena

Identificador del catálogo que selecciona un usuario en FBE. Un usuario puede usar este identificador para administrar el catálogo de productos. Consulta los activos conectados de la lista installed_features.

fbe_event

Tipo: cadena

Evento de la extensión de Facebook para empresas que indica si la notificación del evento es una descarga o una desinstalación. Consulta los activos conectados de la lista installed_features.

flow

Tipo: cadena

Flujo que indica con qué ciclo se ha incorporado un usuario (por ejemplo, COMMERCE, CREATIVE, etc.). Consulta los activos conectados de la lista installed_features.

commerce_merchant_settings_id

Tipo: cadena

Identificador de la configuración del comerciante utilizado para permitir a los socios leer información sobre la configuración seleccionada del comerciante de FBE. Consulta los activos conectados de la lista installed_features.

onsite_eligible

Tipo: booleano

Elegibilidad en el sitio del comercio. Indica si los activos seleccionados cumplen los requisitos para el comercio en el sitio. El comerciante debe tener una intención en el sitio y seleccionar las devoluciones, los envíos o los pagos en el sitio del socio. Consulta los activos conectados de la lista installed_features.

profiles

Tipo: matriz

Lista de perfiles (un identificador de página de Facebook o de perfil de Instagram para empresas). Utiliza estos identificadores a fin de crear solicitudes independientes de la API Graph para otras integraciones de Facebook que puedas tener. Consulta los activos conectados de la lista installed_features.

pages

Tipo: matriz

Lista de identificadores de páginas de Facebook. Utiliza estos identificadores a fin de crear solicitudes independientes de la API Graph para otras integraciones de páginas de Facebook que puedas tener. Consulta los activos conectados de la lista installed_features.

instagram_profiles

Tipo: matriz

Lista de identificadores de perfiles de Instagram para empresas. Utiliza estos identificadores a fin de crear solicitudes independientes de la API Graph para otras integraciones de Facebook o Instagram que puedas tener. Si no se incluye el campo, se trata únicamente de un ámbito relacionado con Instagram. Por ejemplo, instagram_basic no se incluye en el identificador de acceso o la empresa no ha conectado ningún perfil de Instagram para empresas con FBE. Consulta los activos conectados de la lista installed_features.

pixel_id

Tipo: cadena

Identificador único del píxel para esta empresa que debes almacenar y utilizar a fin de activar eventos de píxel. Consulta los activos conectados de la lista installed_features.

token_type

Tipo: cadena

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

installed_features

Tipo: matriz

Lista de las funciones que esta empresa ha integrado con los procesos de incorporación o ha instalado a través de ellos. Consulta la lista actual de funciones.

feature_instance_id

Tipo: matriz

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

feature_type

Tipo: cadena

Tipo de la función instalada. En la tabla de la lista de funciones se incluye el conjunto completo de funciones disponibles. Solo es necesario realizar un seguimiento de las funciones que has activado.

connected_assets

Tipo: matriz

Lista de activos específicos y pertinentes para cada función. Las descripciones de los activos se corresponden con las mencionadas al inicio de esta tabla.

additional_info

Tipo: matriz

Información adicional sobre la función conectada.


Cuando recibes un evento de webhook para una descarga nueva, debes hacer lo siguiente: 1) mantener una asignación de business_id a pixel_id porque el identificador del píxel es único para la empresa y debes utilizarlo para activar eventos del píxel estándar y 2) actualizar el inventario de la empresa mediante una de las API PUSH del catálogo, si están activadas.


Ejemplo: carga útil 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 descarga de la extensión de Facebook para empresas

Puedes consultar información básica de la descarga (pixel_id y una lista de perfiles con un IG Business ID and/or Page ID) de cualquier empresa que haya descargado la extensión de Facebook para empresas mediante el siguiente extremo:

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. Ahora, estos campos son la fuente de información en los recursos conectados de la lista “installed_features”:

CampoDescripción

token_type

Tipo: cadena

Tipo de identificador que indica si el valor recibido de access_token es un identificador de acceso de usuario predeterminado o un identificador de acceso de usuario del sistema.

installed_features

Tipo: matriz

Lista de las funciones que esta empresa ha integrado con los procesos de incorporación o ha descargado a través de ellos.

feature_instance_id

Tipo: cadena

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

feature_name

Tipo: cadena

Nombre de la función única.

feature_type

Tipo: cadena

Tipo de la función descargada. Solo tienes que hacer un seguimiento de las funciones que has activado.

connected_assets

Tipo: matriz

Lista de recursos específicos para cada función.

additional_info

Tipo: cadena

Información adicional sobre la función conectada, incluidos los valores de shop_status y shop_status_info, que indican si una tienda se verá afectada por próximos cambios. Los valores de shop_status pueden ser “inactive_other”, “inactive_offsite” o “active”, o “no_longer_available”.

“Active” significa que la tienda es visible. “Inactive_offsite” significa que la tienda no es visible porque no utiliza la finalización de compra en el sitio. “Inactive_other” significa que la tienda no es visible por otra razón que no está relacionada con el tipo de finalización de compra. “No_longer_available” significa que la tienda no está en EE. UU. o en un mercado clave y ya no está disponible.

Respuesta de la API de configuración de la función


En el modelo se incluye el identificador de la instancia de cada función y los campos que constan de una matriz de todas las funciones de ese tipo descargadas por la empresa (por ejemplo, varias llamadas a la acción de página).

En el caso de las funciones que no se pueden personalizar, solo se muestran el identificador de la instancia de la función y una marca activada. Puedes actualizar únicamente las funciones que se pueden personalizar con una solicitud POST.

Este modelo es diferente al de la API de instalación de FBE, ya que proporciona información adicional sobre las funciones aparte de los activos conectados, que incluye el estado conectado y personalizaciones específicas de las funciones. Tras llamar a la API de instalación de FBE, usa esta API si necesitas más información sobre las configuraciones o el estado activado de las funciones.

Lectura

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

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

Actualización

Para actualizar todas las funciones, usa la solicitud POST siguiente:

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