استفاده برنامه‌ریزی‌شده از «مشاور» در Google Analytics برای پُرسمان و تجزیه‌وتحلیل داده‌ها

روش chat Data API دسترسی برنامه‌ای به Ask Advisor در Google Analytics را فراهم می‌کند — دستیار تحلیلی با بهره‌گیری از هوش مصنوعی که به شما کمک می‌کند داده‌های Google Analytics خود را بااستفاده از زبان طبیعی پُرسمان، تحلیل، و عیب‌یابی کنید.

درحالی‌که «از مشاور بپرسید» به‌صورت تعاملی در میانای کاربر Google Analytics دردسترس است، chat API به توسعه‌دهندگان، عامل‌های هوش مصنوعی خودکار، و ابزارهای داخلی اجازه می‌دهد ازطریق HTTP با «از مشاور بپرسید» به‌صورت برنامه‌ریزی‌شده تعامل کنند.

مهم: این محصول از هوش مصنوعی استفاده می‌کند و ممکن است اطلاعات نادرست نشان دهد. ممکن است از فعالیت گپ شما برای بهبود دادن محصول استفاده شود و استفاده شما تابع شرایط، خط‌مشی استفاده از هوش مصنوعی، و خط‌مشی رازداری Google است.

نمای کلی

روش chat هم سؤالات داده‌ای موردی تک‌نوبتی و هم جلسات مکالمه‌ای چندنوبتی را فعال می‌کند:

  1. پُرسمان‌های تک‌نوبتی: سؤالات تحلیلی فوری بپرسید (مثلاً «کانال‌های ترافیک برتر ما در هفته گذشته چه بود؟») و پاسخ‌هایی به زبان طبیعی همراه با جدول‌های داده ساختاریافته دریافت کنید.
  2. مکالمه‌های چندنوبتی: sessionId را ارسال کنید تا سابقه مکالمه حفظ شود و سؤالات تعقیبی تشخیصی بپرسید (مثلاً «چرا ترافیک طبیعی در آن دوره کاهش یافت؟»).
  3. پاسخ‌های داده‌های ساختاریافته: علاوه‌بر روایت‌های نوشتاری، پاسخ‌ها حاوی بلوک‌های ساختاریافته table با سرصفحه‌های ستون و ردیف هستند.
  4. پایش سهمیه گپ: با تنظیم کردن returnPropertyQuota روی true، سهمیه باقی‌مانده گپ روزانه و ساعتی را بررسی کنید.

اصالت‌سنجی

تماس با روش chat به مجوز OAuth 2.0 با حوزه زیر نیاز دارد:

قبل‌از شروع

  1. gcloud CLI را نصب و مقداردهی اولیه کنید.

  2. برای تولید اعتبارنامه‌های پیش‌فرض برنامه و دادن دامنه‌های لازم به حسابتان، دستور زیر را اجرا کنید:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"
    
  3. در رابط کاربری Google Analytics، به حساب کاربری‌تان دسترسی به دارایی Google Analytics اعطا کنید.

  4. متغیرهای محیطی‌تان را با وارد کردن موارد زیر پیکربندی کنید. PROJECT_ID را با شناسه پروژه و PROPERTY_ID را با شناسه دارایی Google Analytics خودتان جایگزین کنید.

      export PROJECT_ID=PROJECT_ID
      export PROPERTY_ID=PROPERTY_ID

مثال ۱: پُرسمان تک‌نوبتی با ردیابی سهمیه

برای شروع مکالمه جدید، ChatRequest بسازید که حاوی userQuery شما باشد. برای بررسی تراز باقی‌مانده رمز خود، returnPropertyQuota را روی true تنظیم کنید.

سناریو: درآمد و نرخ تبدیل براساس دستگاه

می‌خواهید درآمد و نرخ تبدیل‌به‌مشتری جلسه را در دستگاه‌های مختلف در ۳۰ روز گذشته مقایسه کنید.

درخواست اچ‌تی‌تی‌پی

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
    "returnPropertyQuota": true
  }'

پاسخ HTTP

پاسخ حاوی این موارد است:

  • sessionId جدیدی که می‌توانید برای نوبت‌های بعدی استفاده کنید.
  • فهرستی از blocks که هم حاوی خلاصه زبان طبیعی (text) و هم جدول ساختاریافته (table) است. بلوک‌های نوشتاری می‌توانند حاوی قالب‌بندی Markdown مانند نوشتار پررنگ، عنوان‌ها، و پیوندها باشند.
  • جزئیات propertyQuota ملک.
{
  "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
  "blocks": [
    {
      "text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
    },
   {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Total Revenue",
            "dataType": "string"
          },
          {
            "header": "User Conversion Rate",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "99.9%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "$15,309.41"
              },
              {
                "value": "99.46%"
              }
            ]
          }
      }
    },
    {
      "text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
    },
    {
      "text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
    }
  ],
   "propertyQuota": {
    "tokensPerDay": {
      "consumed": 26849,
      "remaining": 3723151
    },
    "tokensPerHour": {
      "consumed": 26849,
      "remaining": 473151
    }
  }
}

