POST şeması
Webhook'a gönderilen POST isteği, aşağıdaki şemaya sahip JSON biçiminde olur:
Webhook Proto yükü
// 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];
}
Alan açıklaması
| Alan | Açıklama | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Belirli bir potansiyel müşteriyi tanımlayan benzersiz dize.
Öneri işleme: Bu işlevi, alınan potansiyel müşterilerin yinelenen kayıtlarını kaldırmak için kullanın. Bu değer tüm formlarda benzersiz olacaktır. Belirli bir potansiyel müşteriyle ilgili sorunları bildirirken bu kimlik gereklidir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Bu potansiyel müşteri şemasının ait olduğu API sürümü. Bu, yeni bir şemaya geçiş yaparken kullanılır ve şimdilik yoksayılabilir. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Google Ads'de yapılandırılan her form için benzersiz kimlik. Mevcut ürün, formun kampanya düzeyinde eklenmesine (reklam grubu veya reklam düzeyinde eklenmesine kıyasla) olanak tanır.
Etkileri: Potansiyel müşteriler yalnızca İstemcilerin işlemek için 8 baytlık tam sayı kullanması gerekir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
Ekli potansiyel müşteri formuyla ilişkili Google Ads kampanya kimliği veya satır öğesi kimliği (Display & Video 360).
İstemcilerin işlemek için 8 baytlık bir tam sayı kullanması gerekir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
Google Ads reklam grubu kimliği, kampanyadaki belirli reklam grubunu ayırt etmek için kullanılır. (Yalnızca video ve Discovery reklamlarından gelen potansiyel müşteriler için kullanılabilir)
İstemcilerin işlemek için 8 baytlık bir tam sayı kullanması gerekir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
Google Ads reklam öğesi kimliği, reklam grubundaki belirli reklam öğesini ayırt etmek için kullanılır. (Yalnızca video ve Discovery reklamlarından gelen potansiyel müşteriler için kullanılabilir)
İstemcilerin işlemek için 8 baytlık bir tam sayı kullanması gerekir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
Bir reklamın her tıklamasını izlemek için kullanılan benzersiz bir parametre olan Google tıklama kimliği. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Reklamveren tarafından her formla birlikte yapılandırılan bir anahtar.
Önerilen işlem: Web kancası üzerinden alınan bir potansiyel müşteriyi işlemeden önce, potansiyel müşterinin geçerli olduğundan daha fazla emin olmak için |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Bu alanın semantiği "isteğe bağlı"dır. Değer doğruysa bu potansiyel müşteriyi test potansiyel müşterisi olarak değerlendirin. Değer yanlışsa veya alan mevcut değilse bu potansiyel müşteriyi geçerli üretim potansiyel müşterisi olarak değerlendirin. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Kullanıcı tarafından gönderilen verileri ileten, tekrarlanan bir anahtar/değer demeti.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Bu alan yalnızca Maksimum Performans kampanyaları için doldurulur.
Bu, potansiyel müşteri formunu içeren kapsayıcı kimliğini belirtir.
İstemcilerin işlemek için 8 baytlık bir tam sayı kullanması gerekir. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Bu, potansiyel müşteri teslimi sırasında potansiyel müşterinin bulunduğu aşamayı gösterir. Bu alan, potansiyel müşterinin dönüşüm hunisi aşamasını / dönüşüm durumunu izlemek için yararlıdır. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Bu, kullanıcının formu gönderdiği zaman damgasını gösterir. ISO-8601 biçiminde gösterilir. Ör. 2024-09-26T12:30:00Z |
Tanınmayan alanlar ve ileriye dönük uyumluluk
Webhook entegrasyonunuzun sağlam kalmasını ve gelecekteki geliştirmelere uyum sağlayabilmesini sağlamak için JSON ayrıştırıcınızı, sisteminizin açıkça kullanmadığı veya tanımadığı webhook yükündeki tüm alanları sorunsuz bir şekilde yoksayacak şekilde tasarlamak standart bir en iyi uygulamadır.
Önemli Öneri: JSON ayrıştırma mantığınızı yalnızca uygulamanız için özellikle gerekli olan alanları işleyecek şekilde yapılandırın. Sabit bir alan grubu bekleyen veya yeni, beklenmedik alanlar yükte mevcutsa başarısız olacak kod yazmayın.
Bu neden önemli?
- İleriye Dönük Uyumluluk: Google, daha zengin veriler veya yeni özellikler sağlamak için gelecekteki güncellemelerde webhook yüküne yeni ve isteğe bağlı alanlar ekleyebilir. Ayrıştırıcınız çok katıysa (ör. bilinmeyen özelliklerde başarısız olursa) Google bu tür değişiklikleri kullanıma sunduğunda entegrasyonunuz bozulabilir.
- Basitleştirilmiş Bakım: Yalnızca aktif olarak kullandığınız veri noktalarına odaklanarak entegrasyon kodunuzun daha basit ve bakımı daha kolay olmasını sağlayabilirsiniz.
En modern JSON ayrıştırma kitaplıkları, bilinmeyen özellikleri varsayılan olarak yoksayma seçenekleri sunar veya bu şekilde yapılandırılabilir.
Potansiyel müşteri işleme
Potansiyel müşteri işleyicileri aşağıdaki HTTP kodlarıyla yanıt vermelidir:
| HTTP Yanıtı | Yanıt gövdesi (JSON) | Yeniden denenebilir hata mı? |
|---|---|---|
200 |
{} | Yok |
4XX |
{"message: Free form error text, describing what was wrong with request"} | Hayır |
5XX |
{"message: Intermittent retraible error optional message"} | Evet |
Kopyalar
Tek bir potansiyel müşterinin tam olarak bir kez teslim edileceği garanti edilmez. Bu nedenle, potansiyel müşteri işleme webhook'u, yinelenenleri düzgün bir şekilde işlemelidir.