Ce guide aide les développeurs qui utilisent la spécification de l'API Event and Conversion (ECAPI) de l'IAB Tech Lab à mapper leurs données d'événement et de conversion au schéma d'ingestion d'événements de l'API Data Manager.
Présentation
L'ECAPI est une norme de données Open Source indépendante de la plate-forme qui définit la structure des événements et des conversions liés au marketing.
Le tableau suivant présente une vue d'ensemble des principaux attributs et principes de conception d'ECAPI par rapport à l'API Data Manager :
| ECAPI | API Data Manager | |
|---|---|---|
| Déduplication | S'appuie sur id (ID d'événement) |
S'appuie sur transaction_id |
| Routage des événements | Le champ data_set_id de la charge utile de l'événement indique la destination des données. |
Le champ destinations de la requête définit les destinations des événements.
L'API Data Manager permet également de router des événements vers plusieurs destinations dans une même requête. Pour en savoir plus, consultez Configurer des destinations et des en-têtes. |
| 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). Définissez les champs de consentement 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 de champs structurels
Les tables de mappage suivantes définissent la manière dont les champs individuels de la spécification ECAPI sont traduits en champs acceptés par l'API Data Manager :
Mappage de l'objet d'événement
ECAPI (event) |
API Data Manager (Event) |
Remarques |
|---|---|---|
data_set_id |
|
Vous pouvez définir des destinations aux niveaux suivants :
Pour en savoir plus sur la définition d'un Destination et la détermination de l'ID de destination du produit, consultez Configurer les destinations et les en-têtes.
|
id |
transaction_id |
Supprime les doublons d'événements de conversion. Consultez Comment Google traite les données multisources dans les guides Envoyer des événements pour Google Ads, Google Analytics et Floodlight. |
timestamp |
event_timestamp |
Obligatoire. L'API pour le suivi avancé des conversions utilise le format d'epoch Unix (entier) pour les codes temporels.
Lors du mappage vers l'API Data Manager, convertissez le champ event_timestamp dans l'un des formats suivants :
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 vers 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 |
Mappez vers un code de la devise à trois lettres en majuscules (par exemple, USD). |
source |
event_source |
Définissez ce paramètre sur une valeur de l'énumération EventSource. |
properties |
|
Mappez les éléments au niveau de la transaction au tableau cart_data.items dans l'objet CartData. L'API Data Manager accepte 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 la forme d'une 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 d'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 ID utilisateur. 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 vers 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 RFC 3339 event_timestamp.
Si vous utilisez des tampons de protocole, 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 des objets Address. |
gpp_string |
Aucun équivalent | Mappez le consentement à l'objet Consent au niveau de la requête ou de l'événement. Consultez Présentation de la confidentialité et du consentement. |
gpp_sid |
Aucun équivalent | Associez le consentement à l'objet Consent au niveau de la requête ou de l'événement. Consultez Présentation de la confidentialité et du consentement. |
mmt_only |
Aucun équivalent | |
click_id |
ad_identifiers.gclid |
Mappez-le à 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 l'identifiant publicitaire pour 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 de l'objet Address
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 compatible avec l'API Data Manager. |
city |
Aucun équivalent | Non compatible avec l'API Data Manager. |
state |
Aucun équivalent | Non compatible avec l'API Data Manager. |
country_code |
region_code |
Ne hachez pas. Correspond au champ region_code dans AddressInfo. Suivez les consignes de mise en forme. |
postal_code |
postal_code |
Ne hachez pas. Correspond au champ postal_code dans AddressInfo. Suivez les consignes de mise en forme. |
address_type |
Aucun équivalent | Non compatible avec 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 les données du panier. Définissez l'ID produit dans le compte Merchant Center. |
name |
additional_item_parameters |
Mappez-le en tant que item_name dans la liste additional_item_parameters. |
price |
unit_price |
|
discount |
additional_item_parameters ou custom_variables |
Mappez-le 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 un entier (int64). |
brand |
additional_item_parameters |
Mappez-le en tant que item_brand dans la liste additional_item_parameters. |
affiliation |
additional_item_parameters |
Mappez en tant que affiliation dans la liste additional_item_parameters. |
category |
additional_item_parameters |
Mappez en tant que item_category dans la liste additional_item_parameters. |
cattax |
Aucun équivalent | |
item_coupon |
additional_item_parameters |
Mappez en tant que coupon dans la liste additional_item_parameters. |
item_list_id |
additional_item_parameters |
Mappez-le en tant que item_list_id dans la liste additional_item_parameters. |
item_list_name |
additional_item_parameters |
Mappez en tant que item_list_name dans la liste additional_item_parameters. |
item_item_variant |
additional_item_parameters |
Mappez 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 EC 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_nameest 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 Conversion Cloud (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_itemcorrespond àview_itemviewed_item_listcorrespond àview_item_listviewed_cartcorrespond à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 d'API Data Manager valide :
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 formatées, hachées et encodées. Le type de compte GOOGLE_ADS dans la destination indique que la demande cible une destination Google Ads :
{
"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
}
]
}
}
]
}