Google ads api 문제 해결 2059ed60ad7d800f9954e26f93fde0a7 - all-ad/all-ad GitHub Wiki

문제 해결

전환을 관리하려면 종종 상호 종속된 여러 도구와 프로세스가 포함된 복잡한 통합이 필요합니다. 이 가이드에서는 API에서 이해할 수 없는 오류가 발생했거나 UI에 표시되는 측정항목이나 진단에 대해 혼란스러운 경우와 같이 발생한 문제를 해결하기 위해 취할 수 있는 세부적인 단계를 제공합니다.

중요: API에서 가져오기 응답이 성공했다고 해서 반드시 전환 기여도가 부여되었다는 의미는 아닙니다. 가져오기가 완료된 후의 데이터 불일치에 관한 자세한 내용은 이 고객센터 도움말을 참고하세요.

Google Ads UI에서 측정항목 읽기

Google Ads UI는 가져오기 날짜별로 전환 측정항목을 정리하지 않으므로 UI의 보고서를 사용하여 가져오기 결과를 확인하면 혼동을 줄 수 있습니다. 가져오기 상태를 확인하려면 오프라인 진단부터 시작하세요. Google Ads UI에서 리드 확보용 향상된 전환 및 웹용 향상된 전환에 대한 진단에 관해 자세히 알아볼 수도 있습니다.

리드 확보용 향상된 전환 문제

이 섹션에서는 리드의 향상된 전환을 가져올 때 발생하는 일반적인 문제를 해결하는 방법을 설명합니다.

일반적인 실수

오류
NO_CONVERSION_ACTION_FOUND 지정된 전환 액션이 사용 설정되지 않았거나 요청의 client_id 필드에 지정된 고객 계정에서 액세스할 수 없습니다. 업로드의 전환 액션이 사용 설정되어 있고 업로드 요청을 전송하는 고객이 소유하고 있는지 확인합니다.
요청의 GCLID가 요청에 지정된 전환 액션에 액세스할 수 없는 고객 계정에 속하는 경우에도 이 오류가 발생할 수 있습니다. click_view 리소스를 사용하여 GCLID가 클라이언트 계정에 속하는지 확인할 수 있습니다. click_view.gclid 및 **segments.date**로 필터링하는 쿼리를 제출하면 됩니다. 여기서 날짜는 클릭이 발생한 날짜입니다.
INVALID_CONVERSION_ACTION_TYPE 지정된 전환 액션의 유형이 리드 확보용 향상된 전환에 유효하지 않습니다. 업로드 요청에 지정된 **ConversionAction**의 유형이 **UPLOAD_CLICKS**인지 확인합니다.
CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS 전환 설정에서 리드 확보용 향상된 전환을 사용 설정했는지 확인합니다. 기본 요건 가이드에서 이에 관한 안내를 확인하세요.
DUPLICATE_ORDER_ID 가져온 이벤트에 주문 ID가 동일한 전환이 여러 개 포함되어 있어 처리되지 않았습니다. 주문 ID가 고유한지 확인한 후 다시 시도해 주세요.
CLICK_NOT_FOUND 제공된 사용자 식별자와 일치하는 클릭이 없습니다. Google Ads API는 UploadClickConversionsRequest에서 **debug_enabled**이 **true**인 경우에만 이 오류를 반환합니다.참고: 이 오류가 대부분의 전환에서 발생하지 않는 한 경고로 취급합니다.
전환에서 이 경고가 발생하면 Google Ads API는 오프라인 데이터 진단의 **successful_event_count**에 이를 포함합니다. Google Ads API에는 이 경고의 빈도를 모니터링할 수 있도록 alerts 컬렉션에 CLICK_NOT_FOUND 항목이 포함되어 있습니다.
클릭이 Google Ads 캠페인에서 발생하지 않은 경우 이 오류가 발생할 수 있습니다. 예를 들어 SA360 또는 DV360에서 가져올 수 있습니다. 그 밖의 가능한 원인은 다음과 같습니다.
• 업로드 고객은 Google Ads 전환 고객과 다릅니다.
• 리드 양식에 태그 지정이 올바르게 구성되지 않았습니다.
• 업로드된 데이터가 올바르게 정규화 및 해싱되지 않았습니다.
업로드 고객이 Google Ads 전환 고객과 다른 드문 경우 이 오류는 업로드 고객이 고객 데이터 약관에 동의했지만 게재 고객이 동의하지 않았음을 의미할 수 있습니다.customer 리소스를 쿼리하고 customer.offline_conversion_tracking_info.accepted_customer_data_terms 필드를 확인하여 계정이 고객 데이터 약관에 동의했는지 확인할 수 있습니다.

