מעקב המרות באפליקציות ורימרקטינג – מפרט בקשה/תגובה

סוכן משתמש של האפליקציה

כחלק מהמאמצים הרחבים יותר שלנו למאבק בספאם, פיתחנו מפרט סטנדרטי של כותרת User-Agent שנשלחת על ידי מוצר של Analytics או של Google Ads בשם משתמש באפליקציה. אפשר לגזור את User-Agent של האפליקציה מקוד מקורי כדי לעמוד במפרט הבא:

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

ההגדרה של השדות האלה היא כדלקמן:

רכיבים של סוכן משתמש
name

השם של מוצר הניתוח או הפרסום. (Google AdMob)

הערה: אם סוכן המשתמש נוצר בצד הלקוח, הערך name צריך להיות מזהה החבילה של אפליקציית הלקוח.

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

השם של המכשיר הפיזי שבו פועל המוצר של Analytics או של Google Ads. (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 של מערכת ההפעלה. (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. בקשות להמרות הן בקשות POST דרך HTTPS בנתיב הבא: 

/pagead/conversion/app/version
כאשר version היא הגרסה הרצויה של Conversion API.

בקשת המרה רגילה באפליקציה תכיל את הפרמטרים הבאים עבור 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

האירוע first_open צריך להישלח תמיד לצורך שיוך של התקנות, והאירוע session_start צריך להישלח תמיד לצורך שיוך מחדש של סשנים. משתמשים ב-in_app_purchase לרכישות שבוצעו דרך חנות האפליקציות המקורית, וב-ecommerce_purchase לכל הרכישות האחרות.
app_event_name

חובה בתנאים מסוימים

מיקום: שאילתה

השם של כל אירוע מותאם אישית באפליקציה שלא מתקבל בשדה app_event_type. השדה הזה צריך להכיל 1 עד 64 תווים ב-Unicode (בקידוד UTF-8). חובה למלא את השדה הזה אם 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

מיקום: שאילתה

הערך של פרמטר השאילתה info שתועד במהלך התקנה או התקנה מחדש של אפליקציית iOS מ-Google On Device Measurement ‏ (ODM): Event Data SDK. השדה הזה מאפשר מעקב המרות משולב בקמפיינים לקידום אפליקציות ל-iOS.

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

חובה

סוג המזהה שמועבר בשדה rdid.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

חובה

מיקום: שאילתה

מחרוזת UUID תקינה שמייצגת את מזהה המכשיר הגולמי.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

אם מזהה המכשיר חסר, למשל מזהה מכשיר ממשתמש שלא הביע הסכמה ל-ATT, צריך להגדיר אותו כ-0.

00000000-0000-0000-0000-000000000000
ctry_c

חובה

מיקום: שאילתה

קוד מדינה בן שתי אותיות על פי תקן ISO שמציין את המדינה שממנה הגיעה ההמרה.

השדה הזה נדרש כדי להפעיל מעקב המרות באפליקציה ברמה שאינה ברמת המשתמש ב-iOS וב-Android.

US, IN
eea

חובה בתנאים מסוימים

מיקום: שאילתה

היקף ההרשאות EEA.

0: התקנות האירופאיות לא חלות על המשתמש וההמרה האלה

1: התקנות האירופאיות חלות על המשתמש וההמרה האלה. לדוגמה, אם משתמש נמצא באזור הכלכלי האירופי, הוא נכלל בהיקף של התקנות האירופאיות הרלוונטיות. 

*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

חובה

מיקום: שאילתה

הגרסה הנוכחית של מערכת ההפעלה המארחת של האפליקציה. הפורמט צריך להיות אחיד כמו בדוגמה הבאה.

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

חובה

מיקום: שאילתה

חותמת הזמן של UNIX מהאירוע התואם first_open בשניות, עם דיוק של מיקרו-שניות לכל הסשנים הבאים ולאירועים אחרי ההתקנה.

1432681913.123456
value

אופציונלי

מיקום: שאילתה

הערך הכספי של האירוע, אם יש כזה. הערך הזה תמיד צריך להיות בפורמט של ערך נקודה צפה שניתן לקריאה על ידי מכונה, עם נקודה עשרונית שמפרידה בין החלק השלם לחלק השברי של הערך.

1.99
currency_code

חובה בתנאים מסוימים

מיקום: שאילתה

קוד המטבע לפי תקן ISO 4217 של הפרמטר value. חובה למלא את השדה הזה אם הפרמטר value צוין ולא ריק.

USD
gclid

חובה בתנאים מסוימים

מיקום: שאילתה

הערך של פרמטר השאילתה gclid מכתובת URL של קישור עומק שפתח את האפליקציה.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

חובה בתנאים מסוימים

מיקום: שאילתה

הערך של פרמטר השאילתה gclid מכתובת URL של קישור עומק שמתקבל מהערך install_referrer באמצעות Play Install Referrer API.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

חובה בתנאים מסוימים

מיקום: שאילתה

מזהה לשיוך (Attribution) מבוסס gclid בתרחישים שבהם not (advertisingid) זמין או כל zeroes וגם gclid או market_referrer_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 ייפסלו.

שימו לב: אם גוף הבקשה ריק (במקרים שבהם לא מועברים נתונים מפורטים של אירועים במטען הייעודי (payload) של app_event_data), השרת שלנו דורש להגדיר במפורש את הכותרת Content-Length: 0 בבקשה.

קידוד נתוני אירועים

לפרמטר הגוף app_event_data, צריך להשתמש במוסכמות הבאות עבור סוגי נתונים פרימיטיביים:

  • Float

    • שימוש בנקודה כמפריד עשרוני ללא קשר ללוקליזציה של האפליקציה
    • כדי לייצג ערכים כספיים, צריך להשתמש בנקודה עשרונית עם שתי ספרות. למשל: 2.99
    • אסור להשתמש בסימון אקספוננציאלי, למשל 2E+9
    • אסור להשתמש בפסיק כדי להפריד בין קבוצות של ספרות, למשל: 1,000,000
    • דוגמאות לערכים תקינים:
      • -0.5
      • 2.99
      • 1000000.123

  • Integer

    • שולחים רק ערכים של מספרים שלמים ללא ספרות עשרוניות
    • אסור להשתמש בפסיק כדי להפריד בין קבוצות של ספרות, למשל: 1,000,000
    • דוגמאות לערכים תקינים:
      • 1000
      • -11
      • 0

  • ‫תאריך

    • פורמט התאריך: yyyy-mm-dd
      • ‫yyyy = שנה בארבע ספרות, לדוגמה 2016
      • ‫mm = חודש בן שתי ספרות, למשל 09 לספטמבר
      • ‫dd = יום בשתי ספרות, למשל 23 ליום ה-23 בחודש
    • תמיד שולחים את מספר הספרות שצוין למעלה. לדוגמה, אם שולחים את הערך של dd ליום החמישי בחודש, שולחים 05.
    • דוגמאות לערכים תקינים:
      • "2016-09-23"
      • "1990-12-31"

  • חותמת זמן

    • פורמט זמן: חותמת זמן של מערכת Unix/Epoch בשניות, שמוגדרת באזור הזמן UTC עם דיוק של מיקרו-שניות
    • דוגמאות לערכים תקינים:
      • ‫1478713087 Wed, 09 Nov 2016 17:38:07 GMT
      • ‫1073513982.123000 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
       &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

דוגמה לבקשת פתיחה ראשונה ללא מדידה במכשיר: 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
       &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

דוגמה לבקשה אחרי התקנה עם 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
       &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

דוגמה לבקשת פתיחה ראשונה להמרה לא דטרמיניסטית ב-Android ב-ACAPI גרסה 1.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
       &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.

אירועים שקשורים למודעות הם האובייקטים המרכזיים בשיוך (Attribution) באפליקציות, והם יכללו את המאפיינים הבאים.

הערות חשובות לגבי התנהגות התגובה בהתאם להסכמת המשתמש:
אם ההמרה כוללת הסכמה לשימוש בנתוני משתמשים לצורכי מודעות, והמשתמש הביע הסכמה לשימוש חוצה במסגרת הגדרות המשתמש שלו ב-Google, מערכת Google Ads תגיב בלחיצה אחרונה אחת בכל מערכות ה-CPS שלה. אם המשתמש לא הביע הסכמה לשימוש חוצה בהגדרות המשתמש שלו ב-Google, מערכת Google Ads תגיב עם כמה קליקים אחרונים, על בסיס עלות להמרה.

אם ההמרה כוללת כמה CPS שהמשתמש אישר להם שימוש משותף אבל לא אחרים, Google Ads יגיב עם קליק אחרון יחיד בכל ה-CPS שהמשתמש אישר להם שימוש משותף, אבל עם כמה קליקים אחרונים, על בסיס כל CPS, עבור ה-CPS שהמשתמש לא אישר להם שימוש משותף.

תגובה של מעקב המרות
ad_event_id

מוצג תמיד

מחרוזת

‫ad_event_id משמש כמזהה ייחודי לאירועים שקשורים למודעות. הוא משמש שוב בבקשת השיוך חוצה-פלטפורמות, וצריך לתעד אותו או לשמור אותו למטרות ניפוי באגים.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

מוצג תמיד

מחרוזת

מדד ההמרה שמשמש לשיוך (Attribution). בתחילה נתמוך במדד המרה אחד.

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 הוא קיצור של קמפיינים לעידוד השימוש באפליקציה.
campaign_id

מוצג תמיד

number

מזהה הקמפיין המספרי של הקמפיין שיצר את אירוע הצפייה במודעה. הערך הזה מובטח להיות ייחודי.

123456789
campaign_name

מוצג תמיד

מחרוזת

שם הקמפיין שהוגדר על ידי המפרסם ושייך לקמפיין שיצר את אירוע הצפייה במודעה. הערך הזה לא בהכרח ייחודי.

Occasional Gamers (Video)
ad_type

מוצג תמיד

מחרוזת

סוג המודעה שהובילה לאירוע המודעה. אפשר להשתמש בערך הזה כדי להבחין בין סוגים שונים של מלאי שטחי פרסום, באופן הבא.

קידום אפליקציות 
ClickToDownload
 קמפיינים לעידוד השימוש באפליקציה 
AppDeepLink
 הגדלת כמות האינטראקציות עם האפליקציה – תהליך ההתקנה וההמשך 
AppDeepLinkContinue
 Catch-all for other values 
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

הערך יהיה null אם הערך של campaign_type הוא ACI או ACE והערך של network_type הוא Display.

מחרוזת

בשדה הזה יצוין ה'סוג המשני' של רשת הפרסום של 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 שמשויך לאירוע שקשור למודעה.

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.

number

המזהה המספרי של קבוצת המודעות שיצרה את אירוע הצפייה במודעה. הערך הזה מובטח להיות ייחודי.

123456789
ad_group_name

המאפיין הזה מסופק רק אם הערך של campaign_type הוא ACI, ACE או ACPRE.

מחרוזת

השם של קבוצת המודעות שהוגדר על ידי המפרסם, שאליה משויך אירוע המודעה. הערך הזה לא בהכרח ייחודי.

My App AdGroup
creative_id

המאפיין הזה מסופק רק אם הערך של campaign_type הוא לא ACI, ACE, ACPRE או Performance_Max.

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": null,
    "ad_group_name": 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": null,
    "ad_group_name": 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": null,
      "ad_group_name": 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",
    "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": null,
    "ad_group_name": "",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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

חובה

מיקום: שאילתה

האם Google Ads קיבל קרדיט על ההמרה על ידי צרכן ה-API. 0 או 1.

דוגמה לבקשת שיוך (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
       &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 ללא גוף תגובה.