3: Implementación para desarrolladores

En esta página se aborda la integración manual y se explican los siguientes procesos:

Crear la carga útil de la integración de CRM
Generar un identificador de acceso y prepara una llamada a la API
Enviar una carga útil de prueba
Enviar datos de producción

Esta sección solo se aplica si decides completar este proceso con una integración manual y recursos para desarrolladores. Si por el contrario decides completar esta integración con un socio, sigue las instrucciones del socio correspondiente para la integración. Puedes pasar a la sección 4: Verificar los datos de esta guía una vez que la integración con socios esté completa.

Necesitarás acceso de administrador de Business Manager para completar estos pasos de integración. Puedes obtener acceso a partir del correo electrónico que recibiste si te invitaron como desarrollador. De lo contrario, ponte en contacto con un administrador de Business Manager para solicitar acceso.

Paso 1: crear una carga útil

En este paso se expondrán las especificaciones de la carga útil de la integración para la conversión de clientes potenciales y se proporcionarán algunas recomendaciones sobre cómo enviarla desde el servidor.

Abre la guía de integración de CRM desde la pestaña Configuración del píxel de CRM para comenzar.

Consulta la guía para desarrolladores de la API de conversiones para comprender cómo funciona la API de conversiones.

Recomendamos utilizar el asistente de carga útil para crear la carga útil. El asistente de carga útil aplicará un formato a la carga útil y comprobará si hay errores. Una vez que se hayan resuelto todos los errores de la carga útil, haz clic en el botón Obtener código en el asistente de carga útil para generar una plantilla de código para tu lenguaje de programación.

A continuación se incluye la lista de los parámetros obligatorios. Consulta la guía Integración para la conversión de clientes potenciales: especificación de la carga útil para ver la descripción completa de cada parámetro. Esta especificación de la carga útil debe utilizarse solo en el caso de los eventos de optimización para conseguir conversiones de clientes potenciales. Esto significa que los eventos solo deben pertenecer a los anuncios para clientes potenciales de Meta y tener un identificador de cliente potencial válido. Evita usar esta especificación de la carga útil para otros tipos de eventos, como los clientes potenciales del sitio web.

Parámetros

Nombre	Descripción
`event_name` Cadena	Campo sin formato para capturar las fases de clientes potenciales que utilizas en el sistema de CRM. El parámetro `event_name` debe indicar que un cliente potencial se está moviendo por el embudo de ventas en el sistema de CRM. Asegúrate de enviar todas las fases a medida que se actualizan, incluido el cliente potencial sin procesar.
`event_time` Entero	Mara de tiempo UNIX en segundos que indica cuándo actualiza el sistema de CRM el evento de actualización de las fases de clientes potenciales. La marca de tiempo debe ocurrir después del periodo de generación de clientes potenciales; de lo contrario, es posible que el evento se descarte.
`action_source` Cadena	Valor:`system_generated` (Al utilizar la API de conversiones, aceptas que el parámetro `action_source` es adecuado hasta donde tú sabes).
`lead_id` Entero	Valor de `leadgen_id` de 15 o 16 dígitos de tus clientes potenciales descargados.
`lead_event_source` Cadena	Nombre del sistema de CRM de donde proceden los eventos.
`event_source` Cadena	Valor:`crm`

Ejemplo
Un ejemplo de carga útil puede tener un aspecto similar al siguiente. Nota: Debes utilizar un valor válido de lead_id para que el sistema no rechace el evento.

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

Si los eventos no siguen la especificación de la carga útil o no coinciden con ningún anuncio para clientes potenciales de Meta, no se reconocerán para la integración y no se utilizarán para entrenar el modelo.
Por ejemplo, la API de conversiones aceptará la carga útil web y aparecerá en el Administrador de eventos, pero no se reconocerá para esta integración. También debes usar un valor válido de lead_id para que el sistema no rechace el evento.
La carga útil de la conversión de clientes potenciales será la única que se reconozca para la integración y se utilizará para el entrenamiento.

