סוכן משתמש של האפליקציה
במסגרת המאמצים הנרחבים שלנו למאבק בספאם, פיתחנו מפרט סטנדרטי של כותרת User-Agent שנשלחת על ידי מוצר ניתוח נתונים או מוצר פרסום בשם משתמש אפליקציה. אפשר לגזור את User-Agent של האפליקציה מקוד Native כדי לעמוד בדרישות המפרט הבאות:
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 | מערכת ההפעלה וגרסת מערכת ההפעלה שבהן האפליקציה פועלת. ( 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/ ואחריו מספר ה-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 בסוף User-Agent של האפליקציה כשיוצרים את User-Agent של האפליקציה בצד השרת. אם סוכן המשתמש של האפליקציה נוצר כולו בצד הלקוח, צריך להחריג את ; 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. בקשות להמרות הן בקשות POST דרך HTTPS בנתיב הבא:
/pagead/conversion/app/version
בקשת המרה רגילה באפליקציה תכיל את הפרמטרים הבאים עבור App Conversion 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 תמיד צריך לשלוח את האירוע |
app_event_name |
חובה בתנאים מסוימים מיקום: שאילתה השם של כל אירוע מותאם אישית באפליקציה שלא מתקבל בשדה level_achieved Level Achieved השדה הזה לא יכול להכיל אף אחד מהערכים ששמורים ל- |
app_event_data |
אופציונלי מיקום: גוף מעבירים נתונים נוספים של אירועים מתקדמים כאובייקט JSON פשוט שממפה מחרוזות של מפתחות לערכים. הערכים הקבילים הם מחרוזות ומערכים של מחרוזות. {"level": 5, "attempts": 20} |
odm_info |
נדרש כשמשתמשים במעקב המרות משולב ב-iOS מיקום: שאילתה הערך של פרמטר השאילתה XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg _CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23 |
id_type |
חובה סוג המזהה שמועבר בשדה Androidadvertisingid appsetid iOSidfa idfv |
rdid |
חובה מיקום: שאילתה מחרוזת UUID תקינה שמייצגת את מזהה המכשיר הגולמי. f10e1de2-e237-4f50-b6aa-843c45cc63d6 אם מזהה המכשיר חסר, למשל מזהה מכשיר של משתמש שלא הביע הסכמה ל-ATT, צריך להגדיר אותו כ-0. 00000000-0000-0000-0000-000000000000 |
ctry_c |
חובה מיקום: שאילתה קוד מדינה בן 2 אותיות לפי תקן ISO שמציין את המדינה שבה התרחשה ההמרה. השדה הזה נדרש כדי להפעיל מעקב המרות באפליקציה ברמה שאינה ברמת המשתמש ב-iOS וב-Android. US, IN |
eea |
חובה בתנאים מסוימים מיקום: שאילתה היקף האזור הכלכלי האירופי.
|
ad_personalization |
חובה בתנאים מסוימים מיקום: שאילתה הסימונים למודעות בהתאמה אישית
|
ad_user_data |
חובה בתנאים מסוימים מיקום: שאילתה אות ההסכמה לשימוש בנתוני משתמשים למטרות פרסום
|
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 |
fot |
חובה מיקום: שאילתה חותמת הזמן של UNIX מהאירוע 1432681913.123456 |
value |
אופציונלי מיקום: שאילתה הערך הכספי של האירוע, אם יש כזה. הערך הזה תמיד צריך להיות בפורמט של מספר עשרוני שניתן לקריאה על ידי מכונה, עם נקודה עשרונית שמפרידה בין החלק השלם לחלק השברי של הערך. 1.99 |
currency_code |
חובה בתנאים מסוימים מיקום: שאילתה קוד המטבע לפי תקן ISO 4217 של הפרמטר USD |
gclid |
חובה בתנאים מסוימים מיקום: שאילתה הערך של פרמטר השאילתה Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
חובה בתנאים מסוימים מיקום: שאילתה הערך של פרמטר השאילתה BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
חובה בתנאים מסוימים מיקום: שאילתה מזהה לשיוך (Attribution) מבוסס 1 |
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 body, צריך להשתמש במוסכמות הבאות עבור סוגי נתונים פרימיטיביים:
Float
- שימוש בנקודה כמפריד עשרוני ללא קשר ללוקליזציה של האפליקציה
- כדי לייצג ערכים כספיים, צריך להשתמש בנקודה עשרונית עם שתי ספרות. לדוגמה: 2.99
- אסור להשתמש בסימון מדעי, למשל 2E+9
- אין להשתמש בפסיק כדי להפריד בין קבוצות של ספרות, למשל: 1,000,000
- דוגמאות לערכים תקינים:
-0.52.991000000.123
Integer
- אפשר לשלוח רק ערכים של מספרים שלמים ללא ספרות עשרוניות
- אין להשתמש בפסיק כדי להפריד בין קבוצות של ספרות, למשל 1,000,000
- דוגמאות לערכים תקינים:
1000-110
תאריך
- פורמט התאריך: yyyy-mm-dd
-
yyyy= שנה בארבע ספרות, למשל 2016 -
mm= חודש בשתי ספרות, למשל 09 לספטמבר -
dd= היום בשתי ספרות, למשל 23 ליום ה-23 בחודש
-
- תמיד שולחים את מספר הספרות שצוין למעלה, לדוגמה, אם שולחים את הערך של dd ליום החמישי בחודש, שולחים
05. - דוגמאות לערכים תקינים:
"2016-09-23""1990-12-31"
- פורמט התאריך: yyyy-mm-dd
חותמת זמן
- פורמט זמן: חותמת זמן של מערכת Unix בשניות, מוגדרת באזור הזמן UTC עם דיוק של מיקרו-שניות
- דוגמאות לערכים תקינים:
-
1478713087 Wed, 09 Nov 2016 17:38:07 GMT -
1073513982.123000for Wed, 07 Jan 2004 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
×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דוגמה לבקשת פתיחה ראשונה ללא SDK למדידת המרות משולבת: Event Data SDK for Integrated Conversion Measurement:
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
×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דוגמה לבקשה אחרי התקנה עם On Device Measurement: Event Data SDK for Integrated Conversion Measurement:
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
×tamp=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דוגמה לבקשת פתיחה ראשונה ללא מדידה במכשיר: Event Data 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
×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דוגמה לבקשת פתיחה ראשונה להמרה לא דטרמיניסטית ב-Android ב-ACAPI v1.1:
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
×tamp=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
×tamp=1432681913.123456
&value=1.99
¤cy_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"]}}דוגמה לבקשת מעקב המרות תקינה עם סוג אירוע לא מותאם אישית ופרטי הכנסות שבהם מזהה המכשיר לפרסום (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
×tamp=1432681913.123456
&value=1.99
¤cy_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
×tamp=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דוגמה לבקשת session start reattribution תקפה לסשן שהתחיל מקישור העומק 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
×tamp=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
×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מדריך לתגובות של מעקב המרות
התגובה של מעקב ההמרות היא בפורמט הבא:
{
"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 הוא שדה חובה בכל הבקשות שקשורות לאזורי שוק ייעודיים.
אירועים שקשורים למודעות הם אובייקטי הליבה של שיוך (Attribution) באפליקציות, והם יכללו את המאפיינים הבאים.
הערות חשובות לגבי התנהגות התגובה בהתאם להסכמת המשתמש:
אם ההמרה כוללת הסכמה לשימוש בנתוני משתמשים לצורכי מודעות והמשתמש הביע הסכמה לשימוש חוזר בנתונים
בהגדרות המשתמש שלו ב-Google, מערכת Google Ads תגיב עם קליק אחרון יחיד בכל מערכות ה-CPS שלה. אם המשתמש לא הביע הסכמה לשימוש חוצה בהגדרות המשתמש שלו ב-Google, מערכת Google Ads תגיב עם כמה קליקים אחרונים, על בסיס עלות לקליק.
אם ההמרה כוללת שירותי CPS מסוימים שהמשתמש אישר להשתמש בהם למטרות שונות, אבל לא שירותי CPS אחרים, מערכת Google Ads תגיב בקליק אחרון יחיד על שירותי ה-CPS שהמשתמש אישר להשתמש בהם למטרות שונות, אבל עם כמה קליקים אחרונים, על בסיס כל שירות CPS, עבור שירותי ה-CPS שהמשתמש לא אישר להשתמש בהם למטרות שונות.
| תגובה של מעקב המרות | |
|---|---|
ad_event_id |
מוצג תמיד מחרוזת Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
מוצג תמיד מחרוזת מדד ההמרה שמשמש לשיוך. בתחילה נתמוך במדד המרה אחד. conversion |
timestamp |
מוצג תמיד number חותמת הזמן של מערכת UNIX שבה התרחש אירוע מודעה, בשניות עם דיוק של מיקרו-שניות. הערך הזה צריך לשמש לשיוך לקליק האחרון. 1432681913.123456 |
campaign_type |
מוצג תמיד מחרוזת בשדה הזה יצוין סוג הקמפיין שיצר את אירוע המודעה. אלה הערכים האפשריים. ACI ACE ACPRE Search Display Video Shopping Hotel Performance_Max Other ACI הוא קיצור של App Campaign for Install (קמפיין להתקנת אפליקציה). ACE הוא קיצור של App Campaigns for Engagement (קמפיינים לעידוד השימוש באפליקציות). |
campaign_id |
מוצג תמיד number מזהה הקמפיין המספרי של הקמפיין שהניב את אירוע מודעה. הערך הזה מובטח להיות ייחודי. 123456789 |
campaign_name |
מוצג תמיד מחרוזת שם הקמפיין שהוגדר על ידי המפרסם ושייך לקמפיין שיצר את אירוע המודעה. אין ערובה לכך שהערך הזה יהיה ייחודי. Occasional Gamers (Video) |
ad_type |
מוצג תמיד מחרוזת סוג המודעה שהובילה לאירוע המודעה. אפשר להשתמש בערך הזה כדי להבחין בין סוגים שונים של מלאי שטחי פרסום, באופן הבא. קידום אפליקציותClickToDownload AppDeepLink AppDeepLinkContinue Unknown |
external_customer_id |
מוצג תמיד number מזהה המפרסם של המפרסם שהוא הבעלים של הקמפיין שיצר את אירוע המודעה. אפשר להשתמש בערך הזה כדי להבדיל בין חשבונות Google Ads. 123456789 |
location |
מוצג תמיד number קוד מזהה המיקום של המיקום הגיאוגרפי שבו התרחש אירוע מודעה. כדי להבין את קודי המיקום, אפשר לעיין ב הפניה ל-Google Ads API. |
network_type |
מוצג תמיד מחרוזת בשדה הזה יצוין שם רשת הפרסום של Google Ads שבה התרחש אירוע המודעה. אלה הערכים האפשריים. Search Display YouTube GoogleTv cross-network |
network_subtype |
הערך יהיה מחרוזת בשדה הזה יצוין ה'סוג המשנה' של רשת הפרסום של Google Ads שבה התרחש אירוע מודעה. הערכים האפשריים משתנים בהתאם לסוג הרשת העיקרית. חיפושחיפוש Google רגילGoogleSearch SearchPartners רשת המדיהבעלי תוכן דיגיטלי באתרים לניידmGDN Google AdMob YouTubeרשת סרטוני YouTubeYouTubeVideos YouTubeSearch VideoPartners GoogleTvרשת הסרטונים של GoogleTVGoogleTvVideos ברשת אחרתקמפיינים למיקסום הביצועים ברשתות שונותcross-network |
video_id |
הערך הזה מסופק רק אם הערך של מחרוזת מזהה הסרטון ב-YouTube שמשויך לאירוע מודעה. dQw4w9WgXcQ |
keyword |
הערך הזה מסופק רק אם הערך של מחרוזת מילת המפתח לרשת החיפוש שמשויכת לאירוע מודעה. +food +delivery |
match_type |
הערך הזה מסופק רק אם הערך של מחרוזת סוג ההתאמה של מילות מפתח לרשת החיפוש. מדויקתe p b |
placement |
הערך הזה מסופק רק אם הערך של מחרוזת מיקום המודעה שמשויך לאירוע שקשור למודעה. mobileapp::1-343200656 |
ad_group_id |
הערך הזה מסופק רק אם הערך של number המזהה המספרי של קבוצת המודעות שהפיקה את אירוע המודעה. הערך הזה מובטח כייחודי. השדה הזה לא מסופק לאירועים של מודעות שמשויכים באמצעות gbraid ושיוכם נקבע באופן דטרמיניסטי ( 123456789 |
ad_group_name |
הערך הזה מסופק רק אם הערך של מחרוזת השם של קבוצת המודעות שהוגדר על ידי המפרסם, שאליה משויך אירוע המודעה. אין ערובה לכך שהערך הזה יהיה ייחודי. השדה הזה לא מסופק לאירועים של מודעות שמשויכים באמצעות gbraid ושיוכם נקבע באופן דטרמיניסטי ( My App AdGroup |
asset_group_id |
הערך הזה מסופק רק אם number המזהה המספרי של קבוצת הנכסים שיצרה את אירוע המודעה. הערך הזה ייחודי. 123456789 |
creative_id |
המאפיין הזה מסופק רק אם הערך של number המזהה המספרי של יחידת המודעות הקריאייטיבית שיצרה את אירוע המודעה. הערך הזה מובטח כייחודי. 123456789 |
interaction_type |
הערך בשדה הזה תמיד יהיה 'מעורבות'. מחרוזת |
is_deterministic |
השדה מציין אם שיטת השיוך היא דטרמיניסטית או לא. בוליאני true, false |
device_model |
דגם המכשיר שיצר את אירוע המודעה. מחרוזת sm-s936w, sm-3936w |
os_version |
הגרסה הראשית של מערכת ההפעלה שיצרה את אירוע המודעה. מחרוזת 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": []
}דוגמה לתשובה להמרה ב-iOS או ב-Android שמשויכת ל-gbraid:
{
"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
}תגובה של מעקב המרות תוחזר לכל הבקשות של מעקב המרות.
דוגמה לתשובה חיובית למעקב המרות של משתמש שלא נמצא באזור הכלכלי האירופי בקמפיין לקידום אפליקציות:
{
"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": []
}דוגמה לתגובה חיובית של מעקב המרות לגבי משתמש שלא נמצא באזור הכלכלי האירופי בקמפיין לרשת החיפוש:
{
"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": []
}דוגמה לתשובה חיובית של מעקב המרות עבור משתמש שלא נמצא באזור הכלכלי האירופי בקמפיין לרשת המדיה:
{
"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:
{
"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": []
}דוגמה לתגובה של מעקב המרות עם שיוך, שבה ההמרה משויכת לאינטראקציות עם מודעות ב-Play ובחיפוש Google, אבל הסכמה לשימוש משותף לפי סעיף 5(2)(ב) + 5(2)(ג) נדחית בין מערכות ה-CPS של Play וחיפוש Google:
{
"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
}דוגמה לתגובה של מעקב המרות עם שיוך, שבה ההמרה משויכת גם לאינטראקציות עם מודעות ב-Play ובחיפוש Google, וגם להסכמה לשימוש חוצה גבולות 5(2)(ב) + 5(2)(ג) שהתקבלה בין מערכות ה-CPS של Play וחיפוש Google, דומה להתנהגות ההמרה הנוכחית:
{
"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
}דוגמה לתגובה של מעקב המרות עם ייחוס, שבה ההמרה משויכת לאינטראקציות עם מודעות ב-Play, בחיפוש וב-YouTube, והסכמת השימוש הצולב לפי סעיף 5(2)(b) + 5(2)(c) מתקבלת בין מערכות ה-CPS של Play ושל חיפוש Google, אבל נדחית במערכת ה-CPS של YouTube:
{
"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 |
חובה מיקום: שאילתה המזהה |
attributed |
חובה מיקום: שאילתה האם Google Ads קיבל קרדיט על ההמרה על ידי צרכן ה-API. |
דוגמה לבקשה תקינה לשיוך (Attribution) חוצה-פלטפורמות:
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
×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 ללא גוף תגובה.