User-agent de l'application
Dans le cadre de nos efforts globaux de lutte contre le spam, nous avons développé une spécification standardisée pour l'en-tête User-Agent envoyé par un produit d'analyse ou d'annonces pour le compte d'un utilisateur de l'application. Le user-agent de l'application peut être dérivé du code natif pour respecter la spécification suivante:
name version (os_and_version; locale; device; build; Proxy)
La définition de ces champs est la suivante:
Composants user-agent | |
---|---|
name | Nom du produit d'analyse ou d'annonce. ( Notez que si le user-agent est construit côté client, Android// Specified by API consumer. iOS// Specified by API consumer. |
version | Version du produit d'analyse/d'annonces.
( Android// Specified by API consumer. iOS// Specified by API consumer. |
os_and_version | Système d'exploitation et version du système d'exploitation sur lesquels l'application est exécutée. ( AndroidString osAndVersion = "Android " + Build.VERSION.RELEASE; iOSUIDevice *uid = [UIDevice currentDevice]; NSString *osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]]; |
locale | Tag de paramètres régionaux IETF pour l'appareil, utilisant la langue et le code pays à deux lettres séparés par un trait de soulignement.
( AndroidString locale = Locale.getDefault(); iOSNSString *locale = [[NSLocale currentLocale] localeIdentifier] |
device | Nom de l'appareil physique exécutant le produit d'analyse/d'annonces.
( AndroidString device = Build.MODEL; iOS@import Darwin.sys.sysctl; NSString *device(void) { size_t bufferSize = 64; NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; } |
build | "Build/" suivi du numéro de build du système d'exploitation.
( AndroidString build = "Build/" + Build.ID; iOS@import Darwin.sys.sysctl; NSString *build(void) { size_t bufferSize = 64; NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("kern.osversion", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; } |
N'incluez ; Proxy
qu'à la fin du user-agent de l'application lorsque vous créez le user-agent côté serveur de l'application. Si le user-agent de l'application est entièrement créé côté client, excluez ; Proxy
. Ainsi, un user-agent d'application peut être:
- Android :
AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
- iOS :
AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
Demande de suivi des conversions
Les requêtes de suivi des conversions permettent d'informer Google Ads d'un événement dans l'application qui doit être suivi en tant que conversion et/ou utilisé pour remplir une liste de remarketing. Il permet aussi de récupérer les métadonnées décrivant tout clic ayant précédé l'événement.
Tous les appels d'API sont effectués vers le domaine www.googleadservices.com
. Les requêtes de conversion sont des requêtes POST
via HTTPS sur le chemin suivant :
/pagead/conversion/app/version, où version est la version souhaitée de l'API de suivi des conversions. Actuellement, la seule version valide est
1.0
.
Une demande de conversion d'application standard contient les paramètres suivants.
Demande de suivi des conversions | |
---|---|
dev_token |
Obligatoire Lieu: requête Jeton de développeur statique unique émis pour le consommateur d'API. Z_eErE4DkvcKjDM1OVE4c4 |
link_id |
Obligatoire Lieu: requête Identifiant du lien qui lie le jeton de développeur du client de l'API à une application spécifique. 31FF8D67E5BB5DD5029DCC2734C2F884 |
app_event_type |
Obligatoire Lieu: requête Nom de l'événement dans l'application. Ce champ est une énumération et n'accepte que les valeurs suivantes: • first_open • session_start • in_app_purchase • view_item_list • view_item • view_search_results • add_to_cart • ecommerce_purchase • custom L'événement |
app_event_name |
Obligatoire sous certaines conditions Lieu: requête Nom de tout événement d'application personnalisé qui n'est pas accepté dans le champ level_achieved Level Achieved Ce champ ne doit contenir aucune des valeurs réservées pour |
app_event_data |
Facultative Lieu: Corps Transférez toutes les données d'événement enrichi supplémentaires sous la forme d'un simple objet JSON mappant les clés aux valeurs. Les valeurs acceptées sont des chaînes et des tableaux de chaînes. {"level": 5, "attempts": 20} |
rdid |
Obligatoire Lieu: requête Chaîne UUID valide représentant l'ID brut de l'appareil. f10e1de2-e237-4f50-b6aa-843c45cc63d6 Si cet ID d'appareil est manquant (par exemple, si l'ID d'un utilisateur sans consentement ATT n'est pas défini), définissez-le sur zéro. 00000000-0000-0000-0000-000000000000 |
id_type |
Obligatoire Lieu: requête Type d'identifiant stocké dans le champ Androidadvertisingid iOSidfa |
lat |
Obligatoire Lieu: requête État du suivi des annonces limitées de l'appareil.
|
app_version |
Obligatoire Lieu: requête Version actuelle de l'application. Elle devrait être standardisée comme suit. AndroidpackageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4 |
os_version |
Obligatoire Lieu: requête Version actuelle du système d'exploitation hôte. Cela doit être standardisé comme suit. Androidandroid.os.Build.VERSION.RELEASE iOS[[UIDevice currentDevice] systemVersion] |
sdk_version |
Obligatoire Lieu: requête Version du SDK qui a mesuré l'événement. Comme il est principalement utilisé pour le débogage, il doit refléter la version de version exactement telle qu'elle est publiée avec les versions de votre SDK. Si l'application n'utilise pas de SDK, transmettez la même valeur que 1.9.5r6 |
timestamp |
Obligatoire Lieu: requête Horodatage UNIX où l'événement de conversion s'est produit, en secondes avec une précision pouvant atteindre quelques microsecondes. 1432681913.123456 |
value |
Facultative Lieu: requête Valeur monétaire de l'événement, le cas échéant. Il doit toujours être mis en forme en tant que valeur à virgule flottante lisible par un ordinateur à l'aide d'un point décimal afin de séparer les parties entière et fractionnaire de la valeur. 1.99 |
currency_code |
Obligatoire sous certaines conditions Lieu: requête Code de devise ISO 4217 pour le paramètre USD |
gclid |
Obligatoire sous certaines conditions Lieu: requête Valeur du paramètre de requête Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
Obligatoire sous certaines conditions Lieu: requête Valeur du paramètre de requête BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
Obligatoire sous certaines conditions Lieu: requête Identifiant de l'attribution basée sur 1 |
gbraid |
Obligatoire sous certaines conditions Lieu: requête Dernière valeur ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O |
app_open_source |
Obligatoire sous certaines conditions Lieu: requête Valeur permettant d'identifier un lien profond vers un clic sur une annonce ou une session de recherche naturelle dans une application. ad_click or organic |
User-Agent |
Obligatoire Emplacement: En-tête User-agent de l'application, tel que défini dans la section précédente AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M) |
X-Forwarded-For |
Obligatoire Emplacement: En-tête Adresse IPv4 ou IPv6 publique de l'appareil sur lequel l'événement a été mesuré. 216.58.194.174 |
Toutes les requêtes doivent être envoyées via HTTPS. Les pings reçus via HTTP seront refusés.
Notez que si le corps de la requête est vide (dans le cas où aucune donnée d'événement enrichi n'est transmise dans la charge utile app_event_data
), notre serveur exige que vous définissiez explicitement l'en-tête Content-Length: 0
sur votre requête.
Exemple de requête
Voici un exemple de requête de suivi des conversions valide avec un type d'événement non personnalisé et des informations sur les revenus:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
Voici un exemple de demande de suivi des conversions valide avec un type d'événement non personnalisé et des informations sur les revenus, avec un rdid (advertisingid) non disponible:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &rdid=00000000-0000-0000-0000-000000000000 &id_type=advertisingid &lat=1 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u &gclid=Cj0KEQjw0dy4BRCuuL_e5M &gclid_only_request=1 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
Voici un exemple de requête de début de session valide:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Voici un exemple de requête de réattribution de début de session valide pour une session qui a débuté à partir du lien profond example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M
:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &gclid=Cj0KEQjw0dy4BRCuuL_e5M Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Encodage des données d'événement
Pour le paramètre de corps app_event_data
, veuillez utiliser les conventions suivantes pour les types de données primitifs:
Nombre décimal
- Utiliser un point comme séparateur décimal indépendamment de la localisation de l'application
- Utilisez une précision décimale à deux chiffres pour représenter les valeurs monétaires (par exemple, 2,99).
- N'utilisez pas la notation exponentielle (par exemple, 2E+9).
- N'utilisez pas de virgule pour séparer des groupes de chiffres (par exemple, 1 000 000).
- Exemples valides :
-0.5
2.99
1000000.123
Entier
- Envoyer uniquement des valeurs entières entières sans chiffres décimaux
- N'utilisez pas de virgule pour séparer des groupes de chiffres (par exemple, 1 000 000).
- Exemples valides :
1000
-11
0
Date
- Format de date: aaaa-mm-jj
yyyy
= année à quatre chiffres, par exemple 2016mm
= mois à deux chiffres, par exemple 09 pour septembredd
= jour à deux chiffres, par exemple 23 pour le 23e jour du mois
- Envoyez toujours le nombre de chiffres spécifié ci-dessus. Par exemple, si vous envoyez la valeur "dd" pour le cinquième jour du mois, envoyez
05
. - Exemples valides :
"2016-09-23"
"1990-12-31"
- Format de date: aaaa-mm-jj
Temporel
- Format de l'heure : horodatage Unix/Epoch défini dans le fuseau horaire UTC avec une précision maximale de quelques microsecondes.
- Exemples valides :
1478713087
pour mercredi 9 novembre 2016 à 17:38:07 GMT1073513982.123000
pour mercredi 7 janvier 2004 22:19:42.123 GMT
Tableaux
- Envoyer uniquement des tableaux de valeurs primitives (chaînes, nombres et valeurs booléennes)
- Exemples valides :
[123, 456, 789]
["abc"]
Réponse au suivi des conversions
Le format de la réponse de suivi des conversions est le suivant:
{ "ad_events": [<ad event objects>], "errors": [<error strings>], "attributed": true|false }
Les tableaux ad_events et errors peuvent être vides.
Les erreurs se présentent normalement sous la forme de codes d'erreur lisibles par l'ordinateur (par exemple, invalid_timestamp
).
Les événements d'annonce sont les principaux objets de l'attribution d'application et contiennent les propriétés suivantes.
Réponse au suivi des conversions | |
---|---|
ad_event_id |
Toujours présent chaîne
Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
Toujours présent chaîne Métrique de conversion utilisée pour l'attribution. Dans un premier temps, nous n'accepterons qu'une seule métrique de conversion. conversion |
timestamp |
Toujours présent number (nombre) Horodatage UNIX avec lequel l'événement d'annonce s'est produit, exprimé en secondes avec une précision pouvant atteindre quelques microsecondes. Cette valeur doit être utilisée pour l'attribution au dernier clic. 1432681913.123456 |
campaign_type |
Toujours présent chaîne Ce champ identifie le type de campagne qui a généré l'événement d'annonce. Les valeurs possibles sont les suivantes. ACI ACE Search Display Video Shopping Hotel Performance_Max Other ACI est l'abréviation de "App Campaign for Install". ACE est l'abréviation de "Campagnes pour applications axées sur l'engagement". |
campaign_id |
Toujours présent number (nombre) ID numérique de la campagne ayant généré l'événement d'annonce. Cette valeur est unique. 123456789 |
campaign_name |
Toujours présent chaîne Nom de la campagne définie par l'annonceur ayant généré l'événement d'annonce. Cette valeur n'est pas garantie unique. Occasional Gamers (Video) |
ad_type |
Toujours présent chaîne Type d'annonce ayant généré l'événement publicitaire. Cette valeur permet de différencier les différents types d'inventaire comme suit. Promotion d'une applicationClickToDownloadEngagement avec une application AppDeepLinkEngagement avec une application – Flux "Installer et continuer" AppDeepLinkContinueCollecteur pour d'autres valeurs Unknown |
external_customer_id |
Toujours présent number (nombre) Identifiant de l'annonceur propriétaire de la campagne qui a produit l'événement d'annonce. Cette valeur permet de différencier les comptes Google Ads. 123456789 |
location |
Toujours présent number (nombre) Code d'identification de la zone géographique associée à l'événement d'annonce. Reportez-vous à la documentation de référence de l'API Google Ads pour interpréter les codes de zone géographique. |
network_type |
Toujours présent chaîne Ce champ identifie le réseau publicitaire Google Ads ayant eu lieu. Les valeurs possibles sont les suivantes. Search Display YouTube |
network_subtype |
Est chaîne Ce champ identifie le "sous-type" du réseau publicitaire Google Ads sur lequel l'événement d'annonce s'est produit. Les valeurs possibles varient en fonction du type de réseau principal. RechercheRecherche Google ordinaireGoogleSearchPartenaires du Réseau de Recherche de Google SearchPartners ÉcranÉditeurs Web mobilemGDNÉditeurs d'applications Google AdMob YouTubeRéseau de vidéos YouTubeYouTubeVideosRéseau de recherche YouTube YouTubeSearchPartenaires vidéo VideoPartners |
video_id |
Fournie uniquement lorsque chaîne ID vidéo YouTube associé à l'événement d'annonce. dQw4w9WgXcQ |
keyword |
Fournie uniquement lorsque chaîne Mot clé de recherche associé à l'événement d'annonce. +food +delivery |
match_type |
Fournie uniquement lorsque chaîne Type de correspondance des mots clés pour le Réseau de Recherche. Mot clé exacteExpression exacte pRequête large b |
placement |
Fournie uniquement lorsque chaîne Emplacement associé à l'événement d'annonce. mobileapp::1-343200656 |
ad_group_id |
Toujours présent number (nombre) ID numérique du groupe d'annonces généré avec l'événement d'annonce. Cette valeur est unique. 123456789 |
ad_group_name |
Fourni uniquement lorsque chaîne Nom du groupe d'annonces défini par l'annonceur du groupe d'annonces ayant généré l'événement d'annonce. Cette valeur n'est pas garantie unique. My App AdGroup |
creative_id |
Fournie uniquement lorsque number (nombre) ID numérique du bloc d'annonces de création qui a généré l'événement d'annonce. Cette valeur est unique. 123456789 |
interaction_type |
Ce champ contient toujours l'engagement. chaîne |
Exemples de réponses
Voici un exemple de réponse de suivi des conversions:
{ "ad_events": [], "errors": ["INVALID_CURRENCY_CODE"], "attributed": false }
Voici un exemple de réponse négative concernant le suivi des conversions:
{ "ad_events": [], "errors": [], "attributed": false }
Une réponse sera renvoyée pour toutes les demandes de suivi des conversions.
Voici un exemple de réponse affirmative du suivi des conversions pour une campagne universelle de promotion d'applications:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "ACI", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Search", "network_subtype": "GoogleSearch", "video_id": null, "keyword": null, "match_type": null, "placement": null, "ad_group_id": null, "ad_group_name": "", "creative_id": null, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Voici un exemple de réponse affirmative du suivi des conversions pour une campagne sur le Réseau de Recherche:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Search", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Search", "network_subtype": "GoogleSearch", "video_id": null, "keyword": "+space +birds", "match_type": "b", "placement": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Voici un exemple de réponse affirmative du suivi des conversions pour une campagne display:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Display", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Display", "network_subtype": "mGDN", "video_id": null, "keyword": null, "match_type": null, "placement": "mobile-app::2-343200656", "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Voici un exemple de réponse positive au suivi des conversions pour une campagne YouTube:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Video", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "YouTube", "network_subtype": "YouTubeVideos", "video_id": "dQw4w9WgXcQ", "keyword": null, "match_type": null, "placement": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Demande d'attribution multiréseau
Lorsque Google Ads répond de manière positive à la demande de suivi des conversions, le consommateur d'API doit informer Google Ads de sa décision d'attribution multiréseau après avoir identifié le dernier clic.
La demande d'attribution multiréseau est identique à la requête de suivi des conversions d'origine, mais avec un chemin de requête de:
/pagead/conversion/app/1.0/cross_network
Ajout de deux paramètres obligatoires:
Demande d'attribution multiréseau | |
---|---|
ad_event_id |
Obligatoire Lieu: requête Identifiant |
attributed |
Obligatoire Lieu: requête Indique si Google Ads a reçu le crédit de la conversion par le consommateur de l'API. |
Voici un exemple de demande d'attribution multiréseau valide:
POST /pagead/conversion/app/1.0/cross_network ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=custom &app_event_name=level_achieved &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ &attributed=1 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Une requête d'attribution multiréseau valide reçoit toujours une réponse 200 générique sans corps de réponse.