実装

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。現在のプロダクトでは、フォームをキャンペーン単位で添付できます(広告グループ単位または広告単位での添付はできません)。

影響: リードは 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" ユーザーの姓名。 "Full Name"
"FIRST_NAME" ユーザーの名前。 "First Name"
"LAST_NAME" ユーザーの姓。 "Last Name"
"EMAIL" ユーザーのメールアドレス。 "User Email"
"PHONE_NUMBER" E.164 形式のユーザーの電話番号(例: "+11234567890")。 "User Phone"
"PHONE_NUMBER_VERIFIED" ユーザーの電話番号が確認済みかどうか。 "Phone Number Verified"
"POSTAL_CODE" ユーザーの郵便番号。 "Postal Code"
"COMPANY_NAME" ユーザーの会社名。 "Company Name"
"JOB_TITLE" ユーザーの役職。 "Job Title"
"WORK_EMAIL" ユーザーの仕事用メールアドレス。 "Work Email"
"WORK_PHONE" ユーザーの仕事用電話番号。 "Work Phone"
"STREET_ADDRESS" ユーザーの番地。 "Street Address"
"CITY" ユーザーの市区町村。 "City"
"REGION" ユーザーの地域。 "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 このフィールドは、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 回だけ配信されるとは限りません。そのため、リード処理ウェブフックは重複を適切に処理する必要があります。