رویدادهای پروتکل اندازه گیری را به Google Analytics ارسال کنید

این راهنما توضیح می‌دهد که چگونه می‌توانید رویدادهای جریان برنامه و وب پروتکل اندازه‌گیری Google Analytics را به سرور Google Analytics ارسال کنید تا بتوانید رویدادهای پروتکل اندازه‌گیری را در گزارش‌های Google Analytics خود مشاهده کنید.

پلتفرمی را که می خواهید در این راهنما ببینید انتخاب کنید:

فرمت درخواست

پروتکل اندازه گیری Google Analytics فقط از درخواست های HTTP POST پشتیبانی می کند.

برای ارسال رویداد از فرمت زیر استفاده کنید:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>

شما باید موارد زیر را در URL درخواست ارائه دهید:

  • api_secret : API SECRET ایجاد شده در رابط کاربری Google Analytics.

    برای ایجاد یک راز جدید، به Admin > Data Streams > جریان خود > Measurement Protocol > Create را انتخاب کنید.

  • measurement_id : شناسه اندازه‌گیری مرتبط با یک جریان، که در رابط کاربری Google Analytics در زیر Admin > Data Streams > جریان خود را انتخاب کنید > Measurement ID یافت می‌شود.

    measurement_id شناسه جریان شما نیست.

برای مرجع کامل به پارامترهای پرس و جو مراجعه کنید.

شما باید موارد زیر را در بدنه درخواست ارائه دهید:

  • client_id : یک شناسه منحصر به فرد برای یک مشتری. این با Firebase app_instance_id متفاوت است. از gtag.js('get') استفاده کنید.

  • user_id : اختیاری. یک شناسه منحصر به فرد برای یک کاربر. فقط می تواند شامل نویسه های UTF-8 باشد. برای اطلاعات بیشتر در مورد این شناسه ، برای تجزیه و تحلیل بین پلتفرم، User-ID را ببینید.

  • consent : اختیاری با نحوه تنظیم تنظیمات رضایت آشنا شوید.

  • timestamp_micros : اختیاری. زمان یونیکس، در میکروثانیه، برای رویدادها و ویژگی های کاربر در درخواست. اگر مشخص نشده باشد، به طور پیش فرض روی زمان درخواست تنظیم می شود .

  • events : مجموعه ای از آیتم های رویداد. می توانید چندین رویداد را در یک درخواست قرار دهید.

    برای اینکه فعالیت کاربر در گزارش‌هایی مانند Realtime نمایش داده شود، engagement_time_msec و session_id باید به عنوان بخشی از params یک event ارائه شوند. پارامتر engagement_time_msec باید زمان تعامل رویداد را بر حسب میلی ثانیه منعکس کند.

    در اینجا یک مثال است: 

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": "100"
        }
     }
   ]
  }

در حالی که session_start یک نام رویداد رزرو شده است، ایجاد یک session_id جدید یک جلسه جدید بدون نیاز به ارسال session_start ایجاد می کند. نحوه شمارش جلسات را درک کنید.

آن را امتحان کنید

در اینجا نمونه‌ای وجود دارد که می‌توانید از آن برای ارسال رویداد tutorial_begin به سرور Google Analytics خود استفاده کنید: 

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    events: [{
      name: 'tutorial_begin',
      params: {},
    }]
  })
});

لغو مهر زمانی

پروتکل اندازه گیری از اولین مهر زمانی که در لیست زیر پیدا می کند برای هر رویداد در درخواست استفاده می کند:

  1. timestamp_micros رویداد.
  2. timestamp_micros درخواست.
  3. زمانی که پروتکل اندازه گیری درخواست را دریافت می کند.

مثال زیر یک مهر زمانی در سطح درخواست ارسال می کند که برای همه رویدادهای درخواست اعمال می شود. در نتیجه، پروتکل اندازه گیری به هر دو رویداد tutorial_begin و join_group یک مهر زمانی از requestUnixEpochTimeInMicros اختصاص می دهد.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

مثال زیر هم یک مهر زمانی در سطح درخواست و هم مهر زمانی در سطح رویداد را ارسال می کند. در نتیجه، پروتکل اندازه‌گیری به رویداد tutorial_begin یک مهر زمانی از tutorialBeginUnixEpochTimeInMicros و رویداد join_group یک مهر زمانی از requestUnixEpochTimeInMicros اختصاص می‌دهد. 

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

محدودیت ها

محدودیت‌های زیر برای ارسال رویدادهای پروتکل اندازه‌گیری به Google Analytics اعمال می‌شود:

  • درخواست ها می توانند حداکثر 25 رویداد داشته باشند.
  • رویدادها می توانند حداکثر 25 پارامتر داشته باشند.
  • رویدادها می توانند حداکثر 25 ویژگی کاربر داشته باشند.
  • نام ویژگی های کاربر باید 24 کاراکتر یا کمتر باشد.
  • مقادیر ویژگی کاربر باید 36 کاراکتر یا کمتر باشد.
  • نام رویدادها باید 40 نویسه یا کمتر باشد، فقط می‌توانند شامل نویسه‌های الف-عددی و زیرخط باشند و باید با یک نویسه الفبا شروع شوند.
  • نام پارامترها شامل پارامترهای آیتم باید 40 کاراکتر یا کمتر باشد، فقط می‌تواند شامل نویسه‌های الف-عددی و زیرخط باشد و باید با یک نویسه الفبایی شروع شود.
  • مقادیر پارامتر شامل مقادیر پارامتر آیتم باید 100 نویسه یا کمتر برای یک ویژگی استاندارد Google Analytics و 500 کاراکتر یا کمتر برای ویژگی Google Analytics 360 باشد.
  • پارامترهای مورد می توانند حداکثر 10 پارامتر سفارشی داشته باشند.
  • بدنه پست باید کوچکتر از 130 کیلوبایت باشد.
  • رویدادهای پروتکل اندازه‌گیری برنامه ارسال شده به Google Analytics مخاطبان جستجو در Google Ads را برای کاربران برنامه پر نمی‌کند.

برای الزامات اضافی هر مورد، موارد استفاده رایج را ببینید.