앱 전환 추적 및 리마케팅 - 요청/응답 사양

앱 사용자 에이전트

스팸을 퇴치하기 위한 광범위한 노력의 일환으로 Google은 앱 사용자를 대신하여 분석/광고 제품에서 전송하는 User-Agent 헤더에 관한 표준화된 사양을 개발했습니다. 앱 사용자 에이전트는 다음 사양을 준수하기 위해 네이티브 코드에서 파생될 수 있습니다.

name version (os_and_version; locale; device; build; Proxy)

이러한 필드의 정의는 다음과 같습니다.

User-Agent 구성요소
name

분석/광고 제품의 이름입니다. (Google AdMob)

사용자 에이전트가 클라이언트 측에서 구성된 경우 name는 클라이언트 앱의 번들 ID여야 합니다.

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
version

분석/광고 제품의 버전입니다. (7.10.1)

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
os_and_version

앱이 실행되는 운영체제 및 운영체제 버전입니다. (Android 6.0 )

Android
String osAndVersion =
    "Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];
locale

밑줄로 구분된 두 글자 언어 및 국가 코드를 사용하는 기기의 IETF 언어 태그입니다. (en_US)

Android
String locale = Locale.getDefault();
iOS
NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]
device

분석/광고 제품을 실행하는 실제 기기의 이름입니다. (iPhone9,1)

Android
String device = Build.MODEL;
iOS
@import Darwin.sys.sysctl;

