Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mappage des spécifications ECAPI

Ce guide aide les développeurs qui utilisent la spécification IAB Tech Lab Event and Conversion API (ECAPI) à mapper leurs données d'événements et de conversions au schéma d'ingestion d'événements de l'API Data Manager.

Présentation

ECAPI est une norme de données Open Source, indépendante de la plate-forme, conçue pour définir la structure des événements et des conversions liés au marketing.

Le tableau suivant fournit une vue d'ensemble de la façon dont les principaux attributs et principes de conception de l'ECAPI se comparent à l'API Data Manager.

	ECAPI	API Data Manager
Déduplication	Repose sur `id` (ID d'événement)	Dépend de `transaction_id`
Routage des événements	La destination des données est indiquée par le champ `data_set_id` dans la charge utile de l'événement.	Le champ `destinations` de la requête définit la ou les destinations des événements. L'API Data Manager permet également de router les événements vers plusieurs destinations dans une seule requête. Pour en savoir plus, consultez le guide des destinations.
Champs de confidentialité et de consentement	Chaînes de consentement de la Global Privacy Platform (GPP)	L'API Data Manager n'accepte ni n'analyse les chaînes de consentement de la Global Privacy Platform (GPP). Les champs de consentement doivent être définis dans l'objet `Consent`. Vous pouvez définir le consentement au niveau de la demande (ce qui s'applique à tous les événements de la demande) ou au niveau de l'événement (ce qui vous permet de spécifier différents paramètres de consentement pour des événements individuels).

Mappage des champs structurels

Les tableaux de mappage suivants définissent la façon dont les champs individuels de la spécification ECAPI sont traduits en champs acceptés par l'API Data Manager.

Mappage des objets d'événement

ECAPI (`event`)	API Data Manager (`Event`)	Remarques
`data_set_id`	`destinations[].product_destination_id` (au niveau de la demande) `destination_references` (niveau de l'événement)	Peut être défini aux niveaux suivants : Niveau de la requête (obligatoire) : spécifiez la liste des `destinations` dans `IngestEventsRequest`. Au niveau de l'événement : utilisez le champ `destination_references` sur l'objet `Event`. Ajoutez une entrée pour spécifier la destination de la liste `destinations` qui doit recevoir l'événement. Pour savoir comment définir un `Destination` et déterminer l'ID de destination du produit, consultez Configurer des destinations et des en-têtes.
`id`	`transaction_id`	Cette valeur permet de dédupliquer les événements de conversion. En savoir plus
`timestamp`	`event_timestamp`	Obligatoire. ECAPI utilise le format epoch Unix (entier) pour les codes temporels. Lorsque vous mappez le champ `event_timestamp` à l'API Data Manager, il doit être converti dans l'un des formats suivants : Si vous utilisez le format JSON, définissez une valeur au format RFC 3339. Si vous utilisez des tampons de protocole, utilisez `Timestamp` et définissez les champs `seconds` et (facultativement) `nanoseconds`. Pour en savoir plus, consultez Format du code temporel.
`event_type`/`custom_event`	`event_name`	Il peut s'agir d'un nom d'événement recommandé (par exemple, `purchase`) ou d'un nom d'événement personnalisé. Pour en savoir plus, consultez Noms d'événements standards.
`user_data`	`user_data`	Mappe l'objet `UserData`, qui accepte une liste d'objets `UserIdentifier`.
`value`	`conversion_value`	Mappez directement en tant que double ou float représentant la valeur monétaire de la conversion.
`currency_code`	`currency`	Associez-le à un code de devise à trois lettres en majuscules (par exemple, `USD`).
`source`	`event_source`	Définissez une valeur à partir de l'énumération EventSource.
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	Les éléments au niveau de la transaction peuvent être mappés au tableau `cart_data.items` dans l'objet `CartData`. L'API Data Manager est compatible avec plusieurs champs Merchant Center facultatifs pour les produits qui existent dans les comptes Merchant Center. Si votre destination est une action de conversion Google Ads, vous pouvez également inclure des paramètres personnalisés supplémentaires dans le champ `custom_variables` sous forme de liste d'objets `CustomVariable`. Si votre destination est un flux de données Google Analytics, vous pouvez inclure des paramètres d'événement supplémentaires dans le champ `additional_event_parameters` sous forme de liste d'objets `AdditionalEventParameter`.
`ext`	Aucun équivalent

Mappage des objets de données utilisateur

Dans l'API Data Manager, le champ user_data de l'objet Event accepte un objet UserData. Cette méthode attend une liste d'objets UserIdentifier, qui peuvent contenir des identifiants utilisateur individuels tels que des adresses e-mail, des numéros de téléphone ou des composants d'adresse.

ECAPI (`user_data`)	API Data Manager (`Event`)	Remarques
`customer_identifier`	`user_id` (Google Analytics)	Pour les événements Google Analytics, le champ `user_id` représente un User-ID. L'API Data Manager n'est pas compatible avec les champs de numéro client génériques pour les autres destinations.
`uids`	Aucun équivalent	L'API Data Manager n'est pas compatible avec un tableau `uids` structuré contenant des types d'agents et des domaines.
`customer_segments`	`user_properties`	Carte pour `UserProperties` sur `Event`.
`email_address`	`user_data.user_identifiers[].email_address`	Définissez l'adresse e-mail mise en forme et hachée. Vous pouvez également chiffrer l'adresse e-mail hachée.
`phone_numbers`	`user_data.user_identifiers[].phone_number`	Définissez le numéro de téléphone mis en forme et haché. Vous pouvez également chiffrer le numéro de téléphone haché.
`utcoffset`	Aucun équivalent	Si vous utilisez le format JSON, vous pouvez spécifier le décalage du fuseau horaire directement dans la chaîne `event_timestamp` de la norme RFC 3339. Si vous utilisez des protocol buffers, vous pouvez utiliser des fonctions utilitaires telles que `Timestamps.parse(String)` pour gérer la conversion du fuseau horaire en secondes et en nanosecondes. Pour en savoir plus, consultez Format du code temporel.
`address`	`user_data.user_identifiers[].address`	Mappe un objet `AddressInfo`. Consultez Mappage de l'objet Address.
`gpp_string`	Aucun équivalent	Le consentement doit être mappé à l'objet `Consent` au niveau de la requête ou de l'événement. Consultez la Présentation de la confidentialité et du consentement.
`gpp_sid`	Aucun équivalent	Le consentement doit être mappé à l'objet `Consent` au niveau de la requête ou de l'événement. Consultez la Présentation de la confidentialité et du consentement.
`mmt_only`	Aucun équivalent
`click_id`	`ad_identifiers.gclid`	Mappez l'ID de clic Google (`gclid`). Pour en savoir plus, consultez `AdIdentifiers`.
`impression_id`	`ad_identifiers.impression_id`	Pour en savoir plus, consultez `AdIdentifiers`.
`event_ip_address`	`event_device_info.ip_address`	Consultez `DeviceInfo` pour connaître les champs disponibles.
`event_user_agent`	`event_device_info.user_agent`	Consultez `DeviceInfo` pour connaître les champs disponibles.
`ifa`	`ad_identifiers.mobile_device_id`	Mappez-le à l'identifiant publicitaire mobile (IDFA sur iOS, AdID sur Android). Pour en savoir plus, consultez `AdIdentifiers`.
`landing_ip_address`	`ad_identifiers.landing_page_device_info.ip_address`	Consultez `DeviceInfo` pour connaître les champs disponibles.
`landing_user_agent`	`ad_identifiers.landing_page_device_info.user_agent`	Consultez `DeviceInfo` pour connaître les champs disponibles.
`age_range`	Aucun équivalent
`gender`	Aucun équivalent
`ext`	Aucun équivalent

Mappage d'objet d'adresse

ECAPI (`address`)	API Data Manager (`AddressInfo`)	Remarques
`first_name`	`given_name`	Correspond au champ `given_name` dans `AddressInfo`. Suivez les consignes de mise en forme et de hachage. Vous pouvez également chiffrer les attributs hachés d'une adresse.
`last_name`	`family_name`	Correspond au champ `family_name` dans `AddressInfo`. Suivez les consignes de mise en forme et de hachage. Vous pouvez également chiffrer les attributs hachés d'une adresse.
`street`	Aucun équivalent	Non disponible dans l'API Data Manager
`city`	Aucun équivalent	Non disponible dans l'API Data Manager
`state`	Aucun équivalent	Non disponible dans l'API Data Manager
`country_code`	`region_code`	Ne pas hacher Correspond au champ `region_code` dans `AddressInfo`. Suivez les consignes de mise en forme.
`postal_code`	`postal_code`	Ne pas hacher Correspond au champ `postal_code` dans `AddressInfo`. Suivez les consignes de mise en forme.
`address_type`	Aucun équivalent	Non disponible dans l'API Data Manager
`ext`	Aucun équivalent

Mappage des objets d'article

ECAPI (`item`)	API Data Manager (`Item`)	Remarques
`id`	`item_id`	Obligatoire pour les événements Google Analytics. Définissez un identifiant unique standard pour l'article.
Aucun équivalent	`merchant_product_id`	Obligatoire pour les conversions Floodlight et les conversions Google Ads avec données du panier. Définissez l'ID du produit dans le compte Merchant Center.
`name`	`additional_item_parameters`	Carte en tant que `item_name` dans la liste `additional_item_parameters`.
`price`	`unit_price`
`discount`	`additional_item_parameters` ou `custom_variables`	Mappez-la en tant que `discount` dans `additional_item_parameters` (pour Google Analytics) ou en tant que variable personnalisée dans `custom_variables` (pour Google Ads).
`quantity`	`quantity`	Convertissez la valeur `float` en entier (`int64`).
`brand`	`additional_item_parameters`	Carte en tant que `item_brand` dans la liste `additional_item_parameters`.
`affiliation`	`additional_item_parameters`	Carte en tant que `affiliation` dans la liste `additional_item_parameters`.
`category`	`additional_item_parameters`	Carte en tant que `item_category` dans la liste `additional_item_parameters`.
`cattax`	Aucun équivalent
`item_coupon`	`additional_item_parameters`	Carte en tant que `coupon` dans la liste `additional_item_parameters`.
`item_list_id`	`additional_item_parameters`	Carte en tant que `item_list_id` dans la liste `additional_item_parameters`.
`item_list_name`	`additional_item_parameters`	Carte en tant que `item_list_name` dans la liste `additional_item_parameters`.
`item_item_variant`	`additional_item_parameters`	Carte en tant que `item_variant` dans la liste `additional_item_parameters`.
`item_location_id`	`additional_item_parameters`	Carte de `location_id` à `additional_item_parameters`.
`ext`	Aucun équivalent

Noms des événements standards

Les événements standards de l'API ECAPI sont très proches des conventions de dénomination de Google Analytics.

Si vous envoyez des événements à un flux de données Google Analytics, le champ event_name est obligatoire.
Consultez la documentation de référence sur les événements recommandés Google Analytics pour connaître les champs, les paramètres et les exemples de requêtes d'ingestion de l'API Data Manager associés à chaque événement.
Vous pouvez également envoyer des événements personnalisés à condition qu'ils respectent les règles de dénomination des événements.

La plupart des événements standards de l'API EC (comme purchase, add_to_cart, begin_checkout, search et refund) ont le même nom d'événement que les événements recommandés de Google Analytics. Toutefois, il existe quelques exceptions où Google Analytics utilise le présent au lieu du passé :

viewed_item correspond à view_item
viewed_item_list correspond à view_item_list
viewed_cart correspond à view_cart

Exemples de requête

Les onglets suivants comparent une charge utile d'événement de conversion ECAPI et sa représentation en tant que IngestEventsRequest valide de l'API Data Manager.

ECAPI

Voici un exemple de charge utile JSON conforme à la spécification ECAPI.

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

API Data Manager

Voici un exemple de IngestEventsRequest pour les données d'événement mises en forme, hachées et encodées. Il s'agit d'une destination Google Ads, comme indiqué par le type de compte GOOGLE_ADS dans la destination.

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}