ارسال رویدادهای «پروتکل اندازه‌گیری» به 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 ارائه می‌شود.

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

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

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

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

پیش‌نیازها

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

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

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

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

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

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

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

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

برای پیدا کردن «شناسه برنامه Firebase»:

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 مربوط به برنامه شما.

باید یک بدنه درخواست در قالب بدنه 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. زمانی که «پروتکل اندازه‌گیری» درخواست را دریافت می‌کند.

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

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

محدودیت‌ها

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نام‌های رویداد زیر نقاط مشترک سردرگمی هستند:

• ‫screen_view: این رویداد فقط برای جاری‌سازی‌های برنامه مجاز است. برای جاری‌سازی‌های وب، به‌جای آن از page_view استفاده کنید.
• ‫ad_impression: این رویداد فقط برای جاری‌سازی‌های برنامه مجاز است.
• ‫in_app_purchase: این رویداد فقط برای جاری‌سازی‌های برنامه مجاز است. برای جاری‌سازی‌های وب، به‌جای آن از رویداد purchase استفاده کنید.

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