측정항목 불일치

다음과 같은 일반적인 문제에 유의하세요.

  • 다양한 이유로 Google의 처리 파이프라인에서 전환이 누락될 수 있으며 이러한 전환은 복구할 수 없습니다. 자세한 내용은 업로드 완료 후 데이터 불일치 도움말을 참고하세요.
  • Google 태그가 웹페이지에 올바르게 설정되어 있고 리드 양식 제출 시 실행되는지 다시 한번 확인합니다. 양식 제출 시 태그가 실행되지 않거나 잘못된 데이터를 전송하는 경우 업로드된 전환에 기여도가 낮거나 기여도가 표시되지 않을 수 있습니다. 리드 확보용 향상된 전환을 위해 Google 태그 구성 및 Google 태그 관리자 구성에 관한 고객센터 도움말을 검토하세요.
  • 웹페이지에 Google 태그가 없는 상태에서 리드 확보용 향상된 전환을 사용하는 경우 각 전환에서 ClickConversion.gclid 필드를 설정하여 전환 가져오기에 GCLID를 포함해야 합니다.
  • 업로드에서 동의를 올바르게 지정했는지 확인합니다. 계정의 기본 동의 설정을 지정하거나(Google Ads UI에서 도구 -> 데이터 관리 도구 -> 동의 설정을 클릭) 업로드된 각 전환에서 ClickConversion.consent 필드를 설정하면 됩니다.

캠페인 실적 문제

전환을 업로드하는 데 기술적 문제가 없고 표시되는 측정항목에 문제가 없지만 리드 확보를 위한 향상된 전환을 구현한 후 예상되는 캠페인 실적 개선 또는 '실적 상승'이 보이지 않으면 Google Ads 제품 지원팀에 문의하세요.

웹용 향상된 전환 문제

이 섹션에서는 웹용 향상된 전환을 가져올 때 발생하는 일반적인 문제를 해결하는 방법을 중점적으로 설명합니다.

일반적인 실수

오류
CONVERSION_NOT_FOUND 제공된 전환 액션 및 전환 식별자 쌍 또는 **order_id**의 전환을 찾을 수 없습니다. 요청의 **customer_id**에 지정된 Google Ads 전환 고객의 Google Ads 전환인지 확인합니다.또한 gclid 대신 gbraid 또는 **wbraid**가 채워진 클릭으로 인한 전환이 아닌지 확인합니다. Google Ads에서는 이러한 전환에 웹용 향상된 전환을 지원하지 않습니다.
CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS 요청의 **customer_id**에 대해 고객 데이터 약관에 동의하지 않았습니다. 기본 요건 가이드에서 이에 관한 안내를 확인하세요.
CONVERSION_ALREADY_ENHANCED 이 전환은 이미 지정된 order_id 및 **conversion_action**로 조정되었습니다. 각 전환에 고유한 **order_id**를 제공해야 합니다.
CONVERSION_ACTION_NOT_ELIGIBLE_FOR_ENHANCEMENT 제공된 **conversion_action**가 웹용 향상된 전환에 사용할 수 없습니다. Google Ads UI에서 요청에 참조된 전환 액션의 향상된 전환 사용 설정 체크박스를 선택해야 합니다. 고객센터에서 자세한 안내를 확인하세요.

일반 전환 관리 문제

