Microsoft Advertising Conversions API : balise UET plus événements serveur avec msclkid

Les briques

• Une balise UET (Outils → Balises UET). Son identifiant numérique est public et figure dans le snippet JavaScript.
• Un objectif de conversion de type « Événement » ou « URL de destination » lié à cette balise ; les événements serveur sont mis en correspondance avec les objectifs par nom d'événement, catégorie, libellé et valeur, exactement comme les événements de balise.
• Un jeton d'accès OAuth 2.0 pour l'API Microsoft Advertising (scope msads.manage) délivré au compte propriétaire de la balise. Track l'obtient et le renouvelle via la connexion OAuth Microsoft et le conserve dans le coffre-fort.

La requête

POST https://capi.uet.microsoft.com/v1/{tagId}/events avec Authorization: Bearer <token> et un tableau JSON d'événements :

{
  "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 est exprimé en millisecondes depuis l'epoch. eventType vaut custom pour les événements de conversion et pageLoad pour les pages vues. Avec continueOnValidationError: true, l'endpoint accepte les lignes valides et signale les lignes invalides avec leur index ; Track marque ces lignes comme payload invalide et ne les réessaie pas, tandis que les réponses HTTP 5xx et 429 sont réessayées avec temporisation.

Une requête peut contenir jusqu'à 1 000 événements.

Déduplication avec la balise UET

Lorsque la balise JavaScript UET déclenche elle aussi l'événement, les deux chemins doivent partager le même eventId et le même nom d'événement. Dans le navigateur, transmettez l'identifiant dans les paramètres de l'événement (window.uetq.push('event', 'purchase', { revenue_value: 129.9, currency: 'EUR', event_id: '…' })) ; le serveur envoie la même valeur dans eventId. Microsoft ne compte alors la conversion qu'une fois. Le SDK Track génère un identifiant par action et le transmet aussi bien au template UET qu'au collecteur.

Identifiants

• msclkid — l'identifiant de clic que Microsoft ajoute aux URL des pages de destination. Capturez-le après consentement marketing et stockez-le en first-party ; sans lui, les événements serveur ne peuvent être mis en correspondance que par identifiants hachés.
• em et ph — hachages SHA-256 de l'e-mail et du numéro de téléphone normalisés.
• anid — l'identifiant publicitaire Microsoft pour le trafic applicatif.
• clientUserAgent et clientIpAddress — recommandés pour les événements web et disponibles depuis le collecteur lorsque la politique autorise la transmission de l'adresse IP.

Tests

L'API ne dispose d'aucun indicateur de test. Un événement de test envoyé depuis l'assistant est un événement réel sur l'identifiant de balise que vous avez configuré : donnez donc à l'environnement de préproduction (staging) son propre identifiant de balise UET et réservez l'identifiant de production à la production ; l'assistant affiche dans les deux cas la réponse ligne par ligne de Microsoft. Lorsque la destination quitte le mode test, c'est l'identifiant de balise de l'environnement de production qui reçoit les événements.

Erreurs

Chaque tentative, y compris les lignes rejetées par Microsoft, est visible dans le moniteur des destinations avec l'aperçu masqué du payload.