구현

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

필드 설명

필드	설명
lead_id	지정된 리드를 식별하는 고유한 문자열입니다. 처리 권장사항: 수신된 리드의 중복을 제거하는 데 사용합니다. 이 값은 모든 양식에서 고유합니다. 특정 리드와 관련된 문제를 신고할 때 이 ID가 필요합니다.
api_version	이 리드 스키마가 속한 API 버전입니다. 새 스키마로 이전할 때 사용되며 지금은 무시해도 됩니다.
form_id	Google Ads에서 구성된 각 양식의 고유 ID입니다. 현재 제품에서는 광고 그룹 또는 광고 수준에서 첨부하는 대신 캠페인 수준에서 양식을 첨부할 수 있습니다. 영향: 리드는 form_id 수준 (즉, 캠페인 수준)에서만 분류할 수 있습니다. 클라이언트는 8바이트 정수를 사용하여 처리해야 합니다.
campaign_id	연결된 리드 양식의 Google Ads 캠페인 ID 또는 광고 항목 ID (Display & Video 360)입니다. 클라이언트는 8바이트 정수를 사용하여 처리해야 합니다.
adgroup_id	Google Ads 광고 그룹 ID는 캠페인의 특정 광고 그룹을 구분하는 데 사용됩니다. (동영상 및 디스커버리 광고의 리드에만 사용 가능) 클라이언트는 8바이트 정수를 사용하여 처리해야 합니다.
creative_id	Google Ads 광고 소재 ID는 광고 그룹의 특정 광고 소재를 구분하는 데 사용됩니다. (동영상 및 디스커버리 광고의 리드에만 사용 가능) 클라이언트는 8바이트 정수를 사용하여 처리해야 합니다.
gcl_id	Google 클릭 ID: 광고의 각 클릭을 추적하는 데 사용되는 고유한 매개변수입니다.
google_key	광고주가 각 양식에 구성한 키입니다. 처리 권장사항: 웹훅을 통해 수신된 리드를 처리하기 전에 google_key가 Google Ads에서 구성된 것과 동일한지 확인하여 리드가 유효하다는 확신을 높이세요. 이 키를 기밀로 유지하고, 이 키가 널리 유출되었다고 생각되는 이유가 있는 경우 Google Ads에서 업데이트하세요.
is_test	이 필드는 '선택사항' 시맨틱을 갖습니다. 값이 true이면 이 리드를 테스트 리드로 처리합니다. 값이 false이거나 필드가 없으면 이 리드를 유효한 프로덕션 리드로 처리합니다.
user_column_data	사용자가 제출한 데이터를 전송하는 반복된 키-값 튜플입니다. 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]". '사용자 전화' 'PHONE_NUMBER_VERIFIED' 사용자 전화번호가 인증되었는지 여부입니다. '전화번호 인증됨' 'POSTAL_CODE' 사용자의 우편번호입니다. '우편번호' 'COMPANY_NAME' 사용자의 회사 이름입니다. '회사 이름' 'JOB_TITLE' 사용자의 직책입니다. '직책' 'WORK_EMAIL' 사용자의 직장 이메일입니다. '직장 이메일' 'WORK_PHONE' 사용자의 직장 전화번호입니다. '직장 전화' 'STREET_ADDRESS' 사용자의 상세 주소입니다. 'Street Address' 'CITY' 사용자의 도시입니다. '도시' 'REGION' 사용자의 지역입니다. 'Region' '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

인식할 수 없는 필드 및 상위 호환성

웹훅 통합이 안정적으로 유지되고 향후 개선사항에 적응할 수 있도록 하려면 시스템에서 명시적으로 사용하거나 인식하지 않는 웹훅 페이로드 내 필드를 정상적으로 무시하도록 JSON 파서를 설계하는 것이 표준 권장사항입니다.

주요 권장사항: 애플리케이션에 필요한 필드만 처리하도록 JSON 파싱 로직을 구성하세요. 고정된 필드 집합을 예상하거나 페이로드에 예상치 못한 새 필드가 있으면 실패하는 코드를 작성하지 마세요.

중요한 이유:

• 하위 호환성: Google은 향후 업데이트에서 더 풍부한 데이터나 새로운 기능을 제공하기 위해 웹훅 페이로드에 선택사항인 새 필드를 추가할 수 있습니다. 파서가 너무 엄격한 경우 (예: 알 수 없는 속성에서 실패) Google에서 이러한 비호환성 변경사항을 출시할 때 통합이 중단될 수 있습니다.
• 간소화된 유지관리: 적극적으로 사용하는 데이터 포인트에만 집중하면 통합 코드가 더 간단해지고 유지관리도 더 쉬워집니다.

대부분의 최신 JSON 파싱 라이브러리는 기본적으로 알 수 없는 속성을 무시하는 옵션을 제공하거나 이를 무시하도록 구성할 수 있습니다.

리드 처리

리드 핸들러는 다음 HTTP 코드로 응답해야 합니다.

HTTP 응답	응답 본문 (JSON)	재시도 가능한 오류인가요?
200	{}	해당 사항 없음
4XX	{"message: Free form error text, describing what was wrong with request"}	아니요
5XX	{"message: 간헐적 재시도 가능 오류 선택적 메시지"}	예

중복

단일 리드가 정확히 한 번 전송된다고 보장할 수 없으므로 리드 처리 웹훅은 중복을 적절하게 처리해야 합니다.

핵심 사항: lead_id를 사용하여 리드를 중복 삭제합니다.