ردیابی تبدیل برنامه و بازاریابی مجدد - مشخصات درخواست/پاسخ

عامل کاربر برنامه

به‌عنوان بخشی از تلاش‌های گسترده‌ترمان برای مبارزه با هرزنامه، یک مشخصات استاندارد برای سربرگ User-Agent ایجاد کرده‌ایم که توسط یک محصول تجزیه و تحلیل/تبلیغات به نمایندگی از یک کاربر برنامه ارسال می‌شود. برنامه User-Agent را می توان از کد بومی برای رعایت مشخصات زیر مشتق کرد:

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 در انتهای برنامه User-Agent هنگام ساخت برنامه 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 Ads از رویداد برنامه‌ای است که باید به‌عنوان تبدیل ردیابی شود و/یا برای تکمیل فهرست بازاریابی مجدد استفاده شود، و بازیابی فراداده‌ای که هر کلیکی را که قبل از رویداد توصیف می‌کند توصیف می‌کند.

همه تماس‌های API با دامنه 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 (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
       &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 ماه
  • همیشه تعداد ارقام مشخص شده در بالا را ارسال کنید، به عنوان مثال اگر مقدار dd را برای روز پنجم ماه ارسال می کنید، 05 را ارسال کنید.
  • نمونه های معتبر:
    • "2016-09-23"
    • "1990-12-31"

• مهر زمان

  • قالب زمان: مهر زمانی Unix/Epoch در منطقه زمانی UTC با دقت حداکثر میکروثانیه تعریف شده است
  • نمونه های معتبر:
    • 1478713087 برای چهارشنبه، 09 نوامبر 2016، 17:38:07 GMT
    • 1073513982.123000 برای چهارشنبه، 07 ژانویه 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 .

رویدادهای تبلیغاتی اشیاء اصلی تخصیص برنامه هستند و دارای ویژگی‌های زیر هستند.

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 Ads به درخواست ردیابی تبدیل پاسخ مثبت می‌دهد، مصرف‌کننده API باید پس از شناسایی آخرین کلیک، تصمیم خود را درباره انتساب بین شبکه‌ای به Google Ads اطلاع دهد.

درخواست انتساب بین شبکه ای مشابه درخواست اصلی ردیابی تبدیل است، اما با یک مسیر درخواست:

/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 بدون بدنه پاسخ دریافت می کند.