Implémentation

Schéma POST

La requête POST envoyée au webhook sera au format JSON avec le schéma suivant:

Charge utile proto Webhook

// Represent user lead data for single column
message UserLeadColumnData {
  // Human-readable text of the field type (e.g.: Full Name,  What is your
  // preferred dealership?). This field might not always be populated.
  optional string column_name = 1;

  // Column value based on column type
  oneof column_value {
    string string_value = 2;
  }
  // Column id. Populated for all types of fields. (e.g.: FULL_NAME)
  optional string column_id = 3;
}

// Message to construct webhook JSON payload
message WebhookLead {
  // Unique id to represent lead
  optional string lead_id = 1;
  // User inputted data per column
  repeated UserLeadColumnData user_column_data = 2;
  // API version
  optional string api_version = 3;
  // Form id to which lead belonged to.
  optional int64 form_id = 4;
  // Campaign id that the lead form is associated with
  optional int64 campaign_id = 5;
  // Key to be used by advertiser to verify the request
  // is from Google.
  optional string google_key = 6;
  // Denotes if the lead is a test lead.
  optional bool is_test = 7;
  // Click ID for the lead submission.
  optional string gcl_id = 8;
  // Adgroup id which generated the lead.
  optional int64 adgroup_id = 9;
  // Creative id which generated the lead.
  optional int64 creative_id = 10;
  // Asset group id represents the container for holding assets, associated
  // urls, hints and criteria that will be used to select assets and for
  // optimization. This field is only populated for Performance Max campaigns.
  int64 asset_group_id = 11;
}

Description du champ

Champ Description
lead_id Chaîne unique qui identifie un prospect donné.

Recommandation de traitement:utilisez cette option pour dédupliquer les prospects reçus. Il doit être unique pour tous les formulaires. Lorsque vous signalez des problèmes liés à un prospect spécifique, cet ID est obligatoire.

api_version Version de l'API à laquelle appartient ce schéma de prospect. Il sera utilisé lors de la migration vers un nouveau schéma et peut être ignoré pour le moment.
form_id Identifiant unique de chaque formulaire configuré dans Google Ads. Le produit actuel permet d'associer un formulaire au niveau de la campagne (plutôt qu'au niveau du groupe d'annonces ou de l'annonce).

Implications:Les prospects ne peuvent être segmentés qu'au niveau form_id (c'est-à-dire au niveau de la campagne).

Les clients doivent utiliser un entier de 8 octets pour le traitement.

campaign_id ID de la campagne Google Ads ou ID de l'élément de campagne (Display & Video 360) du formulaire de prospect associé.

Les clients doivent utiliser un entier de 8 octets pour le traitement.

adgroup_id L'ID du groupe d'annonces Google Ads permet de distinguer le groupe d'annonces spécifique de la campagne. (Disponible uniquement pour les prospects issus des annonces vidéo et Discovery)

Les clients doivent utiliser un entier de 8 octets pour le traitement.

creative_id L'ID de la création Google Ads permet de distinguer la création spécifique du groupe d'annonces. (Disponible uniquement pour les prospects issus des annonces vidéo et Discovery)

Les clients doivent utiliser un entier de 8 octets pour le traitement.

gcl_id ID de clic Google, paramètre unique utilisé pour suivre chaque clic sur une annonce.
google_key Clé configurée par l'annonceur avec chaque formulaire.

Recommandation de gestion:Avant de traiter un prospect reçu via un webhook, la validation de google_key est identique à la configuration dans Google Ads afin d'être plus sûr que le prospect est valide. Gardez cette clé confidentielle et mettez-la à jour dans Google Ads si vous avez des raisons de penser qu'elle a été divulguée de manière extensive.

is_test Ce champ a une sémantique "facultatif". Si la valeur est "true", traitez ce prospect comme un prospect de test. Si la valeur est "false" ou si le champ n'est pas présent, traitez cette piste comme une piste de production valide.
user_column_data Un tuple clé-valeur répété qui transmet les données envoyées par l'utilisateur.
  • user_column_data.column_id: type de données envoyé par l'utilisateur.
  • User_column_data.column_value: pour chaque type de données, un type de valeur est renseigné en fonction du type de données. Tous nos types de données actuels ont la valeur user_column_data.string_value.
  • user_column_data.column_name: texte lisible par l'utilisateur du type de données envoyé par l'utilisateur. Ce champ n'est pas toujours renseigné. Utilisez plutôt column_id .
user_column_data.column_id Contenu User_column_data.string_value user_column_data.nom_colonne (obsolète)
"FULL_NAME" Nom complet de l'utilisateur. "Nom complet"
"FIRST_NAME" Prénom de l'utilisateur. "Prénom"
"LAST_NAME" Nom de l'utilisateur. "Nom"
"EMAIL" Adresse e-mail de l'utilisateur. "Adresse e-mail de l'utilisateur"
"PHONE_NUMBER" Numéro de téléphone de l'utilisateur au format E.164, par exemple : "+11234567890". "Téléphone de l'utilisateur"
"POSTAL_CODE" Code postal de l'utilisateur. "Code postal"
"COMPANY_NAME" Nom de l'entreprise de l'utilisateur. "Nom de l'entreprise"
"JOB_TITLE" Titre du poste de l'utilisateur. "Titre du poste"
"WORK_EMAIL" Adresse e-mail professionnelle de l'utilisateur. "Adresse e-mail professionnelle"
"WORK_PHONE" Numéro de téléphone professionnel de l'utilisateur. "Numéro de téléphone professionnel"
"STREET_ADDRESS" Adresse postale de l'utilisateur. "Adresse"
"VILLE" Ville de l'utilisateur. "Ville"
"REGION" Région de l'utilisateur. "Région"
"COUNTRY" Pays de l'utilisateur. "Pays"
"VEHICLE_MODEL" Quel modèle vous intéresse ? N/A
"VEHICLE_TYPE" Quel type de véhicule vous intéresse ? N/A
"PREFERRED_DEALERSHIP" Sélectionnez votre concessionnaire préféré N/A
"VEHICLE_PURCHASE_TIMELINE" Quand prévoyez-vous d'acheter un véhicule ? N/A
"VEHICLE_CONDITION" Êtes-vous intéressé(e) par un véhicule neuf ou d'occasion ? N/A
"VEHICLE_OWNERSHIP" Possédez-vous un véhicule ? "N/A"
"VEHICLE_PAYMENT_TYPE" Quel type d'acquisition de véhicule vous intéresse ? N/A
"COMPANY_SIZE" Quelle est la taille de votre entreprise ? N/A
"ANNUAL_SALES" Quel est votre volume de ventes annuel ? N/A
"YEARS_IN_BUSINESS" Depuis combien d'années êtes-vous en activité ? N/A
"JOB_DEPARTMENT" Dans quel service travaillez-vous ? N/A
"JOB_ROLE" Quel est votre poste ? N/A
"EDUCATION_PROGRAM" Quel programme vous intéresse ? N/A
"EDUCATION_COURSE" Quel cours vous intéresse ? N/A
"PRODUCT" Quel produit vous intéresse ? N/A
"SERVICE" Quel service vous intéresse ? N/A
"OFFER" Quelle offre vous intéresse ? N/A
"CATEGORY" Quelle catégorie vous intéresse ? N/A
"PREFERRED_CONTACT_METHOD" Sélectionnez votre méthode de contact préférée N/A
"PREFERRED_LOCATION" Sélectionnez votre lieu préféré N/A
"PREFERRED_CONTACT_TIME" À quelle heure souhaitez-vous être contacté(e) ? N/A
"PURCHASE_TIMELINE" Quand comptez-vous effectuer un achat ? N/A
"YEARS_OF_EXPERIENCE" Combien d'années d'expérience professionnelle avez-vous ? N/A
"JOB_INDUSTRY" Dans quel secteur travaillez-vous ? N/A
"LEVEL_OF_EDUCATION" Quel niveau d'études avez-vous atteint ? N/A
"PROPERTY_TYPE" Quel type de logement recherchez-vous ? N/A
"REALTOR_HELP_GOAL" Pourquoi souhaitez-vous faire appel à un agent immobilier ? N/A
"PROPERTY_COMMUNITY" Quelle communauté vous intéresse ? N/A
"PRICE_RANGE" Quelle gamme de prix recherchez-vous ? N/A
"NUMBER_OF_BEDROOMS" Combien de chambres recherchez-vous ? N/A
"FURNISHED_PROPERTY" Recherchez-vous un logement entièrement meublé ? N/A
"PETS_ALLOWED_PROPERTY" Recherchez-vous des logements qui acceptent les animaux de compagnie ? N/A
"NEXT_PLANNED_PURCHASE" Quel est le prochain produit que vous prévoyez d'acheter ? N/A
"EVENT_SIGNUP_INTEREST" Voulez-vous vous inscrire à un événement ? N/A
"PREFERRED_SHOPPING_PLACES" Où souhaitez-vous effectuer vos achats ? N/A
"FAVORITE_BRAND" Quelle est votre marque préférée ? N/A
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Quel type de licence commerciale possédez-vous ? N/A
"EVENT_BOOKING_INTEREST" Souhaitez-vous réserver un événement ? N/A
"DESTINATION_COUNTRY" Quel est votre pays de destination ? N/A
"DESTINATION_CITY" Quelle est votre ville de destination ? N/A
"DEPARTURE_COUNTRY" Quel est votre pays de départ ? N/A
"DEPARTURE_CITY" Quelle est votre ville de départ ? N/A
"DEPARTURE_DATE" Quelle est votre date de départ ? N/A
"RETURN_DATE" Quelle est votre date de retour ? N/A
"NUMBER_OF_TRAVELERS" Avec combien de personnes voyagez-vous ? N/A
"TRAVEL_BUDGET" Quel est votre budget de voyage ? N/A
"TRAVEL_ACCOMMODATION" Où souhaitez-vous loger pendant votre voyage ? N/A
asset_group_id Ce champ n'est renseigné que pour les campagnes Performance Max. Indique l'ID du conteneur contenant le formulaire de prospect.

Les clients doivent utiliser un entier de 8 octets pour le traitement.

Gestion des prospects

Les gestionnaires de prospects doivent répondre avec les codes HTTP suivants:

Réponse HTTP Corps de la réponse (JSON) Erreur récupérable ?
200 {} N/A
4XX {"message: Texte d'erreur au format libre, décrivant le problème lié à la requête"} Non
5XX {"message: Intermittent retraible error optional message"} Oui

Doublons

Il n'est pas garanti qu'un prospect soit distribué exactement une seule fois. Par conséquent, le webhook de gestion des prospects doit gérer les doublons de manière appropriée.