NSString *device(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("hw.machine",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}
build

'Build/' 다음에 운영체제의 빌드 번호가 나옵니다. (Build/13D15)

Android
String build = "Build/" + Build.ID;
iOS
@import Darwin.sys.sysctl;

NSString *build(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("kern.osversion",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}

앱 사용자 에이전트를 서버 측에서 구성할 때 앱 사용자 에이전트 끝에만 ; Proxy를 포함합니다. 앱 사용자 에이전트가 완전히 클라이언트 측에서 구성된 경우 ; Proxy를 제외합니다. 따라서 앱 사용자 에이전트는 다음과 같을 수 있습니다.

  • Android: AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
  • iOS: AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

전환 추적 요청 가이드

전환 추적 요청의 목적은 전환으로 추적하거나 리마케팅 목록을 채우는 데 사용해야 하는 앱 이벤트를 Google Ads에 알리고 이벤트에 앞선 클릭을 설명하는 메타데이터를 가져오는 것입니다.

모든 API 호출은 www.googleadservices.com 도메인으로 이루어집니다. 변환 요청은 다음 경로에서 HTTPS를 통해 이루어지는 POST 요청입니다. 

/pagead/conversion/app/version
여기서 version은 전환 추적 API의 의도된 버전입니다.

표준 앱 전환 요청에는 앱 전환 API v1.1의 다음 매개변수가 포함됩니다.

전환 추적 요청
dev_token

필수

위치: 쿼리

API 소비자에게 발급된 고유한 정적 개발자 토큰입니다.

Z_eErE4DkvcKjDM1OVE4c4
link_id

필수

위치: 쿼리

API 소비자의 개발자 토큰을 특정 앱에 바인딩하는 링크 식별자입니다.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

필수

위치: 쿼리

발생한 앱 이벤트의 이름입니다. 이 필드는 열거형이며 다음 값만 허용합니다.

 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

first_open 이벤트는 항상 설치 기여 분석을 위해 전송해야 하고 session_start 이벤트는 항상 세션 재기여 분석을 위해 전송해야 합니다. 네이티브 앱 스토어를 통해 이루어진 구매에는 in_app_purchase를 사용하고, 기타 모든 구매에는 ecommerce_purchase를 사용합니다.
app_event_name

특정 조건에서 필요

위치: 쿼리

app_event_type 필드에서 허용되지 않는 맞춤 앱 이벤트의 이름입니다. 이 필드에는 유니코드 문자 (UTF-8 인코딩 사용)가 1~64개 포함되어야 합니다. app_event_type이 맞춤인 경우 이 필드는 필수입니다.

level_achieved
Level Achieved

이 필드에는 app_event_type용으로 예약된 값이 포함되어서는 안 됩니다. 예약된 이벤트 이름을 사용하면 API에서 APP_EVENT_NAME_RESERVED_VALUE 오류를 반환합니다.
app_event_data

선택사항

위치: 본문

추가 리치 이벤트 데이터를 문자열 키를 값에 매핑하는 간단한 JSON 객체로 전달합니다. 허용되는 값은 문자열 및 문자열 배열입니다.

{"level": 5, "attempts": 20}
odm_info

iOS에서 통합 전환 측정을 사용하는 경우 필요

위치: 쿼리

Google 온디바이스 측정 (ODM): 이벤트 데이터 SDK에서 iOS 앱 설치 또는 재설치 시 캡처되는 info 쿼리 매개변수의 값입니다. 이 필드를 사용하면 iOS 앱 캠페인용 통합 전환 측정을 사용할 수 있습니다.

XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL
FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg
_CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23
id_type

필수

rdid 필드에 전달된 식별자 유형입니다.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

필수

위치: 쿼리

원시 기기 ID를 나타내는 유효한 UUID 문자열입니다.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

ATT 동의를 받지 않은 사용자의 기기 ID와 같이 기기 ID가 누락된 경우 모두 0으로 설정합니다.

00000000-0000-0000-0000-000000000000
ctry_c

필수

위치: 쿼리

전환이 발생한 국가를 나타내는 두 글자 ISO 국가 코드입니다.

이 필드는 iOS 및 Android에서 비사용자 수준 앱 전환 측정을 사용 설정하는 데 필요합니다.

US, IN
eea

특정 조건에서 필수

위치: 쿼리

EEA 범위입니다.

0: 이 사용자 및 전환에 유럽 규정이 적용되지 않습니다.

1: 이 사용자 및 전환에 유럽 규정이 적용됩니다. 예를 들어 사용자가 EEA에 거주하는 경우 관련 유럽 규정의 적용 범위에 해당합니다. 

*Required to be sent when the value is known.
ad_personalization

특정 조건에서 필수

위치: 쿼리

개인 맞춤 광고 플래그

0: 최종 사용자가 광고 개인 최적화 동의를 거부했습니다.

1: 최종 사용자가 광고 개인 최적화 동의를 부여했습니다. 

*Required to be sent when the value is known.
ad_user_data

특정 조건에서 필수

위치: 쿼리

광고 목적으로 사용자 데이터를 사용하는 것에 대한 동의 플래그

0: 광고 목적으로 사용자 수준 데이터를 Google에 전송하는 것에 대한 사용자의 동의가 거부됨

1: 광고 목적으로 사용자 수준 데이터를 Google에 전송하는 것에 대한 사용자의 동의가 부여됨 

*Required to be sent when the value is known.
lat

필수

위치: 쿼리

기기의 광고 추적 제한 상태입니다.

  • 0: 사용자가 광고 추적을 제한하지 않기로 선택했습니다.
  • 1: 사용자가 광고 추적을 제한하도록 선택했습니다.
app_version

필수

위치: 쿼리

앱의 현재 버전입니다. 다음과 같이 표준화해야 합니다.

Android

packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

iOS

[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]
 
1.2.4
os_version

필수

위치: 쿼리

앱의 호스트 OS의 현재 버전입니다. 다음과 같이 표준화해야 합니다.

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

필수

위치: 쿼리

이벤트를 측정한 SDK의 버전입니다. 이 값은 주로 디버깅에 사용되므로 SDK 출시와 함께 게시된 출시 버전을 정확하게 반영해야 합니다. 앱이 SDK를 사용하지 않는 경우 app_version와 동일한 값을 전달하세요.

1.9.5r6
timestamp

필수

위치: 쿼리

전환 이벤트가 발생한 UNIX 타임스탬프입니다(단위: 마이크로초).

1432681913.123456
fot

필수

위치: 쿼리

모든 후속 세션 및 설치 후 이벤트의 경우 해당 first_open의 UNIX 타임스탬프(단위: 초, 정밀도: 마이크로초)입니다.

1432681913.123456
value

선택사항

위치: 쿼리

이벤트의 금전적 가치입니다(있는 경우). 이 값은 항상 기계가 읽을 수 있는 부동 소수점 값으로 형식화되어야 하며, 소수점을 사용하여 값의 정수 부분과 소수 부분을 구분해야 합니다.

1.99
currency_code

특정 조건에서 필요

위치: 쿼리

value 매개변수의 ISO 4217 통화 코드입니다. value 매개변수가 제공되고 비어 있지 않은 경우 이 필드는 필수입니다.

USD
gclid

특정 조건에서 필요

위치: 쿼리

앱을 연 딥 링크 URL의 gclid 쿼리 매개변수 값입니다.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

특정 조건에서 필요

위치: 쿼리

Play Install Referrer API를 통해 install_referrer 값에서 캡처된 딥 링크 URL의 gclid 쿼리 매개변수 값입니다.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

특정 조건에서 필요

위치: 쿼리

rdid (advertisingid)가 not 사용 가능하거나 모든 zeroes가 있고 gclid 또는 market_referrer_gclid가 있는 시나리오에서 gclid 기반 기여 분석의 식별자입니다.

1
gbraid

특정 조건에서 필요

위치: 쿼리

앱을 연 딥 링크 URL을 통해 전송된 마지막으로 확인된 gbraid 값입니다. 앱에서 발생하는 향후 전환과 함께 전송될 수 있도록 앱에 캐시해야 합니다.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

특정 조건에서 필요

위치: 쿼리

광고 클릭 딥 링크 또는 자연 앱 세션을 식별하는 값입니다.

ad_click or organic
User-Agent

필수

위치: 헤더

이전 섹션에 정의된 앱 사용자 에이전트입니다.

AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
X-Forwarded-For

필수

위치: 헤더

이벤트가 측정된 기기의 공개 IPv4 또는 IPv6 주소입니다.

216.58.194.174

모든 요청은 HTTPS를 통해 전송되어야 합니다. HTTP를 통해 수신된 핑은 거부됩니다.

요청 본문이 비어 있는 경우 (app_event_data 페이로드에 리치 이벤트 데이터가 전달되지 않는 경우) 서버에서 요청에 Content-Length: 0 헤더를 명시적으로 설정하도록 요구합니다.

이벤트 데이터 인코딩

app_event_data 본문 매개변수의 경우 기본 데이터 유형에 다음 규칙을 사용하세요.

  • Float

    • 앱 현지화와 관계없이 점 문자를 소수점 구분 기호로 사용
    • 2자리 십진수 정밀도를 사용하여 금액을 나타냅니다(예: 2.99).
    • 지수 표기법(예: 2E+9)을 사용하지 마세요.
    • 숫자 그룹을 구분하는 데 쉼표 문자를 사용하지 마세요(예: 1,000,000).
    • 유효한 예:
      • -0.5
      • 2.99
      • 1000000.123

  • 정수

    • 소수 자리가 없는 정수 값만 전송하세요.
    • 숫자 그룹을 구분하는 데 쉼표 문자를 사용하지 마세요(예: 1,000,000). 사용하지 마세요.
    • 유효한 예:
      • 1000
      • -11
      • 0

  • 날짜

    • 날짜 형식: yyyy-mm-dd
      • yyyy = 4자리 연도(예: 2016)
      • mm = 두 자리 월(예: 9월의 경우 09)
      • dd = 두 자리 일(예: 23은 월의 23일)
    • 항상 위에 지정된 자릿수를 전송합니다. 예를 들어 월 5일의 dd 값을 전송하는 경우 05을 전송합니다.
    • 유효한 예:
      • "2016-09-23"
      • "1990-12-31"

  • 타임스탬프

    • 시간 형식: 마이크로초 정밀도로 UTC 시간대에 정의된 초 단위의 Unix/Epoch 타임스탬프
    • 유효한 예:
      • 1478713087(2016년 11월 9일 수요일 17시 38분 7초(GMT))
      • 1073513982.123000(2004년 1월 7일 수요일 22시 19분 42.123초 GMT)

  • 배열

    • 기본 값 (문자열, 숫자, 불리언)의 배열만 전송하세요.
    • 유효한 예:
      • [123, 456, 789]
      • ["abc"]

샘플 요청

통합 전환 측정을 위한 온디바이스 측정: 이벤트 데이터 SDK를 사용하는 첫 실행 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

통합 전환 측정을 위한 온디바이스 측정: 이벤트 데이터 SDK가 없는 첫 번째 열기 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

통합 전환 측정을 위한 온디바이스 측정: 이벤트 데이터 SDK를 사용하는 설치 후 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &&fot=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

온디바이스 측정: 이벤트 데이터 SDK가 없는 첫 번째 열기 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

ACAPI v1.1의 Android 비결정적 전환의 처음 열기 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=appsetid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &ctry_c=IN
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (android 11; en-GB; RMX2040; Build/_; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

맞춤이 아닌 이벤트 유형과 수익 정보가 포함된 유효한 전환 추적 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=0
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

맞춤이 아닌 이벤트 유형과 수익 정보가 있고 rdid (advertisingid)를 사용할 수 없는 유효한 전환 추적 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

유효한 세션 시작 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

딥 링크 example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M에서 시작된 세션의 유효한 세션 시작 재기여도 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

광고 사용자 데이터 동의가 부여되고 광고 개인 최적화가 거부된 EEA 사용자의 유효한 전환 추적 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=1
       &ad_personalization=0
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

전환 추적 응답 가이드

전환 추적 응답의 형식은 다음과 같습니다.

{
  "ad_events": [<ad event objects>],
  "errors": [<error strings>],
  "attributed": true|false
}

ad_events 및 errors 배열은 모두 비어 있을 수 있습니다.

오류는 머신이 읽을 수 있는 오류 코드(예: invalid_timestamp)여야 합니다.

오류 코드

  • invalid_timestamp - 요청에 유효한 타임스탬프가 없습니다.

  • eea_missing_or_invalid - 요청에 'eea' 필드가 설정되지 않았거나 유효하지 않습니다.

  • ad_user_data_missing - 'ad_user_data' 요청 필드가 설정되지 않았습니다. 'ad_user_data' 필드는 범위 내 모든 DMA 요청에 필수입니다.

  • ad_user_data_invalid - 'ad_user_data' 요청 값이 잘못되었습니다. 'ad_user_data' 필드는 범위 내 모든 DMA 요청에 필수입니다.

  • ad_personalization_missing_or_invalid - 요청에 'ad_personalization' 필드가 설정되지 않았거나 필드가 잘못되었습니다. 'ad_personalization' 필드는 범위 내 모든 DMA 요청에 필요합니다.

광고 이벤트는 앱 기여 분석의 핵심 객체이며 다음 속성을 포함합니다.

사용자 동의에 따라 달라지는 응답 동작에 관한 중요 참고사항:
전환에 광고 사용자 데이터 동의가 있고 사용자가 Google 사용자 설정 내에서 교차 사용 동의를 한 경우 Google Ads는 모든 CPS에서 단일 마지막 클릭으로 응답합니다. 사용자가 Google 사용자 설정 내에서 교차 사용 동의에 동의하지 않은 경우 Google Ads는 CPS별로 여러 개의 마지막 클릭으로 응답합니다.

전환에 사용자가 선택한 교차 사용 동의에 포함된 특정 CPS가 포함되지만 다른 CPS는 포함되지 않는 경우, Google Ads는 교차 사용 동의가 부여된 CPS에 대해 단일 마지막 클릭으로 응답하지만 교차 사용 동의가 부여되지 않은 CPS에 대해서는 CPS별로 여러 마지막 클릭으로 응답합니다.

전환 추적 응답
ad_event_id

항상 표시

문자열

ad_event_id는 광고 이벤트의 고유 식별자 역할을 합니다. 교차 네트워크 기여 분석 요청에서 재사용되며 디버깅 목적으로 로깅/보관해야 합니다.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

항상 표시

문자열

기여 분석에 사용되는 전환 측정항목입니다. 처음에는 하나의 전환 측정항목만 지원됩니다.

conversion
timestamp

항상 표시

숫자

광고 이벤트가 발생한 UNIX 타임스탬프입니다(단위: 마이크로초). 이 값은 마지막 클릭 기여 분석에 사용해야 합니다.

1432681913.123456
campaign_type

항상 표시

문자열

이 필드는 광고 이벤트를 생성한 캠페인 유형을 식별합니다. 가능한 값은 다음과 같습니다.

ACI
ACE
ACPRE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI는 설치 유도 앱 캠페인의 약자입니다. ACE는 참여 유도 앱 캠페인의 약자입니다.
campaign_id

항상 표시

숫자

광고 이벤트를 생성한 캠페인의 숫자 캠페인 ID입니다. 이 값은 고유성이 보장됩니다.

123456789
campaign_name

항상 표시

문자열

광고 이벤트를 생성한 캠페인의 광고주 정의 캠페인 이름입니다. 이 값은 고유성이 보장되지 않습니다.

Occasional Gamers (Video)
ad_type

항상 표시

문자열

광고 이벤트가 발생한 광고의 유형입니다. 이 값은 다음과 같이 다양한 유형의 인벤토리를 구분하는 데 사용할 수 있습니다.

앱 프로모션 
ClickToDownload
 앱 참여 
AppDeepLink
 앱 참여도 - 설치 후 계속 흐름 
AppDeepLinkContinue
 기타 값의 포괄 
Unknown
external_customer_id

항상 표시

숫자

광고 이벤트를 생성한 캠페인을 소유한 광고주의 광고주 식별자입니다. 이 값은 Google Ads 계정을 구분하는 데 사용할 수 있습니다.

123456789
location

항상 표시

숫자

광고 이벤트의 지리적 위치에 대한 위치 ID 코드입니다. 위치 코드를 해석하려면 Google Ads API 참조를 참고하세요.
network_type

항상 표시

문자열

이 필드는 광고 이벤트가 발생한 Google Ads 광고 네트워크를 식별합니다. 가능한 값은 다음과 같습니다.

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

campaign_type이 ACI 또는 ACE이고 network_type이 Display이면 null이 됩니다.

문자열

이 필드는 광고 이벤트가 발생한 Google Ads 광고 네트워크의 '하위 유형'을 식별합니다. 가능한 값은 기본 네트워크 유형에 따라 다릅니다.

일반 Google 검색 
GoogleSearch
 Google 검색 파트너 
SearchPartners

디스플레이

모바일 웹 게시자 
mGDN
 앱 게시자 
Google AdMob

YouTube

YouTube 동영상 네트워크 
YouTubeVideos
 YouTube 검색 네트워크 
YouTubeSearch
 동영상 파트너 
VideoPartners

GoogleTv

GoogleTV 동영상 네트워크 
GoogleTvVideos

교차 네트워크

실적 최대화 캠페인 교차 네트워크 
cross-network
video_id

network_type이 YouTube이고 campaign_type가 ACI 및 ACE이 아닌 경우에만 제공됩니다.

문자열

광고 이벤트와 연결된 YouTube 동영상 ID입니다.

dQw4w9WgXcQ
keyword

network_type이 Search이고 campaign_type가 ACI 및 ACE이 아닌 경우에만 제공됩니다.

문자열

광고 이벤트와 연결된 검색 키워드입니다.

+food +delivery
match_type

network_type이 Search이고 campaign_type가 ACI 및 ACE이 아닌 경우에만 제공됩니다.

문자열

검색 키워드의 검색 유형입니다.

완전일치검색 
e
 구문 
p
 확장 
b
placement

network_type이 Display이고 campaign_type가 ACI 및 ACE이 아닌 경우에만 제공됩니다.

문자열

광고 이벤트와 연결된 게재위치입니다.

mobileapp::1-343200656
ad_group_id

campaign_type이 Performance_Max이 아닌 경우에만 제공됩니다.

숫자

광고 이벤트와 함께 생성된 광고 그룹의 숫자 ID입니다. 이 값은 고유성이 보장됩니다.

이 필드는 딥 링크 기여 분석과 같이 결정론적으로 기여 분석되는 gbraid 기여 분석 광고 이벤트 (is_deterministic이 true임)에는 제공되지 않습니다.

123456789
ad_group_name

campaign_type가 ACI, ACE 또는 ACPRE인 경우에만 제공됩니다.

문자열

광고 이벤트를 생성한 광고 그룹의 광고주 정의 광고 그룹 이름입니다. 이 값은 고유성이 보장되지 않습니다.

이 필드는 딥 링크 기여 분석과 같이 결정론적으로 기여 분석되는 gbraid 기여 분석 광고 이벤트 (is_deterministic이 true임)에는 제공되지 않습니다.

My App AdGroup
asset_group_id

campaign_type이 Performance_Max인 경우에만 제공됩니다.

숫자

광고 이벤트를 생성한 애셋 그룹의 숫자 ID입니다. 이 값은 고유합니다.

123456789
creative_id

campaign_type가 ACI, ACE, ACPRE 또는 Performance_Max가 아닌 경우에만 제공됩니다.

숫자

광고 이벤트를 생성한 광고 소재 광고 단위의 숫자 ID입니다. 이 값은 고유성이 보장됩니다.

123456789
interaction_type

이 필드는 항상 engagement입니다.

문자열
is_deterministic

기여 분석 방법이 결정적인지 여부를 나타냅니다.

불리언

true, false
device_model

광고 이벤트를 생성한 기기 모델입니다.

문자열

sm-s936w, sm-3936w
os_version

광고 이벤트를 생성한 주요 OS 버전입니다.

문자열

14, 12
country

광고 이벤트를 생성한 두 글자 국가 코드입니다.

문자열

CA, US
city

광고 이벤트가 발생한 도시입니다.

문자열

san jose, london
region

광고 이벤트가 발생한 주 또는 도입니다.

문자열

california, british columbia

샘플 응답

확정적 전환의 응답 예시는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 1234567.898765
  }],
  "errors": [],
  "attributed": true
}

