Implementacja

Schemat POST

Żądanie POST wysłane do webhooka będzie w formacie JSON z tym schematem:

Ł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;
}

Opis pola

Pole	Opis
lead_id	Unikalny ciąg znaków identyfikujący danego potencjalnego klienta. Zarządzanie rekomendacją: użyj tego, aby usunąć duplikaty otrzymanych potencjalnych klientów. Musi być unikalny we wszystkich formularzach. Podczas zgłaszania problemów związanych z danym potencjalnym klientem będzie wymagany ten identyfikator.
api_version	Wersja interfejsu API, do której należy ten schemat potencjalnego klienta. Będzie on używany podczas migracji do nowego schematu, ale na razie można 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 reklam). Konsekwencje: dane o potencjalnych klientach można dzielić tylko na poziomie form_id (czyli na poziomie kampanii). Klienci muszą używać liczb całkowitych o długości 8 bajtów.
campaign_id	Identyfikator kampanii Google Ads lub elementu zamówienia (Display & Video 360) dołączonego formularza kontaktowego. Klienci muszą przetwarzać liczby całkowite 8-bajtowe.
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 pochodzących z reklam wideo i reklam Discovery) Klienci muszą przetwarzać liczby całkowite 8-bajtowe.
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 pochodzących z reklam wideo i reklam Discovery) Klienci muszą przetwarzać liczby całkowite 8-bajtowe.
gcl_id	Google click ID, czyli unikalny parametr służący do śledzenia każdego kliknięcia reklamy.
google_key	Klucz skonfigurowany przez reklamodawcę w przypadku każdego formularza. Rekomendacja dotycząca obsługi: zanim przetworzysz potencjalnego klienta otrzymanego przez webhooka, sprawdź, czy google_key jest taki sam jak konfiguracja w Google Ads. Dzięki temu będziesz mieć pewność, że potencjalny klient jest prawidłowy. Zachowaj ten klucz w poufności i zaktualizuj go w Google Ads, jeśli masz powody, by sądzić, że został on upubliczniony.
is_test	To pole ma semantykę „opcjonalną”. Jeśli wartość to Prawda, traktuj tego potencjalnego klienta jako potencjalnego klienta testowego. Jeśli wartość jest fałszywa lub pole jest puste, traktuj tę potencjalnego klienta jako zwykłego potencjalnego klienta.
user_column_data	powtarzana tupla klucz-wartość, która przekazuje dane przesłane przez użytkownika; user_column_data.column_id: typ danych przesłanych przez użytkownika. User_column_data.column_value: w przypadku każdego typu danych będzie wypełniany typ wartości w zależności od typu danych. Wszystkie nasze aktualne typy danych mają wartość user_column_data.string_value. user_column_data.column_name: tekst w postaci czytelnej dla człowieka typu danych przesłanego przez użytkownika. To pole może nie być wypełnione. Zamiast niego użyj wartości column_id . user_column_data.column_id User_column_data.string_value content user_column_data.column_name (wycofana) „FULL_NAME” Imię i nazwisko użytkownika. „Imię i nazwisko” „FIRST_NAME” Imię użytkownika. „Imię” „LAST_NAME” Nazwisko użytkownika. „Nazwisko” „EMAIL” Adres e-mail użytkownika. „Adres e-mail użytkownika” „PHONE_NUMBER” Numer telefonu użytkownika w formacie E.164, np. "[phone]". „Telefon użytkownika” „POSTAL_CODE” Kod pocztowy użytkownika. „Kod pocztowy” „COMPANY_NAME” Nazwa firmy użytkownika. „Nazwa firmy” „JOB_TITLE” Stanowisko użytkownika. „Stanowisko” „WORK_EMAIL” służbowy adres e-mail użytkownika, „E-mail służbowy” „WORK_PHONE” Służbowy numer telefonu użytkownika. „Telefon służbowy” „STREET_ADDRESS” Adres użytkownika. „Adres” „CITY” Miasto użytkownika. „Miasto” „REGION” Region użytkownika. „Region” „COUNTRY” Kraj użytkownika. „Kraj” „VEHICLE_MODEL” Który model Cię interesuje? Nie dotyczy „VEHICLE_TYPE” Jaki typ pojazdu Cię interesuje? Nie dotyczy „PREFERRED_DEALERSHIP” Wybierz preferowany salon sprzedaży Nie dotyczy „VEHICLE_PURCHASE_TIMELINE” Kiedy zamierzasz kupić pojazd? Nie dotyczy „VEHICLE_CONDITION” Jaki stan pojazdu Cię interesuje? Nie dotyczy „VEHICLE_OWNERSHIP” Czy masz pojazd? „Nie dotyczy” „VEHICLE_PAYMENT_TYPE” Jaka forma własności pojazdu Cię interesuje? Nie dotyczy „COMPANY_SIZE” Jak duża jest Twoja firma? Nie dotyczy „ANNUAL_SALES” Jaka jest Twoja roczna wielkość sprzedaży? Nie dotyczy „YEARS_IN_BUSINESS” Od ilu lat działa Twoja firma? Nie dotyczy „JOB_DEPARTMENT” W jakim dziale pracujesz? Nie dotyczy „JOB_ROLE” Jakie zajmujesz stanowisko? Nie dotyczy „EDUCATION_PROGRAM” Jaki program Cię interesuje? Nie dotyczy „EDUCATION_COURSE” Jaki kurs Cię interesuje? Nie dotyczy „PRODUCT” Jaki produkt Cię interesuje? Nie dotyczy „SERVICE” Jaka usługa Cię interesuje? Nie dotyczy „OFERTA” Jaka oferta Cię interesuje? Nie dotyczy „CATEGORY” Jaka kategoria Cię interesuje? Nie dotyczy „PREFERRED_CONTACT_METHOD” Wybierz preferowaną metodę kontaktu Nie dotyczy „PREFERRED_LOCATION” Wybierz preferowaną lokalizację Nie dotyczy „PREFERRED_CONTACT_TIME” W jakich godzinach najlepiej się z Tobą kontaktować? Nie dotyczy „PURCHASE_TIMELINE” Kiedy chcesz dokonać zakupu? Nie dotyczy „YEARS_OF_EXPERIENCE” Ile masz lat doświadczenia w pracy? Nie dotyczy „JOB_INDUSTRY” W jakiej branży pracujesz? Nie dotyczy „LEVEL_OF_EDUCATION” Jakie masz wykształcenie? Nie dotyczy „PROPERTY_TYPE” Jakiego typu nieruchomości szukasz? Nie dotyczy „REALTOR_HELP_GOAL” Dlaczego potrzebujesz usług agencji nieruchomości? Nie dotyczy „PROPERTY_COMMUNITY” Jaka społeczność Cię interesuje? Nie dotyczy „PRICE_RANGE” Jaki przedział cenowy Cię interesuje? Nie dotyczy „NUMBER_OF_BEDROOMS” Ile sypialni ma mieć dom lub mieszkanie? Nie dotyczy „FURNISHED_PROPERTY” Czy szukasz w pełni umeblowanej nieruchomości? Nie dotyczy „PETS_ALLOWED_PROPERTY” Czy szukasz domu lub mieszkania, w którym wolno trzymać zwierzęta? Nie dotyczy „NEXT_PLANNED_PURCHASE” Jaki produkt zamierzasz kupić w następnej kolejności? Nie dotyczy „EVENT_SIGNUP_INTEREST” Czy chcesz zarejestrować się na wydarzenie? Nie dotyczy „PREFERRED_SHOPPING_PLACES” Gdzie chcesz robić zakupy? Nie dotyczy „FAVORITE_BRAND” Jaka jest Twoja ulubiona marka? Nie dotyczy "TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Jakim typem licencji komercyjnej dysponujesz? Nie dotyczy „EVENT_BOOKING_INTEREST” Czy chcesz zarezerwować miejsce na wydarzenie? Nie dotyczy „DESTINATION_COUNTRY” Do jakiego kraju chcesz jechać? Nie dotyczy „DESTINATION_CITY” Do jakiego miasta chcesz jechać? Nie dotyczy „DEPARTURE_COUNTRY” Z jakiego kraju wyruszasz? Nie dotyczy „DEPARTURE_CITY” Z jakiego miasta wyruszasz? Nie dotyczy „DEPARTURE_DATE” Podaj datę wyjazdu. Nie dotyczy „RETURN_DATE” Którego dnia wracasz? Nie dotyczy „NUMBER_OF_TRAVELERS” Z iloma osobami podróżujesz? Nie dotyczy „TRAVEL_BUDGET” Jaki jest Twój budżet na podróż? Nie dotyczy „TRAVEL_ACCOMMODATION” Gdzie chcesz się zatrzymać w czasie podróży? Nie dotyczy
asset_group_id	To pole jest wypełniane tylko w przypadku kampanii Performance Max. Określa identyfikator kontenera zawierającego formularz kontaktowy. Klienci muszą przetwarzać liczby całkowite 8-bajtowe.

Obsługa potencjalnych klientów

Obsługa potencjalnych klientów powinna odpowiadać za pomocą tych kodów HTTP:

Odpowiedź HTTP	Treść odpowiedzi (JSON)	Błąd z możliwością ponownego pobrania?
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 obsługujący kontakty do potencjalnych klientów powinien odpowiednio obsługiwać duplikaty.

Ważna informacja: aby usunąć duplikaty potencjalnych klientów, użyj tagu lead_id.