應用程式使用者代理程式
為防止垃圾內容而更加努力,我們為應用程式使用者代表數據分析/廣告產品傳送的 User-Agent 標頭已製定標準化的規格。應用程式 User-Agent 可以從原生程式碼取得,遵從下列規格:
name version (os_and_version; locale; device; build; Proxy)
這些欄位的定義如下:
User-Agent 元件 | |
---|---|
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 | 執行應用程式的作業系統和作業系統版本。( AndroidString osAndVersion = "Android " + Build.VERSION.RELEASE; iOSUIDevice *uid = [UIDevice currentDevice]; NSString *osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]]; |
locale | 裝置的 IETF 語言代碼標記,並使用雙字母語言和國家/地區代碼,並以底線分隔。( AndroidString locale = Locale.getDefault(); iOSNSString *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/&tt」),後面接著作業系統的版本號碼。( 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]; } |
建構應用程式 User-Agent 伺服器端時,才需要在應用程式 User-Agent 的結尾加入 ; Proxy
。如果應用程式 User-Agent 完全在用戶端上建構,請排除 ; Proxy
。因此,應用程式 User-Agent 可能是:
- 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 |
必要 位置:查詢 連結 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 如果缺少裝置 ID (例如來自 ATT 的未同意使用者裝置 ID),請將該 ID 設為零。 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 |
必要 位置:查詢 應用程式主機作業系統的目前版本。這應該標準化,如下所示。 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 |
在特定情況下為必填 位置:查詢 開啟應用程式的深層連結網址 Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
在特定情況下為必填 位置:查詢 透過 Play Install Referrer API 從 install_referrer 值擷取的深層連結 BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
在特定情況下為必填 位置:查詢 在 rdid (advertisingid) 可用 1 |
gbraid |
在特定情況下為必填 位置:查詢 上次發現透過深層連結開啟應用程式的 ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O |
app_open_source |
在特定情況下為必填 位置:查詢 用來識別廣告點擊深層連結或自然應用程式工作階段的值。 ad_click or organic |
User-Agent |
必要 位置:Header 應用程式使用者代理程式,如上一節所述。 AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M) |
X-Forwarded-For |
必要 位置:Header 評估事件的裝置公開 IPv4 或 IPv6 位址。 216.58.194.174 |
所有要求都必須透過 HTTPS 傳送。透過 HTTP 收到的連線偵測 (ping) 會遭到拒絕。
請注意,如果要求主體為空白 (如果 app_event_data
酬載未傳遞豐富的事件資料),我們的伺服器會要求您明確設定要求中的 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"]}}
以下非有效轉換追蹤要求範例,其中包含非自訂事件類型和收益資訊 (不適用 ID (adid)) 無效:
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.99
- 請勿使用指數標記法,例如 2E+9。
- 請勿使用半形逗號分隔各組數字,例如 1,000,000
- 有效範例:
-0.5
2.99
1000000.123
整數
- 只傳送不含整數的整數值
- 請勿使用半形逗號分隔各組數字,例如 1,000,000
- 有效範例:
1000
-11
0
日期
- 日期格式:yyyy-mm-dd
yyyy
= 4 位數字的年份,例如 2016mm
= 2 位數字,例如 09dd
= 2 位數字,例如當月 23 日為 23
- 一律傳送以上指定的位數,例如在當月 5 日傳送 dd 的值時,請傳送
05
。 - 有效範例:
"2016-09-23"
"1990-12-31"
- 日期格式:yyyy-mm-dd
時間戳記
- 時間格式:以 UTC 時區定義的 Unix/Epoch 時間戳記 (精確度高達微秒)
- 有效範例:
- 週三,
1478713087
2016 年 11 月 9 日晚上 17:38:07 - 週三,
1073513982.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 |
一律顯示 數字 產生廣告事件的廣告活動所屬廣告客戶的廣告客戶 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 回應。