API de conversiones offline

Usa la API de conversiones offline para enviar eventos de conversión offline, y observa cuántos clientes visualizaron o hicieron clic en los anuncios de Meta antes de realizar una conversión.

Antes de empezar

Para usar esta API, necesitarás lo siguiente:

1. Administrador comercial de Meta

Si no tienes uno, créalo.

2. Identificador de la app de Meta

Para obtener acceso a la API de marketing. Para crear una aplicación de Meta:

• Ve a Administrador comercial > Configuración del negocio.
• Selecciona Apps.
• Haz clic en Agregar app y sigue las instrucciones.

3. Revisión de apps y permisos

Las reglas sobre la revisión y los permisos de la app dependen de cómo estés implementando nuestra API:

4. Usuario y token del sistema del administrador comercial

Con el acceso de usuario del sistema, tu app puede enviar datos a Meta mediante la API. Para crearlo, sigue estos pasos:

• Ve a Administrador comercial > Configuración del negocio.
• Selecciona Usuarios del sistema.
• Haz clic en Agregar nuevo usuario del sistema.
• Selecciona Usuario administrador del sistema como rol para el usuario del sistema.

Un token de acceso permite acceder a los datos de Meta. Para crear tokens de acceso de usuario del sistema, sigue estos pasos:

• Ve a Administrador comercial > Configuración del negocio.
• Selecciona Usuarios del sistema.
• Selecciona el usuario del sistema y haz clic en Generar nuevo token.
• Selecciona tu app > para alcance, selecciona ads_management.

5. Cuenta publicitaria

Necesitas una cuenta publicitaria para poner en circulación campañas publicitarias en Meta. Para crear una, consulta API de marketing o Servicio de ayuda para empresas: Información sobre la configuración del negocio en el administrador comercial de Meta .

6. Acceso del usuario del sistema a la cuenta publicitaria

Concede acceso del usuario del sistema a tu cuenta publicitaria.

• Ve a Administrador comercial > Configuración del negocio.
• Selecciona Usuarios del sistema.
• Selecciona el usuario del sistema y haz clic en Asignar activos.
• Selecciona tu cuenta publicitaria.

7. Conjunto de eventos offline

Son archivos que se suben con datos de conversión offline. Cuando creas un anuncio, configura tracking_spec con el identificador del conjunto de eventos offline para atribuir correctamente los eventos. Luego, puedes crear conjuntos de eventos, ver estadísticas sobre las importaciones y eliminar y modificar estos datos en el administrador comercial.

Con implementaciones anteriores, puedes realizar operaciones CRUD con el conjunto de eventos offline en el nivel del administrador comercial, con el fin de compartir los conjuntos de eventos con otros objetos y entidades.

Subir los datos del evento

Necesitas acceso específico para crear conjuntos de eventos offline, subir o ver datos para un conjunto de eventos. Además, necesitas tener este acceso para asignar tales permisos a una cuenta publicitaria. Debe ser una de las siguientes opciones:

• Administrador del administrador comercial
• Usuario administrador del sistema que creó el conjunto de eventos offline
• Administrador en la ad_account conectada con el conjunto de eventos offline

Consulta Conjunto de eventos de conversión offline, Referencia.

1. Crea un conjunto de eventos offline

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Crea una instancia de HTTP POST:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

La respuesta incluye el id de un conjunto de eventos:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parámetros

2. Asigna permisos de la cuenta publicitaria

Para asignar permisos de lectura y seguimiento a una cuenta publicitaria:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parámetros

3. Configura el seguimiento de anuncios

Cuando actualices tracking_spec, lo sobrescribiremos. Asegúrate de generar primero GET y, luego, anexa el valor asociado de String a la tracking_spec existente para el conjunto de eventos offline. Consulta Administración de anuncios o usa el administrador de anuncios. Por ejemplo, proporciona una especificación de seguimiento adecuada:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Para actualizar la especificación de seguimiento de tus anuncios:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parámetros

4. Sube los eventos offline

Debes subir la transacción en un plazo de 62 días a partir de la conversión. Sube los datos de conversión:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Para enviar conversiones, genera una solicitud HTTP POST:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Parámetros

Usa el mismo valor de upload_tag para todas las llamadas a la API de subida de eventos en el mismo lote con el fin de agruparlas. Permite depurar las subidas de eventos. Deberás usarlo para todas las subidas de eventos que se hagan en más de una llamada a la API.

Los parámetros de data incluyen:

Por ejemplo, puedes subir información con el campo data:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Usa el mismo valor de upload_tag en todas las llamadas a la API de subida de eventos del mismo lote con el fin de agruparlas. Permite depurar las subidas de eventos. Deberás usarlo en todas las subidas de eventos que se hagan en más de una llamada a la API.

Claves de coincidencia

match_keys es un conjunto de identificadores para hacer coincidir personas por atribución. Consulta Públicos personalizados de datos de la CRM para normalizar y cifrar los datos. Solo SHA256 es compatible y no aceptamos datos sin cifrado.

Respuesta:

Cuando hay errores, se muestra una excepción que incluye las entradas no válidas y la razón. Resuelve los errores u omite las filas de datos con errores, y vuelve a intentar la llamada a la API.

Consultar las estadísticas de subida

Tanto el administrador del administrador comercial como el usuario del sistema que creó el conjunto de eventos offline pueden recuperar las estadísticas de subida. Además, todos los administradores en el campo ad_account que está conectado con el conjunto de eventos offline pueden leer estos datos.

