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

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

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

השם של המכשיר הפיזי שבו פועל המוצר של 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. בשלב הזה, הגרסה התקפה היחידה היא 1.0.

בקשת המרה רגילה באפליקציה תכיל את הפרמטרים הבאים.

בקשה להפעלת מעקב המרות
dev_token

חובה

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

טוקן מפתח ייחודי וסטטי שמונפק לצרכן ה-API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

חובה

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

מזהה הקישור שמקשר את קוד המפתח של צרכן ה-API לאפליקציה ספציפית.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

חובה

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

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

 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

האירוע 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}
rdid

חובה

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

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

f10e1de2-e237-4f50-b6aa-843c45cc63d6

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

00000000-0000-0000-0000-000000000000
id_type

חובה

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

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

Android

advertisingid

iOS

idfa
eea

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

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

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

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

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

*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
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

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

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

הערך האחרון 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 בבקשה.

בקשה לדוגמה

דוגמה לבקשה תקינה למעקב המרות עם סוג אירוע לא מותאם אישית ופרטי הכנסות:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &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.0
       ?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.0
       ?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.0
       ?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.0
       ?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

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

לפרמטר הגוף 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 שמוגדרת באזור הזמן 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"]

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

התגובה של מעקב ההמרות היא בפורמט הבא:

{
  "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

הערך בשדה הזה תמיד יהיה 'אינטראקציה'.

מחרוזת

תשובות לדוגמה

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

{
  "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
}


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

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

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

/pagead/conversion/app/1.0/cross_network

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

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

חובה

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

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

הפונקציה
attributed

חובה

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

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

דוגמה לבקשת שיוך (Attribution) חוצה-פלטפורמות תקינה:

POST /pagead/conversion/app/1.0/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &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 ללא גוף תגובה.