iOS 비결정적 전환의 응답 예시는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": false,
    },
    "device_info": {
        "device_model": "iphone12,3",
        "os_version": "14"
    },
    "timestamp": 1432681918.123456
    }],
  "errors": [],
  "attributed": true
}

Android 비결정적 전환의 응답 예시는 다음과 같습니다.

{
  "ad_events": [
    {
      "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
      "conversion_metric": "conversion",
      "interaction_type": "click",
      "campaign_type": "ACI",
      "campaign_id": 123456789,
      "campaign_name": "My App Campaign",
      "network_type": null,
      "network_subtype": null,
      "ad_group_id": 123456789,
      "ad_group_name": "My App AdGroup",
      "asset_group_id": null,
      "is_deterministic": false,
      "geo_info": {
        "city": "san jose",
        "country": "US",
        "region": "california"
      },
      "device_info": {
          "device_model": "sm-s926u",
          "os_version": "14"
      },
      "timestamp": 1432681918.123456
    },
    ],
    "errors": [],
    "warnings": []
  }

gbraid로 기여도가 부여된 iOS/Android 전환의 응답 예시는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "interaction_type": "engagement",
    "network_type": null,
    "ad_group_id": null,
    "ad_group_name": null,
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 0.000000
  }],
  "errors": [],
  "attributed": true,
  "warnings": [],
}

요청에 오류가 포함된 경우의 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [],
  "errors": ["INVALID_CURRENCY_CODE"],
  "attributed": false
}

부정적인 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [],
  "errors": [],
  "attributed": false
}

모든 전환 추적 요청에 대해 전환 추적 응답이 반환됩니다.

유니버설 앱 캠페인의 EEA 외 사용자에 대한 긍정적인 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

검색 캠페인에 대한 EEA 외 사용자의 긍정적인 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Search",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": "+space +birds",
    "match_type": "b",
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

디스플레이 캠페인의 비EEA 사용자에 대한 긍정적인 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Display",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "mGDN",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": "mobile-app::2-343200656",
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

YouTube 캠페인에 대한 EEA 외 사용자의 긍정적인 전환 추적 응답의 예는 다음과 같습니다.

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Video",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": "dQw4w9WgXcQ",
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


교차 네트워크 기여 분석 요청

Google Ads가 전환 추적 요청에 긍정적으로 응답하면 API 소비자는 마지막 클릭을 식별한 후 Google Ads에 교차 네트워크 기여 분석 결정을 알려야 합니다.

교차 네트워크 기여 분석 요청은 원래 전환 추적 요청과 동일하지만 요청 경로가 다음과 같습니다.

/pagead/conversion/app/1.1/cross_network

다음 두 가지 필수 매개변수가 추가되었습니다.

교차 네트워크 기여 분석 요청
ad_event_id

필수

위치: 쿼리

이전 요청의 기여 분석과 연결된 광고 이벤트의 ad_event_id 식별자입니다.
attributed

필수

위치: 쿼리

API 소비자가 전환에 대한 기여도를 Google Ads에 부여했는지 여부입니다. 0 또는 1.

유효한 교차 네트워크 기여 분석 요청의 예는 다음과 같습니다.

POST /pagead/conversion/app/1.1/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
       &attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

유효한 교차 네트워크 기여 분석 요청은 항상 응답 본문이 없는 일반 200 응답을 수신합니다.