Enviar eventos

Puedes completar esta guía de inicio rápido para familiarizarte con el envío de datos de eventos.

Usa la API de Data Manager en cualquiera de las siguientes situaciones:

• Eventos en línea: Envía datos de eventos como una fuente de datos adicional para las conversiones de tus etiquetas, de modo que puedas maximizar los indicadores de interacción con los anuncios y fortalecer tus datos y tu rendimiento general.

• Eventos sin conexión: Envía datos de eventos para las conversiones sin conexión o las conversiones avanzadas de clientes potenciales.

Elige la versión de la guía que deseas ver:

Anunciante Socio de datos

En esta guía de inicio rápido, completarás los siguientes pasos:

1. Prepara un objeto Destination para recibir datos de eventos.
2. Prepara los datos de eventos para enviarlos.
3. Compila una solicitud de IngestionService para eventos.
4. Envía la solicitud con el Explorador de APIs de Google.
5. Comprende las respuestas de éxito y error.

Prepara un destino

Antes de enviar datos, debes preparar el destino al que se enviarán. Aquí tienes un ejemplo de Destination que puedes usar:

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• Establece el accountId del operatingAccount en el ID de la cuenta de Google Ads que recibirá los datos del evento. El product del operatingAccount debe ser GOOGLE_ADS.

• Establece productDestinationId en el ID de la acción de conversión para los eventos. En el caso de los eventos en línea, la acción de conversión debe ser una acción de conversión de Google Ads con type establecida en WEBPAGE. En el caso de los eventos sin conexión, la acción de conversión debe ser una acción de conversión de Google Ads con type establecida en UPLOAD_CLICKS.

  En esta guía, se muestra cómo crear una solicitud que envíe cada evento a la misma acción de conversión. Si deseas enviar eventos para varias acciones de conversión en la misma solicitud, consulta varios destinos.

Prepara los datos de eventos

Considera los siguientes datos de eventos. Cada tabla corresponde a un evento de conversión. Cada evento de conversión tiene una marca de tiempo, su acción de conversión y su valor.

Cada evento puede tener identificadores de publicidad, como gclid, o identificadores de usuario, como direcciones de correo electrónico, números de teléfono y dirección. Un evento también puede tener información sobre el usuario evaluado en el momento del evento, como el valor del cliente o si es un cliente nuevo, recurrente o reactivado.

Estos son los datos del primer evento:

Estos son los datos del segundo evento:

Formatea los datos

Da formato a los campos según se especifica en la guía de formato. Estos son los datos del primer evento después del formato:

Estos son los datos del segundo evento después del formato:

Genera un hash y codifica los datos

Además, las direcciones de correo electrónico, los nombres y los apellidos con formato deben tener una codificación hash con el algoritmo SHA-256 y codificarse con codificación hexadecimal o Base64. Estos son los datos del primer evento después de aplicar formato, generar un hash y codificar con codificación hexadecimal:

A continuación, se muestran los datos del segundo evento después de aplicar el formato, el hash y la codificación con codificación hexadecimal:

Convierte los datos en un objeto Event

Convierte los datos con formato y codificación hash de cada evento en un Event. Completa los siguientes campos obligatorios:

• event_timestamp: Es la fecha y hora en que ocurrió el evento.
• transaction_id: Es el identificador único del evento.
• event_source: Es la fuente del evento. Se requiere para los eventos sin conexión. Es opcional para los eventos en línea. Si se especifica para un evento en línea, debe ser WEB.
• ad_identifiers o user_data: El evento debe tener un identificador de anuncio o datos del usuario. Envía ambos si los tienes para el evento.

Consulta la documentación de referencia de Event para obtener la lista completa de campos disponibles. Completa cualquier campo en el que tengas un valor para el evento.

A continuación, se muestra un ejemplo de Event para los datos con formato, codificados y con hash del segundo evento:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "eventTimestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ],
      "userProperties": {
        "customerType": "RETURNING"
      }
   }
}

Crea el cuerpo de la solicitud

Combina Destination y Events para el cuerpo de la solicitud:

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       }
     }
  ],
  "validateOnly": true
}

1. Actualiza los marcadores de posición en el cuerpo, como OPERATING_ACCOUNT_ID y CONVERSION_ACTION_1_ID, con los valores de tu cuenta y destino.
2. Establece validateOnly en true para validar la solicitud sin aplicar los cambios. Cuando esté todo listo para aplicar los cambios, establece validateOnly en false.
3. Ten en cuenta que este ejemplo no usa encriptación.

Envía la solicitud

1. Copia el cuerpo de la solicitud con el botón de copia que se encuentra en la parte superior derecha del ejemplo.
2. Haz clic en el botón API de la barra de herramientas.
3. Pega el cuerpo de la solicitud copiado en el cuadro del Cuerpo de la solicitud.
4. Haz clic en el botón Ejecutar, completa las indicaciones de autorización y revisa la respuesta.

Respuestas de éxito

Una solicitud correcta devuelve una respuesta con un objeto que contiene un requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Respuestas de error

Una solicitud fallida genera un código de estado de respuesta de error, como 400 Bad Request, y una respuesta con detalles del error.

Por ejemplo, un email_address que contiene una cadena de texto sin formato en lugar de un valor codificado en hexadecimal produce la siguiente respuesta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Un email_address que no se hashea y solo se codifica en hexadecimal produce la siguiente respuesta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Envía eventos para varios destinos

Si tus datos contienen eventos para diferentes destinos, puedes enviarlos en la misma solicitud usando referencias de destino.

Por ejemplo, si tienes un evento para el ID de acción de conversión 123456789 y otro para el ID de acción de conversión 777111122, envía ambos eventos en una sola solicitud configurando el reference de cada Destination. El reference lo define el usuario. El único requisito es que cada Destination tenga un reference único. Esta es la lista de destinations modificada para la solicitud:

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

Establece el destination_references de cada Event para enviarlo a uno o más destinos específicos. Por ejemplo, aquí hay un Event que solo es para el primer Destination, por lo que su lista de destination_references solo contiene el reference del primer Destination:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

El campo destination_references es una lista, por lo que puedes especificar varios destinos para un evento. Si no configuras el destination_references de un Event, la API de Data Manager envía el evento a todos los destinos de la solicitud.

Próximos pasos

• Configura la autenticación y tu entorno con una biblioteca cliente.
• Obtén información sobre los requisitos de formato, hash y codificación para cada tipo de datos.
• Obtén más información para encriptar datos del usuario.
• Obtén más información sobre las prácticas recomendadas.
• Obtén información sobre los límites y las cuotas.