앱 사용자 에이전트
스팸을 근절하기 위한 광범위한 노력의 일환으로 앱 사용자를 대신하여 애널리틱스/광고 제품에서 전송하는 사용자 에이전트 헤더의 표준화된 사양을 개발했습니다. 앱 사용자 에이전트는 네이티브 코드에서 파생되어 다음 사양을 준수할 수 있습니다.
name version (os_and_version; locale; device; build; Proxy)
이 필드의 정의는 다음과 같습니다.
| 사용자 에이전트 구성요소 | |
|---|---|
| name | 분석/광고 제품의 이름입니다. ( 사용자 에이전트가 클라이언트 측에서 구성된 경우 Android// Specified by API consumer. iOS// Specified by API consumer. |
| version | 분석/광고 제품의 버전입니다.
( Android// Specified by API consumer. iOS// Specified by API consumer. |
| os_and_version | 앱이 실행되는 운영체제 및 운영체제 버전입니다. ( Android
String osAndVersion =
"Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
[UIDevice currentDevice];
NSString *osAndVersion =
[NSString
stringWithFormat:@"%@ %@",
[uid systemName],
[uid systemVersion]];
|
| locale | 두 자로 된 언어 및 국가 코드를 밑줄로 구분하여 사용하는 기기의 IETF 언어 태그입니다.
( AndroidString locale = Locale.getDefault(); iOS
NSString *locale =
[[NSLocale currentLocale]
localeIdentifier]
|
| device | 분석/광고 제품을 실행하는 실제 기기의 이름입니다.
( AndroidString 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/" 뒤에 운영체제의 빌드 번호가 옵니다.
( AndroidString 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의 의도된 버전입니다. 현재 유효한 버전은
1.0뿐입니다.
표준 앱 전환 요청에는 다음 매개변수가 포함됩니다.
| 전환 추적 요청 | |
|---|---|
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
|
app_event_name |
특정 조건에서 요구됨 위치: 쿼리
level_achieved Level Achieved 이 필드는 |
app_event_data |
선택사항 위치: 본문 추가 리치 이벤트 데이터를 단순한 JSON 객체 매핑 문자열 키로 값으로 전달합니다. 허용되는 값은 문자열 및 문자열 배열입니다.
{"level": 5, "attempts": 20}
|
rdid |
필수 위치: 쿼리 원시 기기 ID를 나타내는 유효한 UUID 문자열입니다. f10e1de2-e237-4f50-b6aa-843c45cc63d6 동의되지 않은 ATT 사용자의 기기 ID와 같은 기기 ID가 누락된 경우 모두 0으로 설정합니다. 00000000-0000-0000-0000-000000000000 |
id_type |
필수 위치: 쿼리
Androidadvertisingid iOSidfa |
lat |
필수 위치: 쿼리 기기의 광고 추적 제한 상태입니다.
|
app_version |
필수 위치: 쿼리 앱의 현재 버전입니다. 이 방법은 다음과 같이 표준화되어야 합니다. AndroidpackageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4 |
os_version |
필수 위치: 쿼리 앱 호스트 OS의 현재 버전입니다. 이는 다음과 같이 표준화해야 합니다. Androidandroid.os.Build.VERSION.RELEASE iOS[[UIDevice currentDevice] systemVersion] |
sdk_version |
필수 위치: 쿼리 이벤트를 측정한 SDK 버전입니다. 디버깅에 주로 사용되므로 SDK 출시와 함께 게시된 버전과 정확히 일치하는 출시 버전을 반영해야 합니다. 앱에서 SDK를 사용하지 않는 경우 1.9.5r6 |
timestamp |
필수 위치: 쿼리 전환 이벤트가 발생한 UNIX 타임스탬프로, 마이크로초 단위로 표시됩니다. 1432681913.123456 |
value |
선택사항 위치: 쿼리 이벤트의 금전적 가치입니다(있는 경우). 이 값은 항상 소수점을 사용하여 컴퓨터가 읽을 수 있는 부동 소수점 값으로 형식이 지정되어야 합니다. 이렇게 하면 값의 정수와 분수 부분이 분리됩니다. 1.99 |
currency_code |
특정 조건에서 요구됨 위치: 쿼리
USD |
gclid |
특정 조건에서 요구됨 위치: 쿼리 앱을 연 딥 링크 URL에서 가져온 Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
특정 조건에서 요구됨 위치: 쿼리 Play Install Referrer API를 통해 install_referrer 값에서 캡처된 딥 링크 URL의 BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
특정 조건에서 요구됨 위치: 쿼리 rdid (advertisingid)가 1 |
gbraid |
특정 조건에서 요구됨 위치: 쿼리 앱을 연 딥 링크 URL을 통해 전송된 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 페이로드에 리치 이벤트 데이터가 전달되지 않는 경우) Google 서버는 요청 시 Content-Length: 0 헤더를 명시적으로 설정해야 합니다.
샘플 요청
맞춤이 아닌 이벤트 유형 및 수익 정보가 포함된 유효한 전환 추적 요청의 예는 다음과 같습니다.
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=in_app_purchase
&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
×tamp=1432681913.123456
&value=1.99
¤cy_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
{"app_event_data":{"item_id":["Crayons","Markers"]}}
다음은 맞춤이 아닌 이벤트 유형과 rdid (advertisingid)를 사용할 수 없는 수익 정보가 포함된 유효한 전환 추적 요청의 예입니다.
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=in_app_purchase
&rdid=00000000-0000-0000-0000-000000000000
&id_type=advertisingid
&lat=1
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
&value=1.99
¤cy_code=USD
&market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
&gclid=Cj0KEQjw0dy4BRCuuL_e5M
&gclid_only_request=1
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.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=session_start
&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
×tamp=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
딥 링크 example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M에서 시작된 세션의 유효한 세션 시작 재기여 분석 요청의 예는 다음과 같습니다.
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=session_start
&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
×tamp=1432681913.123456
&gclid=Cj0KEQjw0dy4BRCuuL_e5M
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 본문 매개변수의 경우 기본 데이터 유형에 다음 규칙을 사용하세요.
부동 소수점 수
- 앱 현지화와는 별개로 소수점 구분 기호로 점 문자를 사용합니다.
- 2자리 십진수 정밀도를 사용하여 금전적 가치를 나타냅니다(예: 2.99).
- 지수 표기법 사용 안 함(예: 2E+9)
- 숫자 그룹을 구분할 때 쉼표 문자를 사용하지 마세요(예: 1,000,000).
- 유효한 예:
-0.52.991000000.123
정수
- 십진수가 없는 정수 값만 전송
- 숫자 그룹을 구분할 때 쉼표 문자를 사용하지 마세요(예: 1,000,000).
- 유효한 예:
1000-110
날짜
- 날짜 형식: yyyy-mm-dd
yyyy= 4자리 연도(예: 2016)mm= 2자리 월(예: 9월의 경우 09)dd= 2자리 일(예: 23일의 경우 23)
- 항상 위에 지정된 자릿수를 전송합니다. 예를 들어 월의 5번째 날에 dd 값을 전송하는 경우
05를 보내세요. - 유효한 예:
"2016-09-23""1990-12-31"
- 날짜 형식: yyyy-mm-dd
타임스탬프
- 시간 형식: 최대 마이크로초 단위의 정확도로 UTC 시간대로 정의된 Unix/Epoch 타임스탬프
- 유효한 예:
14787130872016년 11월 9일 수요일 17:38:07 GMT1073513982.123000: 2004년 1월 7일 수요일 22:19:42.123 GMT
배열
- 원시값의 배열 (문자열, 숫자 및 부울)만 전송
- 유효한 예:
[123, 456, 789]["abc"]
전환 추적 응답
전환 추적 응답의 형식은 다음과 같습니다.
{
"ad_events": [<ad event objects>],
"errors": [<error strings>],
"attributed": true|false
}
ad_events 및 errors 배열은 모두 비어 있을 수 있습니다.
오류는 컴퓨터가 읽을 수 있는 오류 코드(예: invalid_timestamp)일 것으로 예상됩니다.
광고 이벤트는 앱 기여 분석의 핵심 객체이며 다음과 같은 속성을 포함합니다.
| 전환 추적 응답 | |
|---|---|
ad_event_id |
항상 표시 문자열
Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
항상 표시 문자열 기여 분석에 사용되는 전환 측정항목입니다. 처음에는 하나의 전환 측정항목이 지원됩니다. conversion |
timestamp |
항상 표시 숫자 광고 이벤트가 발생한 UNIX 타임스탬프로, 마이크로초 단위로 표시됩니다. 이 값은 마지막 클릭 기여 분석에 사용해야 합니다. 1432681913.123456 |
campaign_type |
항상 표시 문자열 이 필드는 광고 이벤트를 생성한 캠페인 유형을 식별합니다. 가능한 값은 다음과 같습니다. ACI ACE 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 |
network_subtype |
문자열 이 필드는 광고 이벤트가 발생한 Google Ads 광고 네트워크의 '하위 유형'을 식별합니다. 가능한 값은 기본 네트워크 유형에 따라 다릅니다. 검색일반 Google 검색GoogleSearchGoogle 검색 파트너 SearchPartners 디스플레이모바일 웹 게시자mGDN앱 게시자 Google AdMob YouTubeYouTube 동영상 네트워크YouTubeVideosYouTube 검색 네트워크 YouTubeSearch동영상 파트너 VideoPartners |
video_id |
문자열 광고 이벤트와 연결된 YouTube 동영상 ID입니다. dQw4w9WgXcQ |
keyword |
문자열 광고 이벤트와 연결된 검색 키워드입니다. +food +delivery |
match_type |
문자열 검색 키워드의 검색 유형입니다. 일치e구문 p확장검색 b |
placement |
문자열 광고 이벤트와 연결된 게재위치입니다. mobileapp::1-343200656 |
ad_group_id |
항상 표시 숫자 광고 이벤트와 함께 생성된 광고그룹의 숫자 ID입니다. 이 값은 고유합니다. 123456789 |
ad_group_name |
문자열 광고 이벤트를 생성한 광고그룹의 광고주 정의 광고그룹 이름입니다. 이 값은 고유하지 않습니다. My App AdGroup |
creative_id |
숫자 광고 이벤트를 생성한 광고 소재 광고 단위의 숫자 ID입니다. 이 값은 고유합니다. 123456789 |
interaction_type |
이 입력란에는 항상 참여도가 포함됩니다. 문자열 |
샘플 응답
요청에 오류가 포함된 경우의 전환 추적 응답 예는 다음과 같습니다.
{
"ad_events": [],
"errors": ["INVALID_CURRENCY_CODE"],
"attributed": false
}
제외 전환 추적 응답의 예는 다음과 같습니다.
{
"ad_events": [],
"errors": [],
"attributed": false
}
모든 전환 추적 요청에 대한 전환 추적 응답이 반환됩니다.
유니버설 앱 캠페인에 대한 긍정적인 전환 추적의 예는 다음과 같습니다.
{
"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": null,
"ad_group_name": "",
"creative_id": null,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
검색 캠페인에 대한 긍정적인 전환 추적 응답의 예는 다음과 같습니다.
{
"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": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
디스플레이 캠페인에 대한 긍정적인 전환 추적 응답의 예는 다음과 같습니다.
{
"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": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
YouTube 캠페인에 대한 긍정적인 전환 추적의 예는 다음과 같습니다.
{
"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": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
교차 네트워크 기여 분석 요청
Google Ads에서 전환 추적 요청에 긍정적으로 응답하면 API 소비자가 마지막 클릭을 확인한 후 교차 네트워크 기여 분석 결정을 Google Ads에 알려야 합니다.
교차 네트워크 기여 분석 요청은 기존 전환 추적 요청과 같지만 요청 경로는 다음과 같습니다.
/pagead/conversion/app/1.0/cross_network
두 개의 필수 매개변수를 추가할 수 있습니다.
| 교차 네트워크 기여 분석 요청 | |
|---|---|
ad_event_id |
필수 위치: 쿼리 이전 요청의 기여 분석과 연결된 광고 이벤트의
|
attributed |
필수 위치: 쿼리 Google Ads API 전환에 의해 전환 기여도가 부여되었는지 여부를
나타냅니다. |
유효한 교차 네트워크 기여 분석 요청의 예는 다음과 같습니다.
POST /pagead/conversion/app/1.0/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
×tamp=1432681913.123456
&value=1.99
¤cy_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개를 수신합니다.