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

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

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

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

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

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

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

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

پیش‌نیازها

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

راز API

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

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

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

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

شناسه برنامه فایربیس

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

برای یافتن شناسه برنامه Firebase خود:

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

فرمت درخواست

پروتکل اندازه‌گیری گوگل آنالیتیکس فقط از درخواست‌های 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

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

• api_secret : رمز API برای تأیید اعتبار درخواست.
• firebase_app_id : شناسه برنامه Firebase برنامه شما.

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

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

محدودیت‌ها

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

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

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

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

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

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

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

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

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

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

نام رویدادهای زیر از نکات رایج سردرگمی هستند:

• screen_view : این رویداد فقط برای استریم‌های اپلیکیشن مجاز است. برای استریم‌های وب، به جای آن page_view استفاده کنید.
• ad_impression : این رویداد فقط برای جریان‌های برنامه (App streams) مجاز است.
• in_app_purchase : این رویداد فقط برای استریم‌های اپلیکیشن مجاز است. برای استریم‌های وب، از رویداد purchase استفاده کنید.

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