Para consultar estadísticas sobre los conjuntos de eventos offline, tales como las entradas válidas y aquellas con coincidencias:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Visualiza desgloses diarios de eventos offline en Offline Events Manager dentro del administrador comercial. Para obtener desgloses más precisos, haz esta llamada:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parámetros

Crea conversiones personalizadas offline

Las conversiones personalizadas offline por el momento no ofrecen respaldo. No atribuimos datos de subidas de eventos realizadas antes de la creación de la conversión personalizada. No puedes usar los datos de conversión personalizada offline para optimizar la entrega de anuncios. Consulta Conversión personalizada, Referencia.

Para crear una conversión personalizada usando los eventos offline, crea una instancia de POST:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Parámetros:

Si se realiza correctamente, la respuesta será la siguiente:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Medir con datos personalizados

Puedes usar el campo custom_data para crear reglas que determinen luego si una conversión se tendrá en cuenta o no. Esto es similar al uso de públicos personalizados offline. El número máximo de conversiones personalizadas que puedes tener por cuenta publicitaria es 40.

Por ejemplo, incluye la categoría de productos en las subidas con custom_data:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

A continuación, usa custom_data.{YOUR_CUSTOM_PARAM} para crear una regla de conversión personalizada:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Conversiones offline para socios

Para atribuir eventos de conversión offline al anuncio del cliente, sigue estos pasos. Las llamadas a la API para la mayoría de estos pasos son las mismas que cuando alguien administra su propio conjunto de eventos offline y se encarga de la administración de la campaña.

1. Socio: crea un conjunto de eventos offline.
2. Socio: comparte el conjunto de eventos con el administrador comercial del cliente.
3. Cliente: asigna el permiso de seguimiento offline de la cuenta publicitaria.
4. Cliente: define el seguimiento offline en los anuncios.
5. Socio: sube los eventos offline y consulta las estadísticas.
6. Socio: muestra las estadísticas de anuncios para el cliente

Estos pasos varían según cómo se configuren los permisos del socio o la agencia con las cuentas publicitarias del cliente:

• Puedes ser el propietario de todas las cuentas publicitarias, conjunto de anuncios u otros activos de tu cliente.
• Puedes tener permiso para acceder a los activos de tu cliente con el fin de realizar determinadas acciones.

Para configurar estos permisos, consulta Activos del administrador comercial.

Socio: comparte el conjunto de eventos

Comparte el conjunto de eventos con el administrador comercial del cliente. El cliente puede usar luego el conjunto de eventos para hacer el seguimiento de los anuncios.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Parámetros

Cliente: asigna el permiso de seguimiento offline de la cuenta publicitaria

Comparte los conjuntos de eventos offline creados por un socio con el cliente. Debes tener el rol de administrador en el administrador comercial o ser el usuario administrador del sistema que creó el conjunto de eventos offline para activar el seguimiento de los anuncios en una cuenta publicitaria. También puedes hacerlo si eres administrador de la cuenta publicitaria conectada con el conjunto de eventos offline. Para hacer esta llamada a la API, el negocio de la llamada debe tener acceso al conjunto de eventos offline.

Puedes asignar los permisos de seguimiento y visualización de los eventos offline a una cuenta publicitaria con esta llamada:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parámetros

Proporcionar identificadores externos

Es posible que haya situaciones en las que proporciones tu propio identificador externo para representar a un cliente y hacerlo coincidir con una persona. Para hacerlo, usa una instancia de extern_id que siga estas normas.

Los socios de datos que siguieron el proceso de coincidencia pueden usar el identificador del socio como identificador del espacio de nombres y extern_id como tpid.

Proporciona solo match_keys

Usamos match_keys para intentar determinar si los datos de conversión que compartiste pueden coincidir con un usuario de Meta. Si proporcionas match_keys, tampoco puedes incluir un parámetro namespace_id.

Proporciona match_keys y extern_id

Usamos match_keys para encontrar personas en Meta y reenviar asignaciones de {dataset_id, extern_id} a {facebook_user_id}. Si proporcionas match_keys y extern_id, tampoco puedes incluir un parámetro namespace_id.

Proporciona solo extern_id

Si ya enviaste datos con match_keys y extern_id, Meta usa {dataset_id, extern_id} para recuperar un {facebook_user_id}.

Proporciona namespace_id

El parámetro namespace_id se aplica a toda la llamada a la API. Puedes usarlo para remitir a otro conjunto de eventos offline al que puede acceder un identificador de perfil de socio o un negocio, o bien que sea de su propiedad. Si ya enviaste datos con match_keys y extern_id, Meta usa {namespace_id, extern_id} para recuperar un {facebook_user_id}. Solo debes proporcionar un extern_id por fila de datos.

Estadísticas y atribución

Consulta los eventos offline atribuidos a un anuncio que alguien visualizó o en el que hizo clic. Atribuimos las conversiones offline después de más de un día. Esto significa que debes configurar tu intervalo de atribución con los valores 28d_view o action_attribution_windows=['28d_view']'; de lo contrario, no verás ninguna conversión en los reportes. Consulta la API de estadísticas y la Guía de estadísticas.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Parámetros

Los resultados se ven de la siguiente manera:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

Por ejemplo, para ver la atribución:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

El resultado tiene el siguiente aspecto:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Opciones de procesamiento de datos para usuarios de EE. UU.

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Obtén más información sobre las Opciones de procesamiento de datos.