مثال ۲: تشخیص خرابی مکالمه‌ای چندنوبتی

برای پرسیدن سؤال تعقیبی ضمن حفظ بافت، sessionId برگردانده‌شده توسط پاسخ قبلی را در درخواستتان بگنجانید.

سناریو: مقایسه با دوره قبلی

در ادامه مقایسه دستگاه قبلی، از «مشاور» می‌خواهید نتایج را با دوره قبلی مقایسه کند.

درخواست اچ‌تی‌تی‌پی

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
    "userQuery": "Compare results with the same period in the previous mounth."
  }'

پاسخ HTTP

«از مشاور بپرسید» از حافظه جلسه برای مرتبط کردن نتایج با دوره قبلی استفاده می‌کند.

{
  "sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
  "blocks": [
    {
      "text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
    },
    {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Metric",
            "dataType": "string"
          },
          {
            "header": "Jul 16 - Aug 15, 2026",
            "dataType": "string"
          },
          {
            "header": "Aug 16 - Sep 14, 2026",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "$19,565.46"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.90%"
              },
              {
                "value": "1.95%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$13,997.19"
              },
              {
                "value": "$15,309.41"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.95%"
              },
              {
                "value": "1.99%"
              }
            ]
          }
      }
    }
  ]
}

ساختار پاسخ و بلوک‌های داده

شیء ChatResponse عناصر ساختاریافته را در آرایه blocks برمی‌گرداند:

نوع مسدود کردن فیلد شرح
نوشتار روایی blocks[].text توضیح قابل‌خواندن برای انسان و نکته‌های تحلیلی سطح بالا.
جدول ساختاریافته blocks[].table تفکیک داده‌های جدولی حاوی headers (نام‌ها و انواع داده) و rows (مقادیر سلول).

انواع داده‌های سرایند جدول

ستون‌های blocks[].table.headers نوع داده معنایی را توصیف می‌کنند:

  • string: مقادیر نوشتاری طبقه‌بندی‌شده (مثلاً "desktop"، "/shop/apparel").
  • ‫float: اعداد ممیز شناور عددی.

مدیریت سهمیه گپ

درخواست‌های Ask Advisor براساس پیچیدگی پُرسمان، از نشان‌های گپ استفاده می‌کنند. وضعیت سهمیه فعلی در propertyQuota وقتی returnPropertyQuota برگردانده می‌شود که true:

  • tokensPerDay: حد روزانه کد و مانده باقی‌مانده.
  • tokensPerHour: حد نرخ پنجره لغزنده ساعتی و مانده باقی‌مانده.

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

روش properties.chat چندین معماری ادغام را در تیم‌ها و ابزارها باز می‌کند:

روبات‌های گپ و مشارکت سازمانی

فضای کاری گپ گروهی‌تان را مستقیماً به Google Analytics متصل کنید.

  • جلسه‌های رشته‌ای: sessionId را دربرابر شناسه رشته گپ ذخیره کنید تا به اعضای تیم اجازه دهید به‌صورت مشارکتی سؤالات پیگیری بپرسند.
  • پرداز کارت غنی: قالب table بلوک‌های پاسخ را به ابزارک‌های کارت تعاملی تبدیل می‌کند.

عامل‌های هوش مصنوعی خودکار و ابزارهای «پروتکل زمینه‌ای مدل» (MCP)

هماهنگ‌کننده‌های مدل زبانی بزرگ (مثل Gemini، ‏LangChain، یا Claude) را با ابزار تحلیلی GA مجهز کنید:

  • به‌جای اینکه مدل زبانی بزرگ را مجبور به تولید پُرسمان‌های پیچیده runReport کنیم، عامل مدل زبانی بزرگ می‌تواند روش chat را با قصد زبان طبیعی فراخوانی کند.
  • این عامل خلاصه‌هایی با واقعیت‌سنجی بالا و جدول‌های ساختاریافته دریافت می‌کند تا آن‌ها را در توصیه‌های بازاریابی چندکاناله ترکیب کند.

خلاصه اجرایی و هشدار خودکار

سرویس‌های زمان‌بندی‌شده‌ای ایجاد کنید که به‌طور پیش‌گیرانه ناهنجاری‌ها را بررسی می‌کنند:

  • یک کار cron روزانه این پُرسمان را اجرا می‌کند: «سنجه‌های عملکرد کلیدی دیروز را خلاصه کن و هرگونه کاهش غیرعادی در تبدیل‌ها را شناسایی کن.»
  • اگر ناهنجاری‌ای پیدا شود، دستورگان به‌طور خودکار پُرسمان پیگیری را برای تشخیص علت‌های ریشه‌ای راه‌اندازی می‌کند و خلاصه گزیده‌ای را در داشبوردهای داخلی یا سیستم‌های CRM پست می‌کند.

مراحل بعدی