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

وكيل مستخدم التطبيق

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

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

يكون تعريف هذه الحقول على النحو التالي:

// Specified by API consumer.

// Specified by API consumer.

// Specified by API consumer.

// Specified by API consumer.

String osAndVersion =
    "Android " + Build.VERSION.RELEASE;

UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];

String locale = Locale.getDefault();

NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]

String device = Build.MODEL;

@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];
}

String build = "Build/" + Build.ID;

@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" بحدث التطبيق الذي يجب تتبُّعه كإحالة ناجحة و/أو استخدامه لتعبئة قائمة تجديد النشاط التسويقي، واسترداد البيانات الوصفية التي تصف أي نقرة سبقت الحدث.

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

/pagead/conversion/app/version

سيحتوي طلب الإحالة الناجحة العادي للتطبيق على المَعلمات التالية.

Z_eErE4DkvcKjDM1OVE4c4

31FF8D67E5BB5DD5029DCC2734C2F884

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

level_achieved
Level Achieved

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

f10e1de2-e237-4f50-b6aa-843c45cc63d6

00000000-0000-0000-0000-000000000000

advertisingid

idfa

packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]

1.2.4

android.os.Build.VERSION.RELEASE

[[UIDevice currentDevice] systemVersion]

1.9.5r6

1432681913.123456

1.99

USD

Cj0KEQjw0dy4BRCuuL_e5M

BX3QojHp4mY5MrJtFM_d1u

1

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

ad_click or organic

AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)

216.58.194.174

يجب إرسال كلّ الطلبات عبر HTTPS. سيتم رفض الإشعارات التي يتم تلقيها عبر 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
       &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":{"item_id":["Crayons","Markers"]}}

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

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

مثال على طلب بدء جلسة إعادة إحالة صالح بدأ من الرابط لصفحة في التطبيق 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
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
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، يُرجى استخدام العبارات التالية لأنواع البيانات الأولية:

• العائم

  • استخدِم حرف النقطة كفاصل عشري بشكل مستقل عن أقلمة التطبيقات.
  • استخدِم القيمة العشرية المكوّنة من رقمين لتمثيل القيم النقدية، مثلاً 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 ليوم 23 من الشهر
  • أرسِل دائمًا عدد الأرقام المحدّد أعلاه، على سبيل المثال، إذا أرسلت القيمة "يوم" لليوم الخامس من الشهر، أرسِل 05.
  • أمثلة صالحة:
    • "2016-09-23"
    • "1990-12-31"

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

  • تنسيق الوقت: طابع زمني لنظام التشغيل Unix/Epoch تم تحديده وفقًا للمنطقة الزمنية للتوقيت العالمي المتفق عليه بدقة تصل إلى ميكرو ثانية.
  • أمثلة صالحة:
    • 1478713087 ليوم الأربعاء، 09 تشرين الثاني (نوفمبر) 2016 الساعة 17:38:07 بتوقيت غرينيتش
    • 1073513982.123000 ليوم الأربعاء، 7 كانون الثاني (يناير) 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.

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

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ

conversion

1432681913.123456

ACI
ACE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

123456789

Occasional Gamers (Video)

ClickToDownload

AppDeepLink

AppDeepLinkContinue

Unknown

123456789

Search
Display
YouTube

GoogleSearch

SearchPartners

mGDN

Google AdMob

YouTubeVideos

YouTubeSearch

VideoPartners

dQw4w9WgXcQ

+food +delivery

e

p

b

mobileapp::1-343200656

123456789

My App AdGroup

123456789

نماذج الردود

في ما يلي مثال على الاستجابة لتتبُّع الإحالات الناجحة عندما يتضمّن الطلب أخطاءً:

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

في ما يلي مثال على الاستجابة لتأكيد تتبُّع الإحالات الناجحة لأي حملة على شبكة البحث:

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

في ما يلي مثال على الاستجابة لتأكيد تتبُّع الإحالات الناجحة لأي حملة على الشبكة الإعلانية:

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

في ما يلي مثال على الاستجابة لتأكيد تتبُّع الإحالات الناجحة لأي حملة على 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
}

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

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

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

/pagead/conversion/app/1.0/cross_network

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

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

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 رد عام بدون نص ردّ.