다음과 같은 일반적인 문제에 유의하세요.

  • enum 필드를 **UNKNOWN**로 설정하려고 하면 RequestError.INVALID_ENUM_VALUE 오류가 발생합니다. 이는 광고주가 동의가 이루어졌는지 알 수 없는 경우 **consent**를 지정할 때 발생하는 일반적인 문제입니다. **consent**의 상태를 알 수 없는 경우 **DENIED**로 설정해야 합니다.
  • 앱 전환 또는 Firebase 및 서드 파티 앱 애널리틱스의 전환 액션을 만들 때는 만들 때만 app_id 필드를 변경할 수 있으며, 전환 액션이 생성된 후에는 이 필드를 변경할 수 없습니다.
  • 전환 액션을 만들 때는 ConversionAction.attribution_model_settings.attribution_model 필드를 GOOGLE_ADS_LAST_CLICK 또는 GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN로만 설정할 수 있습니다. 다른 옵션을 사용하면 CANNOT_SET_RULE_BASED_ATTRIBUTION_MODELS 오류가 발생합니다. 다른 기여 분석 모델의 지원 중단을 발표하는 블로그 게시물에서 자세한 내용을 확인하세요.
  • click_through_lookback_window_days 필드의 허용 범위는 유형이 AD_CALL 및 **WEBSITE_CALL**인 전환 액션의 경우 **[1, 60]**입니다. 대부분의 다른 전환 액션의 허용 범위는 **[1, 30]**입니다.
  • 대부분의 전환 액션의 경우 view_through_lookback_window_days 필드의 허용 범위는 **[1, 30]**입니다. AD_CALL 및 WEBSITE_CALL 유형의 전환 액션의 경우 이 필드는 설정 해제되어야 합니다.
  • 전환 액션에서 include_in_conversion_metrics 필드를 설정하거나 업데이트하면 FieldError.IMMUTABLE_FIELD 오류가 발생합니다. 대신 전환 목표 가이드에 설명된 대로 primary_for_goal 필드를 설정합니다.
  • WEBSITE_CALL 또는 AD_CALL 유형의 전환 액션을 만들 때는 value_settings.always_use_default_value을 **true**로 설정해야 합니다. false 값을 지정하면 INVALID_VALUE 오류가 발생합니다.

일반적인 실수

오류
INVALID_CONVERSION_ACTION_TYPE 지정된 전환 액션의 유형이 클릭 전환 업로드에 유효하지 않습니다. 업로드 요청에 지정된 **ConversionAction**의 유형이 **UPLOAD_CLICKS**인지 확인합니다.
NO_CONVERSION_ACTION_FOUND 지정된 전환 액션이 사용 설정되지 않았거나 업로드 중인 customer_id 내에 없음 전환 설정에 관한 정보를 가져와 업로드의 전환 액션이 사용 설정되어 있고 업로드 요청의 **customer_id**가 소유하고 있는지 확인합니다.
TOO_RECENT_CONVERSION_ACTION 전환 액션이 새로 생성됩니다. 액션이 생성된 후 6시간 이상 기다린 후 실패한 전환을 다시 시도합니다.
INVALID_CUSTOMER_FOR_CLICK 요청의 **customer_id**가 클릭 시 Google Ads API 전환 계정이었던 고객 ID와 다릅니다. 요청의 **customer_id**를 올바른 고객으로 업데이트합니다.
EVENT_NOT_FOUND Google Ads에서 클릭 ID와 **customer_id**의 조합을 찾을 수 없습니다. customer_id 요구사항을 검토하고 올바른 Google Ads 계정을 사용하여 업로드하고 있는지 확인합니다.
DUPLICATE_CLICK_CONVERSION_IN_REQUEST 요청에 포함된 여러 전환의 클릭 ID, conversion_date_time, conversion_action 조합이 동일합니다. 요청에서 중복 전환을 삭제합니다.
CLICK_CONVERSION_ALREADY_EXISTS 클릭 ID, conversion_date_time, **conversion_action**의 조합이 동일한 전환이 이전에 업로드되었습니다. 업로드를 다시 시도 중이고 이전에 이 변환이 성공한 경우 이 오류를 무시합니다. 이전에 업로드한 전환 외에도 다른 전환을 추가하려면 이전에 업로드한 전환이 중복되지 않도록 **ClickConversion**의 **conversion_date_time**를 조정하세요.
EVENT_NOT_FOUND Google Ads에서 클릭 ID와 **customer_id**의 조합을 찾을 수 없습니다. customer_id 요구사항을 검토하고 올바른 Google Ads 계정을 사용하여 업로드하고 있는지 확인합니다.
EXPIRED_EVENT 가져온 클릭이 click_through_lookback_window_days 필드에 지정된 기간 전에 발생했습니다. **click_through_lookback_window_days**를 변경하면 변경 후에 기록된 클릭에만 영향을 미치므로 전환 확인 기간을 변경해도 특정 클릭에 대한 이 오류가 해결되지 않습니다. 적절한 경우 전환 확인 기간이 더 긴 다른 작업으로 **conversion_action**를 변경합니다.
CONVERSION_PRECEDES_EVENT **conversion_date_time**는 클릭 날짜와 시간보다 이전입니다. **conversion_date_time**를 이후 값으로 업데이트합니다.
GBRAID_WBRAID_BOTH_SET **ClickConversion**에는 gbraid 및 wbraid 모두에 설정된 값이 있습니다. 클릭 ID를 하나만 사용하도록 전환을 업데이트하고 여러 클릭을 하나의 전환으로 결합하지 않도록 합니다. 각 클릭에는 클릭 ID가 하나만 있습니다.
VALUE_MUST_BE_UNSET **GoogleAdsError**의 location를 확인하여 다음 문제 중 어떤 문제가 오류를 일으켰는지 확인합니다.
• **ClickConversion**에는 gclid 값과 gbraid 또는 wbraid 중 하나 이상이 설정되어 있습니다. 클릭 ID를 하나만 사용하도록 전환을 업데이트하고 여러 클릭을 하나의 전환으로 결합하지 않도록 합니다. 각 클릭에는 클릭 ID가 하나만 있습니다.
• **ClickConversion**에는 gbraid 또는 **wbraid**에 설정된 값과 custom_variables 값이 있습니다. Google Ads에서는 gbraid 또는 wbraid 클릭 ID가 있는 전환에 맞춤 변수를 지원하지 않습니다. 전환의 custom_variables 필드를 설정 해제합니다.

