POST スキーマ
ウェブフックに送信される POST リクエストは、次のスキーマの JSON 形式になります。
ウェブフックの proto ペイロード
// 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];
// The source of the lead submission.
// Possible values: "LEAD_FORM" or "CONVERSATIONAL_AGENT".
string lead_source = 14 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}
フィールドの説明
| フィールド | 説明 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
特定のリードを識別する一意の文字列。
処理に関する推奨事項: この ID を使用して、受信したリードの重複を排除します。これはすべての フォームで一意です。特定のリードに関する問題を報告する場合は、この ID が必要になります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
このリード スキーマが属する API バージョン。これは新しいスキーマに移行する際に使用されるため、現時点では無視してかまいません。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Google 広告で構成されたフォームごとに一意の ID。現在のプロダクトでは、フォームをキャンペーン単位で添付できます(広告グループ単位または広告単位での添付はできません)。 影響: リードは 処理には 8 バイトの整数を使用する必要があります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
添付されたリードフォームの Google 広告キャンペーン ID または広告申込情報 ID(ディスプレイ&ビデオ 360)。 処理には 8 バイトの整数を使用する必要があります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
Google 広告の広告グループ ID は、キャンペーン内の特定の
広告グループを区別するために使用されます(動画広告とディスカバリー
広告からのリードでのみ使用可能)
処理には 8 バイトの整数を使用する必要があります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
Google 広告のクリエイティブ ID は、広告グループ内の特定の
クリエイティブを区別するために使用されます(動画広告とディスカバリー
広告からのリードでのみ使用可能)
処理には 8 バイトの整数を使用する必要があります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
Google クリック ID。広告の各クリックをトラッキングするために使用される一意のパラメータ。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
広告主が各フォームに設定したキー。
処理に関する推奨事項: ウェブフック経由で受信したリードを処理する前に |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
このフィールドには「省略可」の意味があります。値が true の場合は、この リードをテストリードとして扱います。値が false の場合、またはフィールドが存在しない場合は、このリードを有効な本番環境のリードとして扱います。 このリードを有効な本番環境のリードとして扱います。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
ユーザーが送信したデータを送信する Key-Value のタプルを繰り返します。
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
このフィールドは、P-MAX キャンペーンでのみ設定されます。
これは、リードフォームを含むコンテナ ID を示します。
処理には 8 バイトの整数を使用する必要があります。 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
これは、リード配信時のリードのステージを示します。このフィールドは リードのファネルのステージ / コンバージョンのステータスをトラッキングするのに役立ちます。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
これは、ユーザーがフォームを送信したときのタイムスタンプを示します。ISO-8601 形式で表されます。 例: 2024-09-26T12:30:00Z | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_source |
これは、リード送信の発生元を示します。標準のリードフォーム広告から生成されたリードの場合は「LEAD_FORM」、検索でのエージェント チャット エクスペリエンスから生成されたリードの場合は「CONVERSATIONAL_AGENT」になります。 |
認識されないフィールドと上位互換性
ウェブフック統合の堅牢性を維持し、将来の機能強化に対応できるようにするには、システムが明示的に使用または認識しないウェブフック ペイロード内のフィールドを JSON パーサーで適切に無視するように設計することが標準的なベスト プラクティスです。
重要な推奨事項: アプリケーションで特に必要なフィールドのみを処理するように JSON 解析ロジックを構成します。固定されたフィールド セットを想定するコードや、ペイロードに予期しない新しいフィールドが存在する場合に失敗するコードは記述しないでください。
これが重要である理由:
- 上位互換性: Google は、より豊富なデータや新機能を提供するために、今後のアップデートでウェブフック ペイロードに新しい省略可能なフィールドを追加する可能性があります。パーサーが厳しすぎる場合(不明なプロパティで失敗するなど)、Google がこのような非破壊的な変更をロールアウトすると、統合が中断する可能性があります。
- メンテナンスの簡素化: 積極的に使用するデータポイントのみに焦点を当てることで、統合コードをシンプルに保ち、メンテナンスを容易にすることができます。
最新の JSON 解析ライブラリのほとんどは、不明なプロパティをデフォルトで無視するオプションを提供しているか、無視するように構成できます。
セールスリードのハンドリング
リード ハンドラは、次の HTTP コードで応答する必要があります。
| HTTP レスポンス | レスポンスの本文(JSON) | 再試行可能なエラーですか? |
|---|---|---|
200 |
{} | なし |
4XX |
{"message: 自由形式のエラー テキスト。リクエストに問題があった内容を説明します"} | いいえ |
5XX |
{"message: Intermittent retraible error optional message"} | はい |
重複
1 つのリードが 1 回だけ配信されるとは限りません。そのため、リード処理ウェブフックは重複を適切に処理する必要があります。