تتبُّع الإحالات الناجحة وتجديد النشاط التسويقي للتطبيقات - مواصفات الطلب/الاستجابة

App User-Agent

في إطار جهودنا الأوسع لمكافحة المحتوى غير المرغوب فيه، طوّرنا مواصفات موحّدة لعنوان User-Agent الذي يرسله منتج إحصاءات أو إعلانات نيابةً عن مستخدم تطبيق. يمكن استخلاص User-Agent للتطبيق من الرمز البرمجي الأصلي للالتزام بالمواصفات التالية:

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

في ما يلي تعريف لهذه الحقول:

مكوّنات User-Agent
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/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 في نهاية User-Agent للتطبيق فقط عند إنشاء User-Agent للتطبيق من جهة الخادم. إذا تم إنشاء وكيل المستخدم للتطبيق بالكامل من جهة العميل، استبعِد ; Proxy. وبالتالي، قد تكون سلسلة وكيل المستخدم الخاصة بأحد التطبيقات كما يلي:

  • نظام تشغيل Android:‏ AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
  • نظام تشغيل iOS:‏ AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

طلب تتبُّع الإحالات الناجحة

الغرض من طلبات تتبُّع الإحالات الناجحة هو إعلام "إعلانات Google" بحدث في التطبيق يجب تتبُّعه كإحالة ناجحة و/أو استخدامه لملء قائمة تجديد النشاط التسويقي، واسترداد البيانات الوصفية التي تصف أي نقرة سبقت الحدث.

يتم إجراء جميع طلبات البيانات من واجهة برمجة التطبيقات إلى النطاق www.googleadservices.com. طلبات الإحالة الناجحة هي طلبات POST عبر HTTPS على المسار التالي: 

/pagead/conversion/app/version
حيث version هو الإصدار المطلوب من واجهة برمجة التطبيقات لتتبُّع الإحالات الناجحة. الإصدار الوحيد الصالح حاليًا هو 1.0.

سيتضمّن طلب الإحالة الناجحة العادي في التطبيق المَعلمات التالية.

طلب تتبُّع الإحالات الناجحة
dev_token

مطلوب

الموقع الجغرافي: طلب البحث

الرمز المميز الثابت والفريد الذي يتم إصداره لمستهلك واجهة برمجة التطبيقات.

Z_eErE4DkvcKjDM1OVE4c4
link_id

مطلوب

الموقع الجغرافي: طلب البحث

معرّف الرابط الذي يربط الرمز المميز للمطوّر الخاص بمستهلك واجهة برمجة التطبيقات بتطبيق معيّن.

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. يجب أن يحتوي هذا الحقل على ما بين حرف واحد و64 حرفًا من أحرف Unicode (باستخدام ترميز UTF-8). هذا الحقل مطلوب إذا كانت قيمة app_event_type هي مخصّصة.

level_achieved
Level Achieved

يجب ألا يحتوي هذا الحقل على أي من القيم المحجوزة لـ app_event_type. في حال استخدام اسم حدث محجوز، ستعرض واجهة برمجة التطبيقات الخطأ APP_EVENT_NAME_RESERVED_VALUE.
app_event_data

اختياري

الموقع الجغرافي: الجسم

أرسِل أي بيانات إضافية عن الأحداث الغنية بصريًا ككائن JSON بسيط يربط السلاسل الرئيسية بالقيم. وتكون القيم المقبولة هي سلاسل ومجموعات منها.

{"level": 5, "attempts": 20}
rdid

مطلوب

الموقع الجغرافي: طلب البحث

سلسلة معرّف فريد عالمي (UUID) صالحة تمثّل رقم تعريف الجهاز الأولي

f10e1de2-e237-4f50-b6aa-843c45cc63d6

في حال عدم توفّر معرّف الجهاز، مثل معرّف الجهاز من مستخدم لم يوافق على إطار عمل ATT، اضبطه على القيمة صفر.

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

مطلوبة بموجب شروط معيّنة

الموقع الجغرافي: طلب البحث

معرّف تحديد المصدر المستند إلى 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. سيتم رفض طلبات Ping التي يتم تلقّيها عبر HTTP.

يُرجى العِلم أنّه إذا كان نص الطلب فارغًا (في الحالات التي لا يتم فيها تمرير أي بيانات أحداث منسّقة في حمولة 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

في ما يلي مثال على طلب صالح لتتبُّع الإحالات الناجحة لمستخدم في المنطقة الاقتصادية الأوروبية تمّت الموافقة فيه على استخدام بيانات المستخدم في الإعلانات ورفض تخصيص الإعلانات:

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

  • عدد صحيح

    • أرسِل قيم أعداد صحيحة فقط بدون أرقام عشرية
    • لا تستخدِم حرف الفاصلة للفصل بين مجموعات الأرقام، مثل 1,000,000
    • أمثلة صالحة:
      • 1000
      • -11
      • 0

  • التاريخ

    • تنسيق التاريخ: yyyy-mm-dd
      • ‫yyyy = السنة بتنسيق من أربعة أرقام، مثل 2016
      • ‫mm = شهر مكوّن من رقمين، مثل 09 لسبتمبر
      • ‫dd = يوم من رقمين، مثل 23 لليوم الثالث والعشرين من الشهر
    • يجب دائمًا إرسال عدد الأرقام المحدّد أعلاه، مثلاً، إذا أردت إرسال قيمة dd لليوم الخامس من الشهر، أرسِل 05.
    • أمثلة صالحة:
      • "2016-09-23"
      • "1990-12-31"

  • الطابع الزمني

    • تنسيق الوقت: الطابع الزمني لحقبة Unix المحدّد في المنطقة الزمنية UTC بدقة تصل إلى الميكروثانية
    • أمثلة صالحة:
      • 1478713087 for Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 ليوم الأربعاء 07 كانون الثاني (يناير) 2004 الساعة 22:19:42.123 بتوقيت غرينتش

  • المصفوفات

    • إرسال مصفوفات من القيم الأساسية فقط (سلاسل وأرقام وقيم منطقية)
    • أمثلة صالحة:
      • [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" مطلوب لجميع طلبات منطقة السوق المحدّدة التي تندرج ضمن النطاق.

  • ad_user_data_invalid: كانت قيمة الطلب "ad_user_data" غير صالحة. حقل "ad_user_data" مطلوب لجميع طلبات منطقة السوق المحدّدة التي تندرج ضمن النطاق.

  • ad_personalization_missing_or_invalid: لم يتضمّن الطلب الحقل "ad_personalization" أو كان غير صالح. حقل "ad_personalization" مطلوب لجميع طلبات منطقة السوق المحدّدة التي تندرج في النطاق.

أحداث الإعلانات هي العناصر الأساسية لتحديد مصدر التثبيت في التطبيق، وستتضمّن الخصائص التالية.

ملاحظات مهمة بشأن سلوك الاستجابة الذي يعتمد على موافقة المستخدِم:
إذا كانت الإحالة الناجحة تتضمّن موافقة على استخدام بيانات المستخدِمين في الإعلانات، وكان المستخدِم قد وافق على الاستخدام المتعدّد ضمن إعدادات مستخدِم Google، ستستجيب "إعلانات Google" بنقرة واحدة أخيرة على جميع منصّات الشراكة في المبيعات. إذا لم يوافق المستخدم على استخدام الموافقة على مستوى المنتجات المختلفة ضمن إعدادات المستخدم على Google، ستستجيب &quot;إعلانات Google&quot; بعدة نقرات أخيرة، وذلك على أساس كلّ منتج من منتجات &quot;منصة Google للتسويق&quot;.

إذا كانت الإحالة الناجحة تتضمّن بعض خدمات CPS التي وافق المستخدم على استخدامها بشكل مشترك ولكن ليس غيرها، ستردّ "إعلانات Google" بنقرة أخيرة واحدة على مستوى خدمات CPS التي وافق المستخدم على استخدامها بشكل مشترك، ولكن مع نقرات أخيرة متعدّدة، على مستوى كل خدمة CPS، بالنسبة إلى خدمات CPS التي لم يوافق المستخدم على استخدامها بشكل مشترك.

ردّ ميزة "تتبُّع الإحالات الناجحة"
ad_event_id

الظهور دائمًا

سلسلة

يعمل ad_event_id كمعرّف فريد لأحداث الإعلانات. ويتم إعادة استخدامه في طلب الإحالة على جميع الشبكات، ويجب تسجيله/الاحتفاظ به لأغراض تصحيح الأخطاء.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

الظهور دائمًا

سلسلة

مقياس الإحالة الناجحة المستخدَم لتحديد المصدر. سنوفّر في البداية مقياس إحالة ناجحة واحدًا.

conversion
timestamp

الظهور دائمًا

الرقم

الطابع الزمني لنظام التشغيل UNIX الذي وقع فيه الحدث الإعلاني، بالثواني وبدقة تصل إلى الميكروثانية يجب استخدام هذه القيمة لتحديد المصدر بالاستناد إلى النقرة الأخيرة.

1432681913.123456
campaign_type

الظهور دائمًا

سلسلة

سيحدّد هذا الحقل نوع الحملة التي أدّت إلى ظهور حدث الإعلان. في ما يلي القيم المحتمَلة.

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI هو اختصار لـ "حملة التطبيقات لجذب عمليات التثبيت". ‫ACE هو اختصار لـ "حملات التطبيقات لجذب المستخدمين الحاليين".
campaign_id

الظهور دائمًا

الرقم

رقم تعريف الحملة الرقمي للحملة التي أدّت إلى الحدث الإعلاني. هذه القيمة مضمونة بأنّها فريدة.

123456789
campaign_name

الظهور دائمًا

سلسلة

تمثّل هذه السمة اسم الحملة الذي حدّده المعلِن للحملة التي أدّت إلى إنشاء حدث الإعلان. لا يُضمن أن تكون هذه القيمة فريدة.

Occasional Gamers (Video)
ad_type

الظهور دائمًا

سلسلة

نوع الإعلان الذي أدّى إلى حدث الإعلان. يمكن استخدام هذه القيمة للتمييز بين أنواع المستودع المختلفة على النحو التالي.

الترويج لتطبيق 
ClickToDownload
 جذب المستخدمين إلى التطبيق 
AppDeepLink
 التفاعل مع التطبيق: عملية التثبيت والمتابعة 
AppDeepLinkContinue
 فئة شاملة للقيم الأخرى 
Unknown
external_customer_id

الظهور دائمًا

الرقم

تمثّل هذه السمة معرّف المعلِن الذي يملك الحملة التي أدّت إلى ظهور الحدث الإعلاني. يمكن استخدام هذه القيمة للتمييز بين حسابات &quot;إعلانات Google&quot;.

123456789
location

الظهور دائمًا

الرقم

رمز معرّف الموقع الجغرافي لحدث الإعلان. راجِع مرجع Google Ads API لتفسير رموز المواقع الجغرافية.
network_type

الظهور دائمًا

سلسلة

سيحدّد هذا الحقل شبكة الإعلانات على &quot;إعلانات Google&quot; التي وقع عليها الحدث الإعلاني. في ما يلي القيم المحتمَلة.

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

ستكون القيمة null عندما تكون قيمة campaign_type هي ACI أو ACE وقيمة network_type هي Display.

سلسلة

سيحدّد هذا الحقل "النوع الفرعي" لشبكة الإعلانات على "إعلانات Google" التي وقع عليها الحدث الإعلاني. تختلف القيم المحتملة حسب نوع الشبكة الأساسية.

"بحث 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.

الرقم

رقم التعريف الرقمي للمجموعة الإعلانية التي أدّت إلى الحدث الإعلاني. هذه القيمة مضمونة بأنّها فريدة.

123456789
ad_group_name

يتم توفيرها فقط عندما تكون قيمة campaign_type هي ACI أو ACE أو ACPRE.

سلسلة

اسم المجموعة الإعلانية التي حدّدها المعلِن والتي أنتجت حدث الإعلان. لا يُضمن أن تكون هذه القيمة فريدة.

My App AdGroup
creative_id

يتم توفيرها فقط عندما تكون قيمة campaign_type هي not ACI أو ACE أو ACPRE أو Performance_Max.

الرقم

رقم التعريف الرقمي لوحدة الإعلان الإبداعية التي أنتجت الحدث الإعلاني. هذه القيمة مضمونة بأنّها فريدة.

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
}


طلب الإحالة على جميع الشبكات

عندما تردّ &quot;إعلانات Google&quot; بشكل إيجابي على طلب تتبُّع إحالة ناجحة، على مستهلك واجهة برمجة التطبيقات إبلاغ &quot;إعلانات Google&quot; بقرار تحديد المصدر على مستوى الشبكات بعد تحديد النقرة الأخيرة.

يكون طلب تحديد المصدر على مستوى شبكات متعدّدة مطابقًا لطلب تتبُّع الإحالات الناجحة الأصلي، ولكن مع مسار طلب على النحو التالي:

/pagead/conversion/app/1.0/cross_network

وإضافة مَعلمتَين مطلوبتَين:

طلب الإحالة على جميع الشبكات
ad_event_id

مطلوب

الموقع الجغرافي: طلب البحث

المعرّف ad_event_id من حدث الإعلان المرتبط بعملية تحديد المصدر في الطلب السابق.
attributed

مطلوب

الموقع الجغرافي: طلب البحث

تُستخدَم لتحديد ما إذا كانت "إعلانات Google" قد تلقّت نسبة مساهمة في الإحالة الناجحة من خلال مستهلك واجهة برمجة التطبيقات أم لا. إما 0 أو 1

في ما يلي مثال على طلب صالح للإحالة على جميع الشبكات:

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 بدون نص الاستجابة.