2.2 타겟 사용자 세그먼트 (수정된 내용)

  • Primary Target (주요 타겟): 1인 기업부터 중견기업까지, 특히 마케팅 툴 사용에 익숙하지 않거나 1인이 다수의 광고 채널 운영 및 기타 업무를 동시에 처리해야 하는 환경에 놓인 담당자 및 사업주를 핵심 타겟으로 합니다. 이들은 시간 부족과 여러 플랫폼 관리의 복잡함으로 인해 광고 운영 효율화 및 통합 리포팅에 대한 니즈가 매우 큽니다.
  • Overall Target (전체 타겟): 광고 채널 수나 데이터 분석 수준에 관계없이, 두 개 이상의 광고 플랫폼을 운영하는 모든 개인 및 기업을 잠재 고객으로 설정합니다. '올애드'를 통해 자연스럽게 데이터 기반 의사결정을 경험하도록 지원하는 것을 목표로 합니다.

5.2 요금제 구조 (새로운 버전별 계획)

버전 1 (초기 출시 버전):

  • 가격 모델: 전체 무료
  • 이용 가능 플랫폼: 구글(Google Ads), 메타(Meta Ads)
  • 이용 가능 인원: 계정당 최대 5명
  • API 호출 제한: 호출 횟수 자체는 무제한이나, 데이터 업데이트는 시간당 1회로 제한

버전 2 (기능 확장 후):

  • 가격 모델: 부분 무료 (Freemium) 및 구독 기반
  • 요금제 세부 구조:
    • Free Plan:
      • 이용 가능 플랫폼: 구글(Google Ads), 메타(Meta Ads)
      • 이용 가능 인원: 계정당 최대 2명
      • API 호출 제한: 1일 2회 (데이터 업데이트 주기)
    • Starter Plan: (유료)
      • Free Plan 모든 기능 포함
      • 추가 연동 플랫폼: 네이버 광고(Naver Ads), 쿠팡 애즈(Coupang Ads)
      • 이용 가능 인원: 계정당 최대 3명
      • API 호출 제한: 1일 3회
    • Plus Plan: (유료)
      • Starter Plan 모든 기능 포함
      • 추가 연동 플랫폼: 올애드에서 제공하는 모든 플랫폼 연동 가능
      • 이용 가능 인원: 계정당 최대 5명
      • API 호출 제한: 1일 5회
    • Pro Plan: (유료)
      • Plus Plan 모든 기능 포함
      • API 호출 제한: 무제한 (실시간 또는 매우 빈번한 데이터 업데이트 가능)
      • 이용 가능 인원: 계정당 최대 10명