Paso 2: crear un identificador de acceso y una llamada a la API

Cuando configures lo que vas a enviar, el siguiente paso consiste en configurar a dónde se enviarán los datos.

Este paso te ayudará a generar un identificador de acceso para el píxel de Meta, que luego se utilizará para establecer una conexión entre el servidor y la API de conversiones.

Puedes volver a la guía de integración de CRM desde la pestaña Configuración del píxel de CRM.

Desplázate hacia abajo hasta la sección Crear extremo y haz clic en el botón Generar identificador de acceso. El identificador de acceso se utilizará para crear la llamada a la API.
Para generar un nuevo identificador de acceso, vuelve a la guía de integración o, en la pestaña Configuración del Administrador de eventos, ve a la sección API de conversiones y haz clic en el enlace Generar identificador de acceso.

El resto de esta guía variará en función de si utilizas el SDK de Meta. Se recomienda utilizar Meta Business SDK porque proporciona mensajes de error y de diagnóstico más precisos. Necesitarás el identificador del píxel y el identificador de acceso para llamar a la API mediante Meta Business SDK. Para obtener el identificador de acceso, haz clic en Copiar identificador de acceso en el guía de integración de CRM y guárdalo. Puedes consultar ejemplos de llamadas a la API del SDK en la guía para desarrolladores de la API de conversiones o la función Obtener código del asistente de carga útil de Meta.

Este es el formato de extremo para realizar una solicitud POST a la API de conversiones sin el SDK. Si quieres obtener el extremo completo, haz clic en Copiar extremo en la guía de integración de CRM y guárdalo.
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION: versión actual de la API de marketing.
- PIXEL_ID: el identificador del píxel se puede obtener en el Administrador de eventos para cada píxel.
- ACCESS_TOKEN: identificador de acceso generado anteriormente.
Puedes ver las fechas de lanzamiento y caducidad de la API de marketing en la documentación de versiones de la API. Asegúrate de actualizar la versión de la API o Meta Business SDK en el código antes de la fecha de caducidad de la API de marketing. Si utilizas una versión retirada en el código, se podrían producir errores y el sistema podría descartar los eventos.

Paso 3: probar una carga útil (opcional)

En este punto, es posible que quieras enviar una carga útil de prueba al píxel antes de implementar el código en el servidor. Puedes hacerlo en la pestaña Probar eventos del Administrador de eventos.

En la sección Probar eventos de servidor, haz clic en el enlace Explorador de la API Graph. Al utilizar este enlace único, se rellenarán previamente algunos datos del píxel. (Si quieres, también puedes acceder directamente al explorador de la API Graph). Toma nota del valor de test_event_code, que puede cambiar con el tiempo.

Completa lo siguiente en el explorador de la API Graph:
1. Asegúrate de estar en modo POST.
2. Comprueba que la versión de la API y el identificador del píxel sean correctos.
3. Cambia a la vista de JSON.
4. Introduce la carga útil. Se puede crear manualmente o generar con el asistente de carga útil. Asegúrate de incluir el parámetro test_event_code del paso anterior y un valor válido de lead_id.
Introduce el identificador de acceso del píxel y haz clic en el botón Enviar.

Si la carga útil no contiene errores de sintaxis ni de la API, debes recibir un mensaje de éxito con un valor de fbtrace_id.

El evento de prueba debe aparecer en la pestaña Probar eventos del Administrador de eventos tras un breve periodo de tiempo.

Paso 4: enviar datos de producción

Los datos de producción deben estar en el mismo formato que la carga útil generada en el paso 3, a excepción de que los datos procederán directamente del servidor. Este paso variará para cada integración, por lo que en esta sección se proporcionarán normas en lugar de un tutorial.

Envía el valor de lead_id en lugar de PII para establecer coincidencias.

