رویدادهای پروتکل اندازه گیری را به 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 تولید شده در رابط کاربری گوگل آنالیتیکس.

  برای ایجاد یک راز جدید، به مسیر Admin > Data collection and modification > Data streams > Data Streams > Select your stream > Measurement Protocol API secrets > Create بروید.

• firebase_app_id : شناسه برنامه Firebase که در کنسول Firebase در مسیر Project Settings > General > Your Apps > App ID یافت می‌شود.

  firebase_app_id با app_instance_id یکسان نیست. firebase_app_id برنامه شما را شناسایی می‌کند، در حالی که app_instance_id یک نصب واحد از برنامه را شناسایی می‌کند.

شما باید یک بدنه درخواست در قالب بدنه JSON POST برای پروتکل اندازه‌گیری ارائه دهید. در اینجا مثالی آورده شده است:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

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

امتحانش کن

در اینجا مثالی آورده شده است که می‌توانید برای ارسال چندین رویداد به طور همزمان استفاده کنید. این مثال یک رویداد tutorial_begin و یک رویداد join_group را به سرور Google Analytics شما ارسال می‌کند، اطلاعات جغرافیایی را با استفاده از فیلد user_location و اطلاعات دستگاه را با استفاده از فیلد device وارد می‌کند.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

قالب firebase_app_id مختص پلتفرم است. به Application ID در بخش Firebase config files and objects مراجعه کنید.

نادیده گرفتن مهر زمانی

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

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

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

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

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

• tutorialBeginUnixEpochTimeInMicros برای رویداد tutorial_begin
• customerTierUnixEpochTimeInMicros برای ویژگی کاربر customer_tier
• requestUnixEpochTimeInMicros برای رویداد join_group و ویژگی کاربر newsletter_reader .

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

رفتار اعتبارسنجی برای رویدادهای گذشته و ویژگی‌های کاربر

رویدادها و ویژگی‌های کاربر می‌توانند تا ۷۲ ساعت به عقب برگردانده شوند. اگر مقدار timestamp_micros زودتر از ۷۲ ساعت پیش باشد، پروتکل اندازه‌گیری، رویداد یا ویژگی کاربر را به شرح زیر می‌پذیرد یا رد می‌کند:

• اگر validation_behavior تنظیم نشده باشد یا روی RELAXED تنظیم شده باشد، پروتکل اندازه‌گیری، رویداد یا ویژگی کاربر را می‌پذیرد اما مهر زمانی آن را به ۷۲ ساعت پیش تغییر می‌دهد.
• اگر validation_behavior روی ENFORCE_RECOMMENDATIONS تنظیم شده باشد، پروتکل اندازه‌گیری، رویداد یا ویژگی کاربر را رد می‌کند.

محدودیت‌ها

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

• درخواست‌ها می‌توانند حداکثر ۲۵ رویداد داشته باشند.
• رویدادها می‌توانند حداکثر ۲۵ پارامتر داشته باشند.
• رویدادها می‌توانند حداکثر ۲۵ ویژگی کاربری داشته باشند.
• نام ویژگی‌های کاربر باید ۲۴ کاراکتر یا کمتر باشد.
• مقادیر ویژگی‌های کاربر باید ۳۶ کاراکتر یا کمتر باشد.
• نام رویدادها باید ۴۰ کاراکتر یا کمتر باشد، فقط می‌تواند شامل کاراکترهای الفبایی-عددی و زیرخط باشد و باید با یک کاراکتر الفبایی شروع شود.
• نام پارامترها شامل پارامترهای آیتم باید ۴۰ کاراکتر یا کمتر باشد، فقط می‌تواند شامل کاراکترهای الفبایی-عددی و زیرخط باشد و باید با یک کاراکتر الفبایی شروع شود.

• مقادیر پارامتر، شامل مقادیر پارامتر آیتم، باید برای یک ویژگی استاندارد گوگل آنالیتیکس ۱۰۰ کاراکتر یا کمتر و برای یک ویژگی گوگل آنالیتیکس ۳۶۰، ۵۰۰ کاراکتر یا کمتر باشند.

  این محدودیت برای پارامترهای session_id و session_number اعمال نمی‌شود، زمانی که مقادیر آنها توسط متغیرهای داخلی Analytics Session ID و Analytics Session Number مربوطه در Google Tag Manager ارائه شده باشد.

• پارامترهای آیتم می‌توانند حداکثر ۱۰ پارامتر سفارشی داشته باشند.

• حجم متن پست باید کمتر از ۱۳۰ کیلوبایت باشد.

• مهر زمانی باید مربوط به ۷۲ ساعت گذشته باشد. برای جزئیات بیشتر به بخش اعتبارسنجی رویدادهای گذشته مراجعه کنید.

• رویدادهای پروتکل اندازه‌گیری برنامه که به گوگل آنالیتیکس ارسال می‌شوند، مخاطبان جستجو در گوگل ادز را برای کاربران برنامه جمع نمی‌کنند.

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