사용자 역할 및 구조

1. Master (마스터):

  • 권한: 계정 내 모든 설정 및 기능에 접근하고 관리할 수 있는 최상위 관리자입니다.
  • 주요 기능:
    • 광고 플랫폼 계정 연동 및 해제
    • 요금제 관리 및 결제 정보 변경
    • 모든 대시보드 및 리포트 생성, 조회, 수정, 삭제
    • 모든 캠페인 데이터 조회
    • 모든 캠페인 관리 기능 사용 (ON/OFF, 예산 변경, 생성, 수정, 삭제 등 - 향후 구현될 기능 포함)
    • 모든 사용자(Master, Team Mate, Viewer) 초대, 역할 변경, 삭제
    • 서비스 관련 모든 알림 및 설정 변경
  • 용도: 계정 소유자, 핵심 관리자, 에이전시 대표 등

2. Team Mate (팀 메이트):

  • 권한: 광고 캠페인 운영 및 관리에 필요한 주요 편집 권한과 하위 사용자 초대 권한을 가집니다.
  • 주요 기능:
    • 할당된 또는 전체 광고 플랫폼 데이터 조회
    • 대시보드 및 리포트 조회 (생성/수정 권한은 Master가 부여 가능 여부 결정 필요)
    • 담당 캠페인 편집 가능 (ON/OFF, 예산 변경, 타겟팅 수정 등 - 향후 구현될 기능 포함)
    • 신규 사용자 초대 (초대 가능한 역할 범위는 Master가 설정)
    • 캠페인 성과 관련 알림 수신
  • 용도: 실무 마케터, 캠페인 운영 담당자, 에이전시 팀원 등

3. Viewer (뷰어):

  • 권한: 데이터 조회만 가능한 읽기 전용 사용자입니다.
  • 주요 기능:
    • 할당된 광고 플랫폼 데이터 및 대시보드, 리포트 조회
    • 모든 편집 및 설정 변경 불가
    • 사용자 초대 불가
  • 용도: 성과 보고를 받아보는 클라이언트, 의사결정을 위한 데이터 참고가 필요한 내부 임원 또는 팀원 등

4. 최고 운영자 계정 (King of Master ID - '올애드' 내부 관리용):

  • 정의: 이 계정은 '올애드(All-AD)' 서비스 운영팀 내부에서 사용하는 특수 관리 계정으로, 일반 사용자에게 할당되거나 직접 제공되지 않습니다.
  • 주요 목적:
    • 고객 지원: 사용자의 명시적인 요청 또는 동의가 있을 경우, 기술적 문제 해결, 복잡한 설정 지원, 오류 진단 등을 위해 해당 사용자 계정에 접근하여 지원합니다.
    • 시스템 유지보수: 서비스의 안정성 확보, 데이터 무결성 검증, 시스템 업데이트 등 내부적인 시스템 관리 및 운영을 위해 사용됩니다.
    • 계정 관련 긴급 상황 대응: 사용자의 계정 복구 지원(정상적인 절차로 불가능할 경우) 등 긴급한 문제 해결을 위해 사용될 수 있습니다.
  • 권한 및 통제:
    • 이론적으로 서비스 내 모든 사용자 계정 및 데이터에 대한 접근 권한을 가질 수 있으나, 실제 접근은 엄격한 내부 보안 정책, 다중 인증(MFA), 접근 통제 프로토콜, 명확한 승인 절차에 따라 제한적으로 허용됩니다.
    • 모든 접근 및 작업 내역은 상세한 감사 로그(Audit Log)로 기록되어 투명성과 책임성을 확보합니다.
    • 운영팀의 계정 접근은 개인정보보호법 등 관련 법규를 철저히 준수하며, 이용약관 및 개인정보처리방침에 명시된 절차에 따라 필요한 경우 사용자에게 고지되거나 동의를 구하는 것을 원칙으로 합니다.
  • 성격: 일반적인 사용자 역할과 달리, 서비스 제공 및 유지를 위한 내부 운영 및 기술 지원을 위한 관리자 권한입니다.
⚠️ **GitHub.com Fallback** ⚠️