Gateway de la API de conversiones para varias cuentas en la API de plano de control

Integración con socios

Información general

El gateway de la API de conversiones para varias cuentas en la API de plano de control es un conjunto de API de GraphQL que se expone a partir de la instancia del gateway. Permite a los desarrolladores administrar de forma programática cuentas, orígenes de datos y otras configuraciones de una instancia del gateway. Los socios pueden integrar la API en su UI para anunciantes y ofrecer a los anunciantes un proceso de gestión y registro sin contratiempos.

Casos de uso potenciales:

Los anunciantes se registran en el gateway mediante la UI del socio y realizan acciones se seguimiento con la configuración de administrador del gateway. Para hacerlo, es necesario contar con una integración parcial de la API de plano de control.
Los anunciantes realizan todas las acciones desde la UI del socio, incluidos el registro en el gateway las acciones posteriores. Puede ser un buen caso de uso para los socios que no quieren exponer la interfaz del gateway, pero, aún así, quieren proporcionar el gateway como servicio para los anunciantes. Para hacerlo, es necesario contar con una integración total de la API de plano de control.

Consulta la sección de abajo para obtener más información sobre los pasos de la integración.

En este documento, se usa "gateway de la API de conversiones para varias cuentas en la API de plano de control" o "gateway" de manera indistinta.

Guía de integración

En función del caso de uso, pueden existir dos rutas de integración (como se muestra en el diagrama que figura a continuación):

Integración parcial de la API de plano de control. No se requiere autenticación por parte de los anunciantes.
Integración total de la API de plano de control. Se requiere autenticación de los anunciantes, que podrán obtenerla utilizando la extensión Meta Business (MBE) o generando tokens de manera manual.

Requisitos previos

En ambas rutas de integración, el socio debe cumplir primero los pasos que se indican a continuación:

Paso 1: registrar como organizador de la instancia de Gateway

Paso 2: generar el nombre de la cuenta y la clave secreta de la API

Para conseguirlo, haz lo siguiente:

https://<Conversions API Gateway Endpoint>/hub/

Ve a la pestaña Configuración de organizadores, selecciona la página Gestionar cuentas de la API y haz clic en el botón de la cuenta Agregar API.

Vuelve a ingresar tu contraseña. Haz clic en Continuar.

Ingresa el nombre de la cuenta de la API. Haz clic en Continuar.

El nombre de la cuenta solo puede consistir en letras y números, y no puede contener espacios. La longitud máxima es de 20 caracteres.

Copia y guarda la clave secreta que se generó, ya que no tendrás oportunidad de volver a verla.

Para eliminar una cuenta de la API, haz clic en Eliminar cuenta de la API. Ten en cuenta que la acción no es reversible y tiene el potencial de causar interrupciones en las apps o servicios de cualquier anunciante que usa la API.

Integración parcial

Un caso de uso basado en la integración parcial:

El anunciante se suscribe al servicio del gateway mediante la UI del socio.
El socio genera un enlace de invitación, que el anunciante puede usar para configurar una contraseña y completar la creación de una cuenta del gateway.
El anunciante utiliza las funcionalidades de la UI del gateway para realizar acciones, como la administración de orígenes de datos y la administración de usuarios de cuenta, dominios y enrutamiento.
El socio consulta el uso de la cuenta del anunciante y las facturas asociadas.

Un proceso de usuario de alto nivel puede tener el siguiente aspecto:

Para lograrlo, el socio puede integrar un subconjunto de la API de plano de control, entre lo que se incluye lo siguiente:

Obtener un token de acceso a la API
Crear una cuenta para anunciantes
Consultar el uso de la cuenta, por ejemplo, con fines de facturación

Integración total

Un caso de uso basado en la integración total:

El anunciante se suscribe al servicio del gateway mediante la UI del socio.
El socio registra la cuenta del gateway del anunciante y recibe permiso para administrar la cuenta. El anunciante autoriza al socio mediante la extensión Meta Business (MBE) o generando manualmente un token.
El anunciante puede administrar los orígenes de datos, los usuarios de las cuentas, los dominios y el enrutamiento en la UI del socio.
El socio consulta el uso de la cuenta del anunciante y las facturas asociadas.

Un proceso de usuario de alto nivel puede tener el siguiente aspecto:

En relación con esta ruta de integración, los socios necesitan solicitar autorización y obtener tokens de acceso del usuario del sistema mediante autenticación para poder enviar eventos en nombre de los anunciantes.

Autenticación

Los socios tienen las siguientes dos opciones de autenticación para aquellos píxeles de Meta que no administran ellos mismos:

Opción 1: extensión Meta Business (MBE)

Antes de empezar, necesitarás hacer lo siguiente:

Completa todos los requisitos de implementación de la MBE
Ponte en contacto con tu representante de Meta para agregar la app a la lista de autorizados y que obtenga un permiso privado: open_bridge_configuration_management

La MBE proporciona un punto de conexión para consultar los tokens de acceso del usuario del sistema que se crearon en el administrador comercial del anunciante. Los socios pueden seguir hasta el paso 4 de la guía de integración de la MBE. Asegúrate de hacer lo siguiente:

Configurar como CONVERSIONS_API_GATEWAY_ADVERTISER el valor del parámetro de canal en la configuración del objeto.
Poder recibir la respuesta del webhook cuando se completa el registro.
Usar un token de acceso devuelto mediante la MBE para convertirlo en un token de acceso del usuario del sistema haciendo una llamada adicional a la API.
Guardar una copia de external_business_id, pixel_id y business_id y el token de acceso del usuario del sistema en tu sistema.

Opción 2: token de acceso del usuario del sistema del cliente

Con esta opción, los socios pueden lograr que los anunciantes hagan lo siguiente:

Crear manualmente un token de acceso del usuario del sistema mediante la API de conversiones en Configuración, que se encuentra dentro del administrador de eventos.
Compartir pixel_id, business_id y el token de acceso del usuario del sistema con el socio y guardarse una copia.

Integración

Los socios pueden integrar el conjunto completo de la API de plano de control. Se incluyen más detalles en la referencia de la API.

Paridad de UI y API

Estamos aplicando la paridad de la API y de la UI, ya que exponemos los mismos puntos de conexión de la API que se usan en la UI del gateway. Sin embargo, los puntos de conexión de la API que no se incluyen en la referencia de la API podrán cambiar cuando se los desarrolle en el futuro. Con el fin de limitar al mínimo cualquier impacto inesperado que pudiera producirse, los puntos de conexión de la API que no se traten devolverán el código de error 418. Podrás seguir usando la API, pero será bajo tu responsabilidad.