Asegúrate de enviar todas las fases de clientes potenciales a medida que se actualicen, incluido el evento de clientes potenciales sin procesar que representa a todos los clientes potenciales generados en Meta y descargados en el sistema de CRM. A continuación se presenta un ejemplo de embudo. El anunciante se encarga de definir los nombres de los eventos y las fases, por lo que no tienen que ajustarse a este ejemplo.

Si tus campañas generan 100 clientes potenciales, esperamos 100 eventos de “Cliente potencial sin procesar” subidos para representar la primera fase de clientes potenciales. Enviar la primera fase de clientes potenciales permitirá al sistema saber que el cliente potencial se recibió y procesó. A medida que los clientes potenciales se desplazan hacia abajo en el embudo de ventas, esperamos que se suban 70 eventos de “Cliente potencial cualificado en marketing”, 30 de “Oportunidad de ventas” y 15 de “Ha realizado una conversión”.

En resumen, se generan 100 clientes potenciales a partir de las campañas, pero esperamos que se suban 215 eventos en esta situación de ejemplo.

Crea una función que recupere actualizaciones de la API o la base de datos del sistema de CRM cada vez que el estado del cliente potencial se actualice. A continuación, envía la carga útil a la API de conversiones de Meta con una función personalizada o el Meta Business SDK. La opción que tenga más sentido para la integración dependerá de la configuración del sistema de CRM y la base de datos.

Se recomiendan variables para:
- lead_id
- event_name
- event_time
Por ejemplo, una carga útil que especifica explícitamente los valores de los parámetros podría tener un aspecto similar al siguiente:
```
{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```
Una carga útil que pasa valores de la base de datos con variables podría tener un aspecto similar al siguiente:
```
{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```

Sube datos al menos una vez al día. Las llamadas al sistema de CRM deben realizarse idealmente en tiempo real, pero puedes emplear métodos por lotes cada hora o cada día si no es viable una integración en tiempo real.
Si elijes los métodos por lotes, asegúrate de capturar el historial de cambios de estado del cliente potencial en lugar de una versión del cliente potencial en el momento de los lotes. Por ejemplo, si el estado de un cliente potencial se actualiza tres veces entre lotes, esperamos tres eventos para este cliente potencial en lugar de solo la actualización final.
Nota: Cada lote puede incluir hasta 1000 eventos. Si hay un error en el lote, el lote entero se descartará, por lo que recomendamos ENCARECIDAMENTE utilizar lotes más pequeños y añadir lógica de reintentos.

Opcional. Se recomienda registrar los mensajes de error de la llamada a la CAPI y crear alertas si hay problemas. La gestión de excepciones para estos errores también sería una buena idea.

Puedes rellenar los datos hasta siete días en el pasado. La diferencia de tiempo se calcula entre event_time y upload_time. El proceso de entrenamiento se puede acelerar si se rellenan algunos datos.
ADVERTENCIA: No intentes rellenar más de siete días de datos mediante la modificación de los valores de event_time. El modelo se basa en una marca de tiempo precisa para la optimización. Al hacerlo, puedes provocar que todos los datos rellenados se descarten.
Asegúrate de que los valores de event_time sean posteriores a la marca de tiempo de generación de clientes potenciales; de lo contrario, los eventos podrían descartarse.

Debes empezar a ver cómo aparecen los eventos en el Administrador de eventos para el píxel en el plazo de una hora si la integración sube eventos a Meta. Recuerda utilizar un valor válido de lead_id en las cargas útiles para que los eventos aparezcan. Abre todos los eventos enviados para la integración de CRM para la conversión de clientes potenciales en el Administrador de eventos y comprueba que tengan los parámetros personalizados lead_event_source y event_source rellenados. Si el evento no tiene estos parámetros, no se registrará como un evento de conversión de clientes potenciales.
El sistema verificará si alguno de los eventos es un evento de conversión de clientes potenciales válido. Un día después, aparecerá una marca de verificación verde junto al paso Enviar un evento de CRM de la integración si se detecta un evento válido.

< 2: Getting Started With the CRM Integration

4: Verificar los datos >