Microsoft Advertising Conversions API: etiqueta UET más eventos de servidor con msclkid

Las piezas

• Una etiqueta UET (Herramientas → Etiquetas de UET). Su ID numérico es público y aparece en el snippet de JavaScript.
• Un objetivo de conversión de tipo «Evento» o «URL de destino» vinculado a esa etiqueta; los eventos de servidor se emparejan con los objetivos por nombre de evento, categoría, label y valor, igual que los eventos de la etiqueta.
• Un token de acceso OAuth 2.0 para la Microsoft Advertising API (scope msads.manage) emitido para la cuenta propietaria de la etiqueta. Track lo obtiene y lo renueva a través de la conexión OAuth de Microsoft y lo guarda en el almacén cifrado.

La petición

POST https://capi.uet.microsoft.com/v1/{tagId}/events con Authorization: Bearer <token> y un array JSON de eventos:

{
  "data": [{
    "eventType": "custom",
    "eventName": "purchase",
    "eventId": "01J9EXAMPLESOURCEEVENTID00",
    "eventTime": 1767225600000,
    "eventSourceUrl": "https://shop.example/thank-you",
    "userData": { "em": "<sha256>", "ph": "<sha256>", "msclkid": "…", "clientUserAgent": "…", "clientIpAddress": "…" },
    "eventData": { "eventValue": 129.9, "eventCurrency": "EUR", "items": [{ "id": "SKU-1", "name": "Product", "price": 99.9, "quantity": 1 }] }
  }],
  "continueOnValidationError": true
}

eventTime son milisegundos desde epoch. eventType es custom para eventos de conversión y pageLoad para vistas de página. Con continueOnValidationError: true, el endpoint acepta las filas válidas e informa de las no válidas con su índice; Track marca esas filas como payload no válido y no las reintenta, mientras que las respuestas HTTP 5xx y 429 se reintentan con backoff.

En una sola petición caben hasta 1.000 eventos.

Deduplicación con la etiqueta UET

Si la etiqueta JavaScript de UET también dispara el evento, ambas vías deben compartir el mismo eventId y el mismo nombre de evento. En el navegador, pasa el ID en los parámetros del evento (window.uetq.push('event', 'purchase', { revenue_value: 129.9, currency: 'EUR', event_id: '…' })); el servidor envía el mismo valor en eventId. Microsoft cuenta entonces la conversión una sola vez. El SDK de Track genera un ID por acción y lo pasa por igual a la plantilla de UET y al collector.

Identificadores

• msclkid — el ID de clic que Microsoft añade a las URL de la landing page. Captúralo tras el consentimiento de marketing y guárdalo en first-party; sin él, los eventos de servidor solo pueden emparejarse mediante identificadores con hash.
• em y ph — hashes SHA-256 del correo electrónico y del número de teléfono normalizados.
• anid — el ID publicitario de Microsoft para tráfico de apps.
• clientUserAgent y clientIpAddress — recomendados para eventos web y disponibles desde el collector cuando la política permite reenviar la IP.

Pruebas

La API no tiene flag de prueba. Un evento de prueba enviado desde el asistente es un evento real en el ID de etiqueta que hayas configurado, así que da al entorno de staging su propio ID de etiqueta UET y reserva el ID de etiqueta de producción para producción; el asistente muestra la respuesta fila a fila de Microsoft en ambos casos. Cuando el destino sale del modo de prueba, el ID de etiqueta del entorno de producción recibe los eventos.

Errores

Cada intento, incluidas las filas que Microsoft rechazó, se ve en el monitor de destinos con la vista previa enmascarada del payload.