구현

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

필드 설명

필드	설명
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]". "사용자 전화" 'POSTAL_CODE' 사용자의 우편번호입니다. 우편번호 'COMPANY_NAME' 사용자의 회사 이름입니다. '회사 이름' "JOB_TITLE" 사용자의 직책입니다. '직책' 'WORK_EMAIL' 사용자의 직장 이메일입니다. '직장 이메일' 'WORK_PHONE' 사용자의 직장 전화번호입니다. '직장 전화' 'STREET_ADDRESS' 사용자의 상세 주소입니다. '상세 주소' 'CITY' 사용자의 도시입니다. '도시' 'REGION' 사용자의 지역입니다. '지역' 'COUNTRY' 사용자의 국가입니다. '국가' 'VEHICLE_MODEL' 어떤 모델에 관심이 있으신가요? N/A 'VEHICLE_TYPE' 어떤 종류의 차량에 관심이 있으신가요? N/A 'PREFERRED_DEALERSHIP' 선호하는 대리점을 선택하세요 N/A 'VEHICLE_PURCHASE_TIMELINE' 차량을 언제 구매할 계획이신가요? N/A 'VEHICLE_CONDITION' 어떤 유형의 차량 상태에 관심이 있으신가요? N/A 'VEHICLE_OWNERSHIP' 소유하고 있는 차량이 있으신가요? '해당 사항 없음' 'VEHICLE_PAYMENT_TYPE' 차량을 어떤 방식으로 소유하고 싶으신가요? N/A 'COMPANY_SIZE' 회사의 규모가 어느 정도인가요? N/A 'ANNUAL_SALES' 연간 판매량이 어느 정도인가요? N/A 'YEAR_IN_BUSINESS' 사업한 지 몇 년이나 되셨나요? N/A 'JOB_DEPARTMENT' 어떤 부서에서 근무하시나요? N/A 'JOB_ROLE' 어떤 직무를 맡고 계신가요? N/A 'EDUCATION_PROGRAM' 어떤 프로그램에 관심이 있으신가요? N/A 'EDUCATION_COURSE' 어떤 과정에 관심이 있으신가요? N/A 'PRODUCT' 어떤 제품에 관심이 있으신가요? N/A 'SERVICE' 어떤 서비스에 관심이 있으신가요? N/A 'OFFER' 어떤 상품에 관심이 있으신가요? N/A 'CATEGORY' 어떤 카테고리에 관심이 있으신가요? N/A 'PREFERRED_CONTACT_METHOD' 선호하는 연락 방법을 선택하세요 N/A "PREFERRED_LOCATION" 선호하는 위치를 선택하세요 N/A 'PREFERRED_CONTACT_TIME' 연락받기 가장 편하신 시간은 몇 시인가요? N/A 'PURCHASE_TIMELINE' 언제 구매할 예정이신가요? N/A 'YEAR_OF_EXPERIENCE' 몇 년의 업무 경험이 있으신가요? N/A 'JOB_INDUSTRY' 어떤 업계에 종사하시나요? N/A 'LEVEL_OF_EDUCATION' 최종 학력은 어떻게 되시나요? N/A 'PROPERTY_TYPE' 어떤 유형의 숙박시설을 찾고 계신가요? N/A 'REALTOR_HELP_GOAL' 공인중개사의 도움이 왜 필요하신가요? N/A 'PROPERTY_COMMUNITY' 어떤 커뮤니티에 관심이 있으신가요? N/A "PRICE_RANGE" 어떤 가격대를 찾고 계신가요? N/A 'NUMBER_OF_BEDROOMS개' 침실이 몇 개 필요하신가요? N/A 'FURNISHED_PROPERTY' 가구가 완비된 숙박 시설을 찾고 계신가요? N/A "PETS_ALLOWED_PROPERTY" 반려동물 동반이 가능한 숙박 시설을 찾고 계신가요? N/A 'NEXT_PLANNED_PURCHASE' 구매하시려는 다음 제품이 무엇인가요? N/A 'EVENT_SIGNUP_INTEREST' 이벤트에 참여하고 싶으신가요? N/A 'PREFERRED_SHOPPING_PLACES' 어디에서 쇼핑하는 것을 좋아하시나요? N/A 'FAVORITE_BRAND' 가장 좋아하는 브랜드가 무엇인가요? N/A "TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" 어떤 유형의 유효한 상업용 라이선스를 갖고 계신가요? N/A 'EVENT_BOOKING_INTEREST' 이벤트 예약에 관심이 있으신가요? N/A "DESTINATION_COUNTRY" 도착 국가가 어디인가요? N/A 'DESTINATION_CITY' 도착 도시가 어디인가요? N/A '출발_국가' 출발 국가가 어디인가요? N/A '출발 도시' 출발 도시가 어디인가요? N/A '출발 날짜' 출발 날짜가 언제인가요? N/A 'RETURN_DATE' 돌아오는 날짜가 언제인가요? N/A 'NUMBER_OF_TRAVELERS' 몇 명이 함께 여행하시나요? N/A 'TRAVEL_예산' 여행 예산이 어느 정도인가요? N/A 'TRAVEL_ACCOMMODATION' 여행 중 어디에 머물고 싶으신가요? N/A

리드 처리

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

HTTP 응답	응답 본문 (JSON)	재시도 가능한 오류인가요?
200	{}	N/A
4XX	{"메시지: 요청의 문제를 설명하는 자유 형식 오류 텍스트"}	No
5XX	{"message: 간헐적인 복구 가능 오류 옵션 메시지"}	지원됨

중복

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

핵심사항: lead_id를 사용하여 중복 리드를 삭제하세요.