実装

POST スキーマ

Webhook に送信される POST リクエストは、次のスキーマの JSON 形式になります。

Webhook 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];
}

フィールドの説明

フィールド	説明
lead_id	特定のリードを識別する一意の文字列。 推奨事項の処理: これを使用して、受信したリードの重複を排除します。これは、すべてのフォームで一意になります。特定のリードに関連する問題を報告する場合は、この ID が必要になります。
api_version	この見込み顧客スキーマが属する API バージョン。これは新しいスキーマに移行する際に使用されます。今のところは無視してかまいません。
form_id	Google 広告で設定された各フォームの一意の ID。現在のプロダクトでは、フォームをキャンペーン単位で添付できます（広告グループ単位や広告単位で添付することもできます）。 影響: 見込み顧客は form_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	広告主が各フォームで設定したキー。 推奨される処理: ウェブフック経由で受け取った見込み顧客を処理する前に、google_key が Google 広告で設定されているものと同じであることを検証して、見込み顧客が有効であるという確信を高めます。このキーは機密情報として扱い、広く漏洩したと思われる理由がある場合は、Google 広告で更新してください。
is_test	このフィールドは「省略可」セマンティクスを持ちます。値が true の場合、この見込み顧客をテスト見込み顧客として扱います。値が false の場合、またはフィールドが存在しない場合は、このリードを有効な本番環境リードとして扱います。
user_column_data	ユーザーが送信したデータを送信する Key-Value タプルの繰り返し。 user_column_data.column_id: ユーザーが送信したデータ型。 User_column_data.column_value: 各データ型について、データ型に応じて値の型が設定されます。現在のすべてのデータ型の値は user_column_data.string_value です。 user_column_data.column_name: ユーザーが送信したデータ型の人が読める形式のテキスト。このフィールドは必ずしも入力されるとは限りません。代わりに column_id を使用してください。 user_column_data.column_id User_column_data.string_value のコンテンツ user_column_data.column_name （非推奨） "FULL_NAME" ユーザーの姓名。 「氏名」 "FIRST_NAME" ユーザーの名前。 「名」 "LAST_NAME" ユーザーの姓。 「姓」 「EMAIL」 ユーザーのメールアドレス。 「ユーザーのメールアドレス」 "PHONE_NUMBER" E.164 形式のユーザーの電話番号（例: "[phone]" 「User Phone」 "PHONE_NUMBER_VERIFIED" ユーザーの電話番号が確認済みかどうか。 「電話番号の確認」 「POSTAL_CODE」 ユーザーの郵便番号。 「郵便番号」 "COMPANY_NAME" ユーザーの会社名。 "会社名" "JOB_TITLE" ユーザーの役職。 「役職」 "WORK_EMAIL" ユーザーの仕事用メールアドレス。 「仕事用メール」 "WORK_PHONE" ユーザーの仕事用電話番号。 「仕事用電話番号」 "STREET_ADDRESS" ユーザーの番地。 "Street Address" 「CITY」 ユーザーの市区町村。 「市区町村」 "REGION" ユーザーの地域。 「地域」 "COUNTRY" ユーザーの国。 "Country" "VEHICLE_MODEL" どのモデルに興味がありますか？ なし "VEHICLE_TYPE" どのタイプの車に興味がありますか？ なし "PREFERRED_DEALERSHIP" ご希望のディーラーをお選びください。 なし "VEHICLE_PURCHASE_TIMELINE" 車の購入はいつごろを予定していますか？ なし "VEHICLE_CONDITION" どのような状態の車に興味がありますか？ なし "VEHICLE_OWNERSHIP" 車をお持ちですか？ 「N/A」 "VEHICLE_PAYMENT_TYPE" 車を所有するにあたり、どのような形でのお支払いをお考えですか？ なし "COMPANY_SIZE" 会社の規模をお知らせください。 なし "ANNUAL_SALES" 年間売上を教えてください。 なし "YEARS_IN_BUSINESS" 営業年数はどのくらいですか？ なし "JOB_DEPARTMENT" 仕事の部門をお聞かせください。 なし "JOB_ROLE" 役職をお聞かせください。 なし "EDUCATION_PROGRAM" どのプログラムに興味がありますか？ なし "EDUCATION_COURSE" どのコースに興味がありますか？ なし 「PRODUCT」 どの商品に興味がありますか？ なし 「SERVICE」 どのサービスに興味がありますか？ なし "OFFER" どの特典に興味がありますか？ なし 「CATEGORY」 興味があるカテゴリはどれですか？ なし "PREFERRED_CONTACT_METHOD" ご希望の連絡方法をお選びください なし "PREFERRED_LOCATION" お好みの場所をお選びください なし "PREFERRED_CONTACT_TIME" ご都合のよい連絡時間はいつですか？ なし "PURCHASE_TIMELINE" いつ頃の購入をご検討ですか？ なし "YEARS_OF_EXPERIENCE" 職務の経験年数はどれくらいですか？ なし "JOB_INDUSTRY" どのような業種ですか？ なし "LEVEL_OF_EDUCATION" 最終学歴をお聞かせください。 なし "PROPERTY_TYPE" どのような物件をお探しですか？ なし 「REALTOR_HELP_GOAL」 不動産仲介業者にどのようなサポートをお求めですか？ なし "PROPERTY_COMMUNITY" どのようなコミュニティに興味がありますか？ なし "PRICE_RANGE" ご希望の価格帯をお聞かせください。 なし "NUMBER_OF_BEDROOMS" 寝室の数はいくつをご希望ですか？ なし "FURNISHED_PROPERTY" 家具付きの物件をお探しですか？ なし "PETS_ALLOWED_PROPERTY" ペット可の物件をお探しですか？ なし 「NEXT_PLANNED_PURCHASE」 次に購入する予定の商品は何ですか？ なし "EVENT_SIGNUP_INTEREST" イベントに申し込みますか？ なし 「PREFERRED_SHOPPING_PLACES」 どこでショッピングをしたいですか？ なし "FAVORITE_BRAND" お気に入りのブランドを教えてください。 なし "TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" お持ちの有効な営業許可の種類をお聞かせください。 なし "EVENT_BOOKING_INTEREST" イベントの予約をご希望ですか？ なし "DESTINATION_COUNTRY" 目的国をお知らせください。 なし "DESTINATION_CITY" 目的地の都市をお知らせください。 なし 「DEPARTURE_COUNTRY」 出発国をお知らせください。 なし "DEPARTURE_CITY" 出発地の都市をお知らせください。 なし "DEPARTURE_DATE" 出発日をお知らせください。 なし "RETURN_DATE" 復路の出発日をお知らせください。 なし "NUMBER_OF_TRAVELERS" 何人でのご旅行ですか？ なし "TRAVEL_BUDGET" 旅行の予算をお聞かせください。 なし "TRAVEL_ACCOMMODATION" 旅行中に滞在する場所をお知らせください。 なし
asset_group_id	このフィールドは、パフォーマンス最大化キャンペーンでのみ入力されます。これは、見込み顧客フォームを含むコンテナ ID を示します。 クライアントは、8 バイトの整数を使用して処理する必要があります。
lead_stage	これは、リードの配信時のリードステージを示します。このフィールドは、見込み顧客のファネルステージやコンバージョンのステータスを追跡するのに役立ちます。
lead_submit_time	これは、ユーザーがフォームを送信したときのタイムスタンプを示します。ISO-8601 形式で表されます。例: 2024-09-26T12:30:00Z

認識されないフィールドと上位互換性

Webhook 統合の堅牢性を維持し、将来の機能強化に対応できるようにするには、システムが明示的に使用または認識しない Webhook ペイロード内のフィールドを適切に無視するように JSON パーサーを設計することが標準的なベスト プラクティスです。

重要な推奨事項: アプリケーションで特に必要なフィールドのみを処理するように JSON 解析ロジックを構成します。固定されたフィールド セットを想定するコードや、予期しない新しいフィールドがペイロードに含まれている場合に失敗するコードは記述しないでください。

重要な理由:

• 前方互換性: Google は、将来の更新で、より豊富なデータや新機能を提供するために、新しいオプション フィールドをウェブフック ペイロードに追加する可能性があります。パーサーが厳しすぎると（不明なプロパティで失敗するなど）、Google がこのような非破壊的変更をロールアウトしたときに統合が中断する可能性があります。
• メンテナンスの簡素化: 実際に使用するデータポイントのみに焦点を当てることで、統合コードがシンプルになり、メンテナンスが容易になります。

最近の JSON 解析ライブラリのほとんどには、不明なプロパティをデフォルトで無視するオプションが用意されているか、そのように構成できます。

セールスリードのハンドリング

リード ハンドラは次の HTTP コードで応答する必要があります。

HTTP レスポンス	レスポンスの本文（JSON）	再試行可能なエラーですか？
200	{}	なし
4XX	{"message: リクエストの何が間違っていたかを説明する自由形式のエラー テキスト"}	いいえ
5XX	{"message: 断続的な再試行可能なエラーのオプション メッセージ"}	はい

重複

1 つのリードが 1 回だけ配信されるとは限りません。そのため、リード処理ウェブフックは重複を適切に処理する必要があります。

重要なポイント: lead_id を使用して見込み顧客を重複除去します。