Schemat POST
Żądanie POST wysłane do webhooka będzie miało format JSON o tym schemacie:
Ładunek proto webhooka
// 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];
}
Opis pola
| Pole | Opis | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Unikalny ciąg znaków, który identyfikuje potencjalnego klienta.
Rekomendacja dotycząca postępowania: użyj tej opcji, aby usunąć duplikaty otrzymanych potencjalnych klientów. Będzie on unikalny we wszystkich formularzach. Podczas zgłaszania problemów związanych z konkretnym potencjalnym klientem ten identyfikator będzie wymagany. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Wersja interfejsu API, do której należy ten schemat potencjalnego klienta. Będzie on używany podczas migracji do nowego schematu, więc na razie możesz go zignorować. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Unikalny identyfikator każdego formularza skonfigurowanego w Google Ads. Obecna usługa umożliwia dołączanie formularza na poziomie kampanii (a nie na poziomie grupy reklam lub reklamy).
Implikacje: potencjalnych klientów można dzielić tylko na poziomie Klienci muszą używać 8-bajtowej liczby całkowitej do przetwarzania. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
Identyfikator kampanii Google Ads lub identyfikator elementu zamówienia (Display & Video 360) dołączonego formularza kontaktowego.
Klienci muszą używać 8-bajtowej liczby całkowitej do przetwarzania. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
Identyfikator grupy reklam Google Ads służy do rozróżniania poszczególnych grup reklam w kampanii. (Dostępne tylko w przypadku potencjalnych klientów z reklam wideo i reklam Discovery)
Klienci muszą używać 8-bajtowej liczby całkowitej do przetwarzania. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
Identyfikator kreacji Google Ads służy do odróżniania konkretnej kreacji w grupie reklam. (Dostępne tylko w przypadku potencjalnych klientów z reklam wideo i reklam Discovery)
Klienci muszą używać 8-bajtowej liczby całkowitej do przetwarzania. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
Identyfikator kliknięcia w Google, unikalny parametr używany do śledzenia każdego kliknięcia reklamy. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Klucz skonfigurowany przez reklamodawcę w każdym formularzu.
Zalecenie: przed przetworzeniem potencjalnego klienta otrzymanego za pomocą webhooka sprawdź, czy wartość |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
To pole ma semantykę „opcjonalne”. Jeśli wartość to „true”, traktuj tego potencjalnego klienta jako testowego. Jeśli wartość to „false” lub pole nie występuje, traktuj potencjalnego klienta jako potencjalnego klienta produkcyjnego. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Powtarzająca się krotka klucz-wartość przesyłająca dane przesłane przez użytkownika.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
To pole jest wypełniane tylko w przypadku kampanii Performance Max.
Oznacza identyfikator kontenera, który zawiera formularz kontaktowy.
Klienci muszą używać 8-bajtowej liczby całkowitej do przetwarzania. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Oznacza to etap potencjalnego klienta w momencie przekazania informacji o nim. To pole jest przydatne do śledzenia etapu ścieżki lub stanu konwersji potencjalnego klienta. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Jest to sygnatura czasowa przesłania formularza przez użytkownika. Jest ona podana w formacie ISO 8601. Ex- 2024-09-26T12:30:00Z |
Nierozpoznane pola i zgodność z przyszłymi wersjami
Aby zapewnić niezawodność integracji webhooka i umożliwić jej dostosowywanie się do przyszłych ulepszeń, warto zaprojektować parser JSON tak, aby ignorował pola w ładunku webhooka, które nie są używane ani rozpoznawane przez Twój system.
Kluczowa rekomendacja: skonfiguruj logikę analizowania JSON tak, aby przetwarzała tylko pola, których potrzebujesz w aplikacji. Nie pisz kodu, który oczekuje stałego zestawu pól lub który nie działa, gdy w ładunku znajdują się nowe, nieoczekiwane pola.
Dlaczego to jest ważne:
- Zgodność z przyszłymi wersjami: w przyszłych aktualizacjach Google może dodawać do ładunku webhooka nowe, opcjonalne pola, aby udostępniać bardziej szczegółowe dane lub nowe funkcje. Jeśli Twój parser jest zbyt rygorystyczny (np. nie działa w przypadku nieznanych właściwości), integracja może przestać działać, gdy Google wprowadzi takie zmiany, które nie powodują przerw w działaniu.
- Uproszczona obsługa: skupiając się tylko na punktach danych, których aktywnie używasz, kod integracji pozostaje prostszy i łatwiejszy w obsłudze.
Większość nowoczesnych bibliotek do analizowania JSON oferuje opcje ignorowania nieznanych właściwości domyślnie lub można je skonfigurować tak, aby to robiły.
Obsługa potencjalnych klientów
Podmioty obsługujące potencjalnych klientów powinny odpowiadać za pomocą tych kodów HTTP:
| Odpowiedź HTTP | Treść odpowiedzi (JSON) | Czy błąd można ponowić? |
|---|---|---|
200 |
{} | Nie dotyczy |
4XX |
{"message: Free form error text, describing what was wrong with request"} | Nie |
5XX |
{"message: Intermittent retraible error optional message"} | Tak |
Duplikaty
Nie ma gwarancji, że pojedynczy kontakt do potencjalnego klienta zostanie dostarczony dokładnie raz, dlatego webhook do obsługi kontaktów do potencjalnych klientów powinien prawidłowo obsługiwać duplikaty.