API de conversiones offline

Usa la API de conversiones offline para enviar eventos de conversión offline y consultar cuántos clientes han visto los anuncios de Meta o han hecho clic en ellos antes de la conversión.

Antes de empezar

Para usar esta API, necesitas:

1. Meta Business Manager

Si aún no tienes una cuenta, créala.

2. Identificador de aplicación de Meta

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

• Visita Business Manager > Configuración de la empresa.
• Selecciona Aplicaciones.
• Haz clic en Añadir una aplicación nueva y sigue las instrucciones.

3. Revisión de la aplicación y permisos

Las reglas sobre los permisos y la revisión de la aplicación dependen de cómo implementas nuestra API:

4. Identificador y usuario del sistema de Business Manager

Si una aplicación cuenta con acceso de usuario al sistema, podrá enviar datos a Meta mediante la API. Para crearlo, haz lo siguiente:

• Visita Business Manager > Configuración de la empresa.
• Selecciona Usuarios del sistema.
• Haz clic en Añadir nuevo usuario del sistema.
• Selecciona Usuario administrador del sistema como rol para el usuario del sistema.

Un identificador de acceso permite acceder a los datos de Meta. Para crear identificadores de acceso de usuarios del sistema, haz lo siguiente:

• Visita Business Manager > Configuración de la empresa.
• Selecciona Usuarios del sistema.
• Selecciona el usuario del sistema y haz clic en Generar un identificador nuevo.
• Selecciona tu aplicación y, para ámbito, selecciona ads_management.

5. Cuenta publicitaria

Para poner en circulación campañas publicitarias en Meta, necesitas una cuenta publicitaria. Para crear una, consulta API de marketing o Servicio de ayuda para empresas: Información sobre la configuración de la empresa en Meta Business Manager.

6. Concesión de acceso a la cuenta publicitaria para el usuario del sistema

Concede acceso a la cuenta publicitaria al usuario del sistema.

• Dirígete a Business Manager > 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

Se trata de archivos que se han subido con datos de conversión sin conexión. Al crear un anuncio, establece tracking_spec en el identificador del conjunto de eventos offline para atribuir correctamente los eventos. Seguidamente, puedes crear conjuntos de eventos, ver estadísticas de importaciones y eliminar o modificar estos datos en Business Manager.

Con las implementaciones más antiguas, puedes realizar operaciones CRUD en los conjuntos de eventos offline en el nivel de Business Manager para compartir los conjuntos de eventos con otros objetos y entidades.

Subida de datos de eventos

Necesitas un acceso específico para crear conjuntos de eventos offline, subir o ver los datos de un conjunto de eventos. También lo necesitas para asignar estos permisos a una cuenta publicitaria. Debes contar con uno de los siguientes roles:

• Administrador de Business Manager;
• Usuario administrador del sistema que creó el conjunto de eventos offline;
• Administrador del objeto ad_account conectado al conjunto de eventos offline.

Consulta la referencia sobre los conjuntos de eventos de conversión offline.

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

Realiza una solicitud 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 un valor de id del conjunto de eventos:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parámetros

2. Asigna los permisos de la cuenta publicitaria

Para asignar los permisos de seguimiento y lectura 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

Al actualizar tracking_spec, se sobrescribe. Asegúrate de realizar la solicitud GET primero y, a continuación, añade el objeto String asociado del conjunto de eventos offline al objeto tracking_spec existente. 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 los 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 desde 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, realiza 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 parámetro upload_tag para todas las llamadas a la API de subida de eventos del mismo lote a fin de agruparlas. De este modo, podrás depurar las subidas de eventos. Asimismo, debes usar este parámetro en todas las subidas de eventos realizadas en más de una llamada a la API.

Entre los parámetros de data se 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 parámetro upload_tag para todas las llamadas a la API de subida de eventos del mismo lote a fin de agruparlas. De este modo, podrás depurar las subidas de eventos. Asimismo, debes usar este parámetro en todas las subidas de eventos que precisen más de una llamada a la API.

Claves de coincidencia

El parámetro match_keys es un conjunto de identificadores que se usan para establecer coincidencias con las personas para realizar la atribución. Consulta Audiencias personalizadas a partir de datos de CRM para normalizar los datos y aplicar algoritmos hash en ellos. Solo se admite el algoritmo SHA256 y no se aceptan datos sin cifrar.

La respuesta:

En los errores se muestra una excepción que incluye las entradas no válidas y el motivo. Corrige los errores u omite las filas de datos con errores y reintenta la llamada a la API.

Ver estadísticas de carga

El usuario del sistema o el administrador de Business Manager que crea un conjunto de eventos offline puede recuperar las estadísticas de carga. Cualquier administrador del objeto ad_account conectado a dicho conjunto puede leer los datos.

Para ver estadísticas sobre los conjuntos de eventos offline, como entradas válidas y coincidentes:

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

Consulta desgloses diarios de eventos offline en Offline Events Manager en Business Manager. Para acceder a 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

Creación de conversiones personalizadas offline

Actualmente, las conversiones personalizadas offline no proporcionan relleno. No atribuimos datos de las cargas de eventos que se realizan antes de crear las conversiones personalizadas. Los datos de las conversiones personalizadas offline no se pueden usar para la optimización de la entrega de anuncios. Consulta la referencia sobre las conversiones personalizadas.

Para crear una conversión personalizada con tus eventos offline, realiza una solicitud 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:

En caso de realizarse correctamente, la respuesta será la siguiente:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Medir con datos personalizados

Puedes usar el campo custom_data para crear reglas que posteriormente determinen si una conversión se cuenta o no. Es similar a las audiencias personalizadas fuera de internet. El número máximo de conversiones personalizadas que puedes tener por cuenta publicitaria es de 40.

Por ejemplo, incluye la categoría de producto 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 los eventos de conversión offline al anuncio de tu cliente, sigue estos pasos. En la mayoría de estos pasos, se realizan las mismas llamadas a la API que cuando alguien administra su propio conjunto de eventos offline o cuando se administran las campañas.

1. Socio: crear un conjunto de eventos offline
2. Socio: compartir el conjunto de eventos con el Business Manager del cliente
3. Cliente: asignar el permiso de seguimiento fuera de internet para la cuenta publicitaria
4. Cliente: configurar el seguimiento fuera de internet en los anuncios
5. Socio: subir eventos offline y ver estadísticas
6. Socio: mostrar las estadísticas de anuncios para el cliente

Estos pasos variarán dependiendo de cómo se configuren los permisos de agencia o socio respecto a las cuentas publicitarias del cliente:

• Puedes ser propietario de todas las cuentas publicitarias, los conjuntos de eventos o cualquier otro tipo de activo de tu cliente.
• Puedes tener permiso para realizar ciertas acciones con los activos de tu cliente.

Para configurar estos permisos, consulta Activos de Business Manager.

Socio: compartir un conjunto de eventos

Comparte el conjunto de eventos con el Business Manager de tu cliente. A continuación, tu cliente podrá usarlo para realizar 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: asignar el permiso de seguimiento fuera de internet para la cuenta publicitaria

Comparte los conjuntos de eventos offline que ha creado un socio con su cliente. Para poder activar el seguimiento de los anuncios en una cuenta publicitaria, debes ser el usuario administrador del sistema o el administrador de Business Manager que ha creado el conjunto de eventos offline. También puedes activarlo si eres un administrador de la cuenta publicitaria conectada al conjunto de eventos offline. Para realizar esta llamada a la API, el negocio que figura debe tener acceso al conjunto de eventos offline.

Puedes asignar permisos de visualización y de seguimiento de eventos offline a una cuenta publicitaria con la siguiente 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

Especificación de identificadores externos

En determinadas situaciones, puedes proporcionar tus propios identificadores externos para representar a un cliente y establecer una coincidencia con una persona. Para ello, usa extern_id de acuerdo con las normas que se indican a continuación.

Los socios de datos que han realizado el proceso de establecimiento de coincidencias pueden usar el identificador de socio como identificador del espacio de nombres y extern_id como tpid.

Proporcionar solo match_keys

Se usa el parámetro match_keys para intentar determinar si con los datos de conversión que has compartido se pueden establecer coincidencias con un usuario de Meta. Si proporcionas match_keys, tampoco puedes proporcionar un parámetro namespace_id.

Proporcionar match_keys y extern_id

Se usa el parámetro match_keys para intentar buscar personas en Meta y reenviar las asignaciones de {dataset_id, extern_id} a {facebook_user_id}. Si proporcionas match_keys y extern_id, no puedes proporcionar también namespace_id.

Proporcionar solo extern_id

Si ya has enviado datos con match_keys y extern_id, Meta usa {dataset_id, extern_id} para recuperar un valor de {facebook_user_id}.

Proporcionar namespace_id

El parámetro namespace_id se aplica a toda la llamada a la API. Puedes usarlo para consultar otro conjunto de eventos offline que esté accesible o pertenezca a un identificador del perfil de socio o negocio. Si ya has enviado datos con match_keys y extern_id, Meta usa {namespace_id, extern_id} para recuperar un valor de {facebook_user_id}. Debes proporcionar solo un valor de extern_id por fila de datos.

Insights y atribución

Consulta los eventos offline que se atribuyen a un anuncio que alguien ha visto o en el que ha hecho clic. Tardamos más de un día en atribuir las conversiones offline. Esto quiere decir que debes establecer el intervalo de atribución en 28d_view o action_attribution_windows=['28d_view']'. De lo contrario, no aparecerá ninguna conversión en los informes. Consulta API de insights y la Guía de insights.

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

El resultado será similar al siguiente:

{
  "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 será similar al siguiente:

{
  "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 tratamiento 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 tratamiento de datos.