GOOGLE_ANALYTICS_TEST_SUMMARY.md

📊 گزارش تست Google Analytics API - داده‌های رایگان

✅ وضعیت نصب

• ✅ کتابخانه google-analytics-data نصب شد (نسخه 0.19.0)
• ✅ کتابخانه google-auth از قبل نصب بود (نسخه 2.35.0)
• ✅ فایل تست ایجاد شد: scripts/test_google_analytics_free_data.py

---

📋 داده‌های رایگان قابل دسترس

1. Metric های پایه (بدون نیاز به تنظیمات)

Metric	توضیحات	استفاده در ادمین
activeUsers	کاربران فعال	✅ تعداد بازدیدکنندگان
newUsers	کاربران جدید	✅ آمار کاربران جدید
totalUsers	کل کاربران	✅ آمار کلی
sessions	جلسات	✅ تعداد جلسات
screenPageViews	بازدید صفحات	✅ آمار بازدید
averageSessionDuration	میانگین مدت جلسه	✅ زمان حضور
bounceRate	نرخ پرش	✅ کیفیت بازدید
engagementRate	نرخ تعامل	✅ تعامل کاربران

2. Dimension های مفید

📄 صفحات:

• pagePath - مسیر صفحه (مثل /dashboard)
• pageTitle - عنوان صفحه
• ✅ استفاده: لیست صفحات پربازدید

🌍 جغرافیا:

• country - کشور
• region - منطقه
• city - شهر
• ✅ استفاده: آمار جغرافیایی کاربران

📱 دستگاه:

• deviceCategory - نوع دستگاه (desktop, mobile, tablet)
• operatingSystem - سیستم عامل
• browser - مرورگر
• ✅ استفاده: آمار دستگاه‌ها

🔗 ترافیک:

• sessionSource - منبع (google, direct, ...)
• sessionMedium - رسانه (organic, cpc, ...)
• sessionDefaultChannelGroup - گروه کانال
• ✅ استفاده: منابع ترافیک

👤 کاربران:

• newVsReturning - کاربر جدید/بازگشتی
• ✅ استفاده: تحلیل رفتار کاربران

📅 زمان:

• date - تاریخ روزانه
• ✅ استفاده: نمودارهای سری زمانی

---

🎯 داده‌های مفید برای بخش ادمین

✅ می‌توانید دریافت کنید:

1. آمار کلی بازدیدها (7 روز، 30 روز، ...)

   • تعداد کاربران فعال
   • تعداد کاربران جدید
   • تعداد جلسات
   • تعداد بازدید صفحات

2. صفحات پربازدید (Top 10)

   • مسیر صفحه
   • عنوان صفحه
   • تعداد بازدید
   • تعداد کاربران

3. اطلاعات جغرافیایی

   • کشورهای کاربران
   • شهرهای کاربران
   • توزیع جغرافیایی

4. نوع دستگاه

   • Desktop vs Mobile vs Tablet
   • سیستم عامل
   • مرورگر

5. منابع ترافیک

   • Google Search
   • Direct
   • Social Media
   • Referral

6. سری زمانی (برای نمودار)

   • آمار روزانه
   • آمار هفتگی
   • آمار ماهانه

7. رفتار کاربران

   • کاربران جدید vs بازگشتی
   • میانگین مدت جلسه
   • نرخ پرش

---

⚠️ محدودیت‌ها

❌ داده‌هایی که نیاز به تنظیمات دارند:

1. userId - برای ردیابی کاربران خاص:

   • باید در frontend تنظیم شود
   • فقط برای کاربران لاگین شده

2. Conversions & Revenue:

   • نیاز به تنظیم Goals
   • نیاز به ارسال رویدادهای ecommerce

✅ داده‌هایی که بدون تنظیمات در دسترس هستند:

• ✅ همه Metric های پایه
• ✅ همه Dimension های جغرافیایی
• ✅ همه Dimension های دستگاه
• ✅ همه Dimension های صفحات
• ✅ همه Dimension های ترافیک
• ✅ سری زمانی
• ✅ رفتار کاربران (newVsReturning)

---

💰 هزینه

• ✅ کاملاً رایگان تا 10 میلیون درخواست در ماه
• ✅ Rate Limit: 10 درخواست در ثانیه
• ✅ داده‌های تاریخی: تا 14 ماه گذشته

---

🚀 مراحل بعدی

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

1. ✅ کتابخانه‌ها نصب شدند
2. ⏳ تنظیم Service Account (راهنما: docs/SETUP_GOOGLE_ANALYTICS_API.md)
3. ⏳ تنظیم Property ID
4. ⏳ اجرای تست کامل: python scripts/test_google_analytics_free_data.py
5. ⏳ پیاده‌سازی API endpoint در backend
6. ⏳ ایجاد صفحه Analytics در بخش ادمین

---

📊 مثال داده‌های قابل دریافت

مثال 1: آمار 7 روز گذشته

{
  "period": "7 days",
  "activeUsers": 1250,
  "newUsers": 320,
  "sessions": 1850,
  "screenPageViews": 5420,
  "averageSessionDuration": 245.5,
  "bounceRate": 0.35
}

مثال 2: صفحات پربازدید

[
  {
    "pagePath": "/dashboard",
    "pageTitle": "Dashboard",
    "views": 1250,
    "users": 850
  },
  {
    "pagePath": "/login",
    "pageTitle": "Login",
    "views": 980,
    "users": 980
  }
]

مثال 3: کاربران بر اساس کشور

[
  {"country": "Iran", "users": 850},
  {"country": "United States", "users": 120},
  {"country": "Germany", "users": 45}
]

---

🎯 توصیه نهایی

روش ترکیبی (بهترین گزینه):

Google Analytics API برای:

• ✅ آمار کلی بازدیدها (همه کاربران)
• ✅ صفحات پربازدید
• ✅ اطلاعات جغرافیایی
• ✅ منابع ترافیک
• ✅ نمودارهای سری زمانی

Database Internal برای:

• ✅ ردیابی دقیق کاربران لاگین شده
• ✅ زمان ورود/خروج دقیق
• ✅ مسیرهای ناوبری کاربران خاص
• ✅ مدت زمان حضور دقیق در هر صفحه

---

📚 فایل‌های ایجاد شده

1. ✅ scripts/test_google_analytics_free_data.py - اسکریپت تست کامل
2. ✅ docs/GOOGLE_ANALYTICS_FREE_DATA_REPORT.md - گزارش کامل داده‌ها
3. ✅ docs/SETUP_GOOGLE_ANALYTICS_API.md - راهنمای تنظیم
4. ✅ backend/requirements.txt - به‌روزرسانی شد

---

✅ نتیجه‌گیری

Google Analytics API می‌تواند داده‌های زیادی را به صورت رایگان در اختیار شما قرار دهد:

• ✅ آمار کلی بازدیدها
• ✅ صفحات پربازدید
• ✅ اطلاعات جغرافیایی
• ✅ نوع دستگاه
• ✅ منابع ترافیک
• ✅ سری زمانی
• ✅ رفتار کاربران

اما برای ردیابی دقیق کاربران لاگین شده و مسیرهای ناوبری، بهتر است از Database Internal استفاده کنید.

توصیه: از روش ترکیبی استفاده کنید! 🎯