Implementazione

Schema POST

La richiesta POST inviata al webhook sarà in formato JSON con lo schema seguente:

Webhook Proto payload

// 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;
  // Lead stage at the time of delivery.
  string lead_stage = 12 [(datapol.semantic_type) = ST_NOT_REQUIRED];
  // Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z
  string lead_submit_time = 13 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}

Descrizione del campo

Campo Descrizione
lead_id Stringa univoca che identifica un determinato lead.

Gestione del suggerimento:utilizza questo campo per eliminare i lead duplicati ricevuti. Sarà univoco in tutti i moduli. Quando segnali problemi relativi a un lead specifico, questo ID è obbligatorio.

api_version Versione API a cui appartiene questo schema dei lead. Verrà utilizzato durante la migrazione a un nuovo schema e può essere ignorato per il momento.
form_id ID univoco per ogni modulo configurato in Google Ads. Il prodotto attuale consente di allegare un modulo a livello di campagna (anziché a livello di gruppo di annunci o annuncio).

Implicazioni:i lead possono essere suddivisi solo a livello di form_id (ovvero a livello di campagna).

I client devono utilizzare un numero intero di 8 byte per l'elaborazione.

campaign_id L'ID campagna Google Ads o l'ID elemento pubblicitario (Display & Video 360) del modulo per i lead allegato.

I client devono utilizzare un numero intero di 8 byte per l'elaborazione.

adgroup_id L'ID gruppo di annunci Google Ads viene utilizzato per distinguere il gruppo di annunci specifico nella campagna. (Disponibile solo per i lead provenienti da annunci video e discovery)

I client devono utilizzare un numero intero di 8 byte per l'elaborazione.

creative_id L'ID creatività Google Ads viene utilizzato per distinguere la creatività specifica nel gruppo di annunci. (Disponibile solo per i lead provenienti da annunci video e discovery)

I client devono utilizzare un numero intero di 8 byte per l'elaborazione.

gcl_id ID clic Google, un parametro univoco utilizzato per monitorare ogni clic su un annuncio.
google_key Una chiave configurata dall'inserzionista con ogni modulo.

Gestione del consiglio:prima di elaborare un lead ricevuto tramite webhook, la convalida di google_key è uguale alla configurazione in Google Ads per avere maggiore certezza che il lead sia valido. Mantieni questa chiave riservata e aggiornala in Google Ads se hai motivo di ritenere che sia stata divulgata.

is_test Questo campo ha una semantica "facoltativa". Se il valore è true, considera questo lead come lead di test. Se il valore è false o se il campo non è presente, considera questo lead come lead di produzione valido.
user_column_data Una tupla chiave-valore ripetuta che trasmette i dati inviati dall'utente.
  • user_column_data.column_id: Tipo di dati inviato dall'utente.
  • User_column_data.column_value: Per ogni tipo di dati, verrà compilato un tipo di valore a seconda del tipo di dati. Tutti i nostri tipi di dati attuali hanno il valore user_column_data.string_value.
  • user_column_data.column_name: Testo leggibile del tipo di dati inviato dall'utente. Questo campo potrebbe non essere sempre compilato. Utilizza column_id .
user_column_data.column_id User_column_data.string_value content user_column_data.column_name (ritirato)
"FULL_NAME" Nome completo dell'utente. "Nome completo"
"FIRST_NAME" Nome dell'utente. "Nome"
"LAST_NAME" Cognome dell'utente. "Cognome"
"EMAIL" Email dell'utente. "Email utente"
"PHONE_NUMBER" Telefono dell'utente in formato E.164, ad es. "+11234567890". "User Phone"
"PHONE_NUMBER_VERIFIED" Indica se il numero di telefono dell'utente è verificato. "Numero di telefono verificato"
"POSTAL_CODE" Codice postale dell'utente. "Codice postale"
"COMPANY_NAME" Nome dell'azienda dell'utente. "Nome dell'azienda"
"JOB_TITLE" Qualifica dell'utente. "Titolo della posizione"
"WORK_EMAIL" Email di lavoro dell'utente. "Email di lavoro"
"WORK_PHONE" Il numero di telefono di lavoro dell'utente. "Telefono di lavoro"
"STREET_ADDRESS" Indirizzo dell'utente. "Indirizzo"
"CITY" Città dell'utente. "Città"
"REGION" Regione dell'utente. "Regione"
"COUNTRY" Paese dell'utente. "Paese"
"VEHICLE_MODEL" Quale modello ti interessa? N/D
"VEHICLE_TYPE" Quale tipo di veicolo ti interessa? N/D
"PREFERRED_DEALERSHIP" Seleziona il tuo concessionario preferito N/D
"VEHICLE_PURCHASE_TIMELINE" Quando intendi acquistare un veicolo? N/D
"VEHICLE_CONDITION" Ti interessa un veicolo nuovo o usato? N/D
"VEHICLE_OWNERSHIP" Possiedi un veicolo? "N/A"
"VEHICLE_PAYMENT_TYPE" Che tipo di proprietà del veicolo ti interessa? N/D
"COMPANY_SIZE" Quali sono le dimensioni della tua azienda? N/D
"ANNUAL_SALES" Qual è il tuo volume annuale di vendite? N/D
"YEARS_IN_BUSINESS" Da quanti anni eserciti la tua attività? N/D
"JOB_DEPARTMENT" In quale reparto lavori? N/D
"JOB_ROLE" Qual è il tuo ruolo professionale? N/D
"EDUCATION_PROGRAM" Quale programma ti interessa? N/D
"EDUCATION_COURSE" Quale corso ti interessa? N/D
"PRODUCT" Quale prodotto ti interessa? N/D
"SERVICE" Quale servizio ti interessa? N/D
"OFFER" Quale offerta ti interessa? N/D
"CATEGORY" Quale categoria ti interessa? N/D
"PREFERRED_CONTACT_METHOD" Seleziona il tuo metodo di contatto preferito N/D
"PREFERRED_LOCATION" Seleziona la tua località preferita N/D
"PREFERRED_CONTACT_TIME" Qual è l'orario migliore per contattarti? N/D
"PURCHASE_TIMELINE" Quando intendi effettuare un acquisto? N/D
"YEARS_OF_EXPERIENCE" Quanti anni di esperienza lavorativa hai accumulato? N/D
"JOB_INDUSTRY" In quale settore lavori? N/D
"LEVEL_OF_EDUCATION" Qual è il livello di istruzione più elevato che hai conseguito? N/D
"PROPERTY_TYPE" Quale tipo di immobile stai cercando? N/D
"REALTOR_HELP_GOAL" Per cosa vuoi chiedere aiuto a un agente immobiliare? N/D
"PROPERTY_COMMUNITY" Quale community ti interessa? N/D
"PRICE_RANGE" Quale fascia di prezzo stai cercando? N/D
"NUMBER_OF_BEDROOMS" Di quante stanze da letto hai bisogno? N/D
"FURNISHED_PROPERTY" Stai cercando un immobile completamente arredato? N/D
"PETS_ALLOWED_PROPERTY" Stai cercando immobili in cui sono ammessi animali domestici? N/D
"NEXT_PLANNED_PURCHASE" Qual è il prossimo prodotto che intendi acquistare? N/D
"EVENT_SIGNUP_INTEREST" Vuoi registrarti a un evento? N/D
"PREFERRED_SHOPPING_PLACES" Dove ti interessa fare acquisti? N/D
"FAVORITE_BRAND" Qual è il tuo brand preferito? N/D
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Quale tipo di licenza commerciale valida possiedi? N/D
"EVENT_BOOKING_INTEREST" Ti interessa prenotare un evento? N/D
"DESTINATION_COUNTRY" Qual è il paese di destinazione? N/D
"DESTINATION_CITY" Qual è la città di destinazione? N/D
"DEPARTURE_COUNTRY" Qual è il paese di partenza? N/D
"DEPARTURE_CITY" Qual è la città di partenza? N/D
"DEPARTURE_DATE" Qual è la data di partenza? N/D
"RETURN_DATE" Qual è la data di ritorno? N/D
"NUMBER_OF_TRAVELERS" Quante persone viaggiano con te? N/D
"TRAVEL_BUDGET" Qual è il tuo budget per il viaggio? N/D
"TRAVEL_ACCOMMODATION" Dove vuoi soggiornare durante il viaggio? N/D
asset_group_id Questo campo viene compilato solo per le campagne Performance Max. Indica l'ID del contenitore che contiene il modulo per i lead.

I client devono utilizzare un numero intero di 8 byte per l'elaborazione.

lead_stage Indica la fase del lead al momento della sua generazione. Questo campo è utile per monitorare la fase del funnel / lo stato di conversione di un lead.
lead_submit_time Indica il timestamp in cui l'utente ha inviato il modulo. È rappresentato nel formato ISO-8601. Esempio: 2024-09-26T12:30:00Z

Campi non riconosciuti e compatibilità futura

Per garantire che l'integrazione del webhook rimanga solida e possa adattarsi ai miglioramenti futuri, è una best practice standard progettare il parser JSON in modo che ignori normalmente tutti i campi all'interno del payload del webhook che il sistema non utilizza o riconosce esplicitamente.

Consiglio chiave:configura la logica di analisi JSON in modo da elaborare solo i campi necessari per la tua applicazione. Non scrivere codice che prevede un insieme fisso di campi o che genererebbe un errore se nel payload sono presenti campi nuovi e imprevisti.

Perché è importante:

  • Compatibilità futura:Google potrebbe aggiungere nuovi campi facoltativi al payload del webhook negli aggiornamenti futuri per fornire dati più ricchi o nuove funzionalità. Se il parser è troppo rigido (ad es. non funziona con proprietà sconosciute), l'integrazione potrebbe interrompersi quando Google implementa queste modifiche non distruttive.
  • Manutenzione semplificata: concentrandoti solo sui punti dati che utilizzi attivamente, il codice di integrazione rimane più semplice e facile da gestire.

La maggior parte delle librerie di analisi JSON moderne offre opzioni per ignorare le proprietà sconosciute per impostazione predefinita o può essere configurata per farlo.

Gestione dei lead

I gestori dei lead devono rispondere con i seguenti codici HTTP:

Risposta HTTP Corpo della risposta (JSON) Errore non irreversibile?
200 {} N/D
4XX {"message: Free form error text, describing what was wrong with request"} No
5XX {"message: Intermittent retraible error optional message"}

Duplicati

Non è garantito che un singolo lead venga inviato esattamente una volta, pertanto il webhook di gestione dei lead deve gestire i duplicati in modo appropriato.