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

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

شناسه‌ها و پارامترهای موردنیاز برای درخواست‌های Measurement Protocol به این بستگی دارد که رویدادها را به جریان داده وب ارسال می‌کنید یا جریان داده برنامه.

  • برای جاری‌سازی‌های وب (که معمولاً با gtag.js یا Google Tag Manager ابزاربندی شده‌اند)، از measurement_id در نشانی وب درخواست و client_id در بدنه JSON برای شناسایی نمونه کاربر استفاده می‌کنید. client_id باید با شناسه تولیدشده توسط برچسب Google Analytics در وب‌سایتتان مطابقت داشته باشد.
  • برای جاری‌سازی‌های برنامه (مجهز به کیت توسعه نرم‌افزار Firebase)، از firebase_app_id در نشانی وب درخواست و app_instance_id در بدنه JSON استفاده می‌کنید که توسط Google Analytics برای کیت توسعه نرم‌افزار Firebase ارائه شده است.

این راهنما برای هر دو سناریو مثال‌هایی ارائه می‌دهد.

عناصر اصلی درخواست براساس نوع جاری‌سازی

مؤلفه جریان داده وب (gtag.js/GTM) جاری‌سازی برنامه (Firebase)
پارامتر نشانی وب جریان داده measurement_id firebase_app_id
پارامتر نشانی وب رمز میانای برنامه‌سازی کاربردی الزامی الزامی
فیلد بدنه JSON شناسه دستگاه client_id app_instance_id

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

این برگه دستورالعمل‌های ارسال رویدادها از سرور شما را نشان می‌دهد که با فعالیت کاربر در جاری‌سازی برنامه بااستفاده از Google Analytics برای Firebase SDK مرتبط است. به‌خاطر داشته باشید که این درخواست‌ها از firebase_app_id و app_instance_id استفاده می‌کنند.

پیش‌نیازها

برای ارسال رویدادها بااستفاده از Measurement Protocol، به شناسه‌های خاصی از دارایی Google Analytics یا پروژه Firebase خود نیاز دارید.

رمز میانای برنامه‌سازی کاربردی

از api_secret برای اصالت‌سنجی درخواست‌هایتان استفاده می‌شود. بسیار مهم است که این راز را محرمانه نگه دارید.

برای ایجاد کردن رمز جدید:

  1. به Google Analytics بروید و به حساب و دارایی‌تان پیمایش کنید.
  2. روی سرپرست در پایین سمت راست کلیک کنید.
  3. در بخش جمع‌آوری و اصلاح داده‌ها، روی جاری‌سازی‌های داده کلیک کنید.
  4. جریان داده‌های «وب» یا «برنامه» را انتخاب کنید.
  5. روی رمزهای Measurement Protocol API کلیک کنید.
  6. روی ایجاد کردن کلیک کنید.
  7. نام مستعاری برای کلید خصوصی وارد کنید و روی ایجاد کلیک کنید.

  8. مقدار رمز را کپی کنید.

شناسه برنامه Firebase

firebase_app_id برنامه Firebase شما را شناسایی می‌کند. این شناسه با app_instance_id یکسان نیست.

برای پیدا کردن شناسه Firebase App:

  1. پروژه‌تان را در کنسول Firebase باز کنید.
  2. روی نماد چرخ‌دنده تنظیمات در کنار نمای کلی پروژه کلیک کنید و تنظیمات پروژه را انتخاب کنید.
  3. در برگه عمومی، به بخش برنامه‌های شما بروید.
  4. برنامه iOS یا Android موردنظر را انتخاب کنید.
  5. مقدار شناسه برنامه را کپی کنید.

قالب‌بندی درخواست

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

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

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

باید موارد زیر را در پارامترهای پُرسمان نشانی وب درخواست ارائه دهید (برای جزئیات مربوط به نحوه یافتن یا ایجاد این مقادیر، به پیش‌نیازها مراجعه کنید):

  • api_secret: رمز میانای برنامه‌سازی کاربردی برای اصالت‌سنجی درخواست.
  • firebase_app_id: شناسه Firebase App برنامه شما.

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

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

باید app_instance_id را در متن درخواست ارائه دهید تا نصب منحصربه‌فرد برنامه تلفن همراهتان شناسایی شود. توجه داشته باشید که این با firebase_app_id که خود برنامه را شناسایی می‌کند متفاوت است. برای اطلاعات بیشتر درباره app_instance_id و نحوه بازیابی آن بااستفاده از کیت توسعه نرم‌افزار Firebase، به اسناد مرجع app_instance_id مراجعه کنید.

درحالی‌که 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",
  headers: {
    "Content-Type": "application/json"
  },
  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 مختص پلاتفرم است. شناسه برنامه را در بخش فایل‌ها و اشیاء پیکربندی Firebase ببینید.

لغو مُهر زمان

«پروتکل اندازه‌گیری» از اولین مُهر زمان که در فهرست زیر پیدا می‌کند برای هر رویداد و مشخصه کاربر در درخواست استفاده می‌کند:

  1. timestamp_micros رویداد یا مشخصه کاربر.
  2. timestamp_micros درخواست.
  3. زمانی که Measurement Protocol درخواست را دریافت می‌کند.

مثال زیر مُهر زمان سطح درخواست را ارسال می‌کند که برای همه رویدادها و ویژگی‌های کاربر در درخواست اعمال می‌شود. درنتیجه، Measurement Protocol مهر زمان 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"
    }
  }
}

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

  • 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 قدیمی‌تر از ۷۲ ساعت قبل باشد، Measurement Protocol رویداد یا مشخصه کاربر را به‌صورت زیر می‌پذیرد یا رد می‌کند:

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

رویدادهای ارسال‌شده بااستفاده از Measurement Protocol که قرار است به‌همراه رویدادهای جمع‌آوری‌شده توسط Google Analytics برای Firebase SDK یا gtag.js ملحق یا پردازش شوند، باید ظرف ۴۸ ساعت از مُهر زمان رویداد اصلی سمت کارخواه توسط Google Analytics دریافت شوند. رویدادهایی که دیرتر از این زمان دریافت شوند ممکن است طبق انتظار پردازش نشوند، به‌ویژه برای اهدافی مانند اسناد تبدیل.

محدودیت‌ها

محدودیت‌های زیر برای ارسال رویدادهای Measurement Protocol به Google Analytics اعمال می‌شود:

  • می‌توانید حداکثر ۱۰۰ میلیون درخواست غیرتبدیل در ساعت برای هر دارایی ارسال کنید. درخواست زمانی غیرتبدیلی است که هیچ‌کدام از رویدادهای موجود در درخواست رویداد کلیدی نباشد که برای آن تبدیل در Google Ads وجود داشته باشد. اگر از این حد فراتر بروید، «پروتکل اندازه‌گیری» همه درخواست‌های غیرتبدیل را برای دارایی در باقی‌مانده ساعت نادیده می‌گیرد.

  • درخواست‌ها می‌توانند حداکثر ۲۵ رویداد داشته باشند.

  • رویدادها می‌توانند حداکثر ۲۵ پارامتر داشته باشند.

  • رویدادها می‌توانند حداکثر ۲۵ ویژگی کاربر داشته باشند.

  • نام‌های ویژگی کاربر باید ۲۴ نویسه یا کمتر باشد.

  • مقادیر ویژگی کاربر باید ۳۶ نویسه یا کمتر باشد.

  • نام رویداد باید ۴۰ نویسه یا کمتر باشد، فقط می‌تواند حاوی نویسه‌های الفباعددی و زیرخط باشد، و باید با نویسه الفبایی شروع شود.

  • نام پارامترها، ازجمله پارامترهای مورد، باید ۴۰ نویسه یا کمتر باشد، فقط می‌تواند حاوی نویسه‌های الفباعددی و زیرخط باشد، و باید با نویسه الفبایی شروع شود.

  • مقادیر پارامتر، ازجمله مقادیر پارامتر مورد، باید ۱۰۰ نویسه یا کمتر برای دارایی استاندارد Google Analytics و ۵۰۰ نویسه یا کمتر برای دارایی Google Analytics 360 باشد.

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

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

  • بدنه پست باید کوچک‌تر از ۱۳۰ کیلوبایت باشد.

  • رویدادهای App Measurement Protocol که به Google Analytics ارسال می‌شوند، مخاطبان «جستجو» را در Google Ads برای کاربران برنامه پر نمی‌کنند.

  • برخی‌از نام‌های رویداد، پارامتر، و مشخصه کاربر رزرو شده‌اند و نمی‌توان از آن‌ها استفاده کرد. برای جزئیات، نام‌های رزروشده را ببینید.

نام‌های رزروشده

Measurement Protocol چندین نام رزروشده دارد که نمی‌توان از آن‌ها برای رویدادها، پارامترها، یا ویژگی‌های کاربر استفاده کرد.

نام‌های رویداد زیر معمولاً باهم اشتباه گرفته می‌شوند:

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