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

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

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

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

השם של המכשיר הפיזי שבו מופעל מוצר הניתוח או מוצר הפרסום. (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

אופציונלי

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

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

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

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

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

הערך האחרון 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 ייפסלו.

שימו לב: אם גוף הבקשה ריק (במקרים שבהם לא מועברים נתוני אירוע מפורטים במטען הייעודי (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

דוגמה לבקשת פתיחה ראשונה ללא On Device Measurement: 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
       &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"]}}

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

דוגמה לבקשת 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
       &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

קוד מזהה המיקום של המיקום הגיאוגרפי של אירוע המודעה. כדי להבין את קודי המיקום, אפשר לעיין ב הפניית ה-API של Google Ads.
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
asset_group_id

הערך הזה מסופק רק אם campaign_type הוא Performance_Max.

number

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

123456789
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,
    "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": null,
    "ad_group_name": null,
    "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": null,
      "ad_group_name": null,
      "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",
    "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": null,
    "ad_group_name": "",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


בקשה לשיוך חוצה-פלטפורמות

כשמערכת Google Ads משיבה בחיוב לבקשת מעקב המרות, צרכן ה-API צריך להודיע ל-Google Ads על החלטת השיוך שלו בין רשתות אחרי זיהוי הקליק האחרון.

בקשת השיוך בין הרשתות זהה לבקשה המקורית למעקב המרות, אבל עם נתיב בקשה של:

/pagead/conversion/app/1.1/cross_network

והוספה של שני פרמטרים נדרשים:

בקשה לשיוך חוצה-פלטפורמות
ad_event_id

חובה

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

המזהה ad_event_id מאירוע המודעה שמשויך לשיוך בבקשה הקודמת.

הפונקציה
attributed

חובה

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

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

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