API نشست‌ها

Queryهای تحلیلی Session، KPI، Pageview، Time Spent، رشد، Traffic و Location.

API نشست‌ها برای خواندن بخش اصلی داده‌های تحلیلی هر App از Public API آلفانا استفاده می‌شود.

این گروه از endpointها اطلاعاتی مثل محدوده زمانی داده، KPIهای Session، Pageviewها، Time Spent، روند رشد کاربران، الگوی Traffic و Location را در اختیار Backend یا integration شما قرار می‌دهد.

تمام endpointهای این بخش به پارامتر اجباری appId نیاز دارند. مقدار appId باید یک UUID معتبر و متعلق به Appی باشد که Account API Key فعلی به آن دسترسی دارد.

اگر appId موردنظر را نمی‌دانید، ابتدا فهرست Appهای قابل‌دسترسی را از endpoint زیر دریافت کنید:

text

GET /api/v1/apps

سپس مقدار id App موردنظر را در Queryهای Session استفاده کنید.

پارامترهای زمانی#

بخشی از endpointهای Session از قرارداد PublicRangeQueryDto استفاده می‌کنند.

در این endpointها می‌توانید دو پارامتر اختیاری زیر را ارسال کنید:

text

from
to

هر دو مقدار باید با قالب ISO 8601 ارسال شوند.

برای مثال:

text

from=2026-07-01T00:00:00.000Z
to=2026-07-31T23:59:59.999Z

کران‌های زمانی from و to شامل هستند؛ یعنی داده‌هایی که دقیقاً روی ابتدا یا انتهای بازه قرار گرفته‌اند نیز در Query محاسبه می‌شوند.

اگر یک endpoint از PublicRangeQueryDto استفاده نکند، نباید فرض کنید from و to روی آن اثر دارند. بعضی گزارش‌ها Window زمانی ثابت و منطق زمانی اختصاصی خودشان را دارند.

Endpointهای Session#

مسیر	نکته معنایی
`GET /api/v1/sessions/data-bounds`	قدیمی‌ترین و جدیدترین زمان موجود برای App را برمی‌گرداند؛ اگر داده‌ای وجود نداشته باشد مقدارها می‌توانند `null` باشند
`GET /api/v1/sessions/overview/extended`	نمای چندبخشی از رفتار کاربران و کیفیت تجربه در بازه موردنظر
`GET /api/v1/sessions/overview/kpis`	KPIهای `current`، `previous` و `change` را برمی‌گرداند؛ بدون Range، مقایسه امروز و دیروز بر اساس UTC انجام می‌شود
`GET /api/v1/sessions/pageviews`	تعداد View و Sessionهای یکتا را به تفکیک `path` برمی‌گرداند
`GET /api/v1/sessions/timespent`	زمان کل و میانگین Time Spent را بر حسب میلی‌ثانیه برمی‌گرداند
`GET /api/v1/sessions/user-growth`	Metricهای روزانه رشد را بر اساس روزهای UTC محاسبه می‌کند
`GET /api/v1/sessions/traffic-heatmap`	Heatmap ترافیک را در یک Window ثابت هفت‌روزه بر اساس timezone `Asia/Tehran` برمی‌گرداند و `from` / `to` نمی‌پذیرد
`GET /api/v1/sessions/traffic-audience-activity`	میانگین فعالیت کاربران را بر اساس روز و ساعت در Window غلتان ۲۸روزه تهران محاسبه می‌کند
`GET /api/v1/sessions/locations/all`	Locationهای دارای مختصات را برمی‌گرداند و نتیجه را بر اساس `count` مرتب می‌کند

Data Bounds#

برای اینکه قبل از اجرای Queryهای تحلیلی بدانید App در چه بازه‌ای داده دارد، می‌توانید از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/data-bounds

این endpoint قدیمی‌ترین و جدیدترین Timestamp موجود برای App را برمی‌گرداند.

اگر App هنوز هیچ داده‌ای نداشته باشد، مقدارهای مربوط به ابتدا و انتهای داده می‌توانند null باشند.

این endpoint برای ساخت Date Picker یا انتخاب بازه اولیه در Dashboardهای سفارشی مفید است؛ چون به شما اجازه می‌دهد Range را بر اساس محدوده واقعی داده تنظیم کنید.

برای مثال، به‌جای اینکه همیشه یک بازه ثابت را فرض کنید، ابتدا Data Bounds را دریافت کنید و بعد Queryهای تحلیلی را در همان محدوده اجرا کنید.

Overview Extended#

endpoint زیر یک نمای چندبخشی از وضعیت Sessionها و رفتار کاربران ارائه می‌کند:

text

GET /api/v1/sessions/overview/extended

این endpoint برای زمانی مناسب است که به‌جای یک Metric مشخص، به یک Overview وسیع‌تر از داده‌های App نیاز دارید.

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

اگر فقط یک KPI یا Metric مشخص لازم دارید، endpointهای تخصصی‌تر این بخش معمولاً انتخاب مستقیم‌تری هستند.

KPIها#

برای دریافت KPIهای اصلی Session از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/overview/kpis

پاسخ این endpoint سه بخش مفهومی دارد:

text

current
previous
change

current مقدار مربوط به بازه فعلی است.

previous بازه قبلی متناظر را نشان می‌دهد.

change تفاوت یا تغییر بین این دو دوره را در اختیار شما قرار می‌دهد.

اگر from و to ارسال نشوند، رفتار پیش‌فرض endpoint مقایسه امروز با دیروز بر اساس UTC است.

این نکته مهم است، چون ممکن است timezone محصول یا Dashboard شما Asia/Tehran باشد اما این endpoint در حالت بدون Range از مرز روز UTC استفاده کند.

اگر مقایسه زمانی مشخصی می‌خواهید، بهتر است Range را صریح ارسال کنید.

Pageviews#

برای تحلیل بازدید صفحه‌ها از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/pageviews

داده به تفکیک path گروه‌بندی می‌شود و برای هر مسیر اطلاعاتی مثل تعداد View و Sessionهای یکتا در اختیار شما قرار می‌گیرد.

به این ترتیب می‌توانید تفاوت بین حجم کل بازدید و تعداد Sessionهایی که واقعاً آن صفحه را دیده‌اند بررسی کنید.

برای مثال، یک Path ممکن است:

text

views: 1200
sessions: 730

داشته باشد.

این تفاوت نشان می‌دهد بعضی Sessionها همان صفحه را بیش از یک‌بار دیده‌اند.

Pageviewها برای سؤال‌هایی مثل این مناسب‌اند:

کدام صفحه بیشترین View را داشته است؟
کدام Path در Sessionهای بیشتری دیده شده؟
آیا کاربران در یک Session چندبار به صفحه خاصی برمی‌گردند؟
کدام مسیرها سهم بیشتری از Traffic داخلی محصول دارند؟

Time Spent#

برای دریافت زمان حضور کاربران از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/timespent

زمان‌ها در این endpoint بر حسب میلی‌ثانیه هستند.

گزارش شامل Metricهایی برای زمان کل و میانگین Time Spent است.

بنابراین اگر مقدار زمان را در UI نمایش می‌دهید، معمولاً لازم است آن را از میلی‌ثانیه به واحد خواناتری مثل ثانیه یا دقیقه تبدیل کنید.

برای مثال:

typescript

const seconds = milliseconds / 1000;
const minutes = milliseconds / 60000;

تبدیل واحد فقط در لایه نمایش انجام شود و داده خام API را بدون نیاز تغییر ندهید.

Time Spent را بهتر است در کنار Pageview یا نوع صفحه تحلیل کنید. زمان بیشتر همیشه به معنای تجربه بهتر نیست؛ ممکن است نشانه درگیری بیشتر باشد یا در بعضی مسیرها اصطکاک و سردرگمی را نشان دهد.

User Growth#

برای مشاهده روند روزانه Metricهای رشد از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/user-growth

این endpoint داده را بر اساس روزهای UTC گروه‌بندی می‌کند.

یعنی مرز شروع و پایان هر روز با timezone UTC محاسبه می‌شود، نه timezone مرورگر یا Asia/Tehran.

اگر داده را در Dashboardی با timezone محلی نمایش می‌دهید، این تفاوت را هنگام Label کردن تاریخ‌ها و مقایسه گزارش‌ها در نظر بگیرید.

این endpoint برای رسم Trendهای زمانی و بررسی تغییر رفتار یا حجم کاربران در طول چند روز مناسب است.

Traffic Heatmap#

endpoint زیر الگوی زمانی Traffic را در یک ساختار Heatmap ارائه می‌کند:

text

GET /api/v1/sessions/traffic-heatmap

برخلاف بسیاری از endpointهای دیگر Session، این گزارش Range دلخواه دریافت نمی‌کند.

Window زمانی آن ثابت و هفت‌روزه است و محاسبات زمانی بر اساس timezone زیر انجام می‌شوند:

text

Asia/Tehran

بنابراین پارامترهای:

text

from
to

برای این endpoint کاربرد ندارند.

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

برای مثال می‌توانید ببینید Traffic سایت در چه ساعت‌هایی از شبانه‌روز بیشتر است یا تفاوت رفتار روزهای هفته چگونه دیده می‌شود.

Audience Activity#

برای بررسی الگوی فعالیت Audience از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/traffic-audience-activity

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

Window گزارش به‌صورت غلتان و ۲۸روزه است و مبنای زمانی آن timezone تهران است.

به‌صورت مفهومی:

text

28-day rolling window
+
Asia/Tehran
+
day/hour averages

این گزارش برای درک الگوی معمول فعالیت کاربران مفید است، نه فقط Traffic یک روز خاص.

برای مثال می‌توانید بررسی کنید کاربران معمولاً در کدام روزهای هفته یا چه ساعت‌هایی فعال‌تر هستند.

تفاوت Traffic Heatmap و Audience Activity#

هر دو endpoint به زمان فعالیت کاربران نگاه می‌کنند، اما Window و معنای آن‌ها یکسان نیست.

traffic-heatmap یک پنجره ثابت هفت‌روزه دارد.

traffic-audience-activity از یک پنجره غلتان ۲۸روزه برای محاسبه میانگین روز و ساعت استفاده می‌کند.

در نتیجه، اولی بیشتر تصویر فعالیت اخیر را نشان می‌دهد و دومی برای پیدا کردن الگوی پایدارتر Audience مناسب‌تر است.

هنگام ساخت Dashboard این دو گزارش را با یک Label یکسان نمایش ندهید، چون Window زمانی آن‌ها متفاوت است.

Locations#

برای دریافت Locationهای ثبت‌شده از endpoint زیر استفاده کنید:

text

GET /api/v1/sessions/locations/all

این endpoint فقط Locationهایی را برمی‌گرداند که مختصات لازم را داشته باشند.

نتیجه بر اساس count مرتب می‌شود تا Locationهایی که تعداد بیشتری دارند زودتر در پاسخ دیده شوند.

این داده می‌تواند برای مواردی مثل:

نقشه پراکندگی کاربران
تحلیل منطقه‌ای Traffic
مقایسه Locationهای پرتکرار
ساخت گزارش جغرافیایی داخلی

استفاده شود.

نبود یک Location در این پاسخ الزاماً به معنای نبود Visitor از آن منطقه نیست؛ این endpoint فقط رکوردهایی را ارائه می‌کند که Location معتبر و مختصات موردنیاز در داده آن‌ها وجود داشته باشد.

`appId` در همه درخواست‌ها#

تمام endpointهای این بخش به appId نیاز دارند.

برای مثال:

curl

curl --get https://api.alphana.ir/api/v1/sessions/pageviews \
  -H "Authorization: Bearer $ALPHANA_API_KEY" \
  --data-urlencode "appId=11111111-1111-4111-8111-111111111111"

اگر endpoint از Range پشتیبانی کند، می‌توانید from و to را نیز اضافه کنید:

curl

curl --get https://api.alphana.ir/api/v1/sessions/pageviews \
  -H "Authorization: Bearer $ALPHANA_API_KEY" \
  --data-urlencode "appId=11111111-1111-4111-8111-111111111111" \
  --data-urlencode "from=2026-07-01T00:00:00.000Z" \
  --data-urlencode "to=2026-07-31T23:59:59.999Z"

قبل از استفاده از یک Range روی هر endpoint، قرارداد همان endpoint را بررسی کنید.

Scope دسترسی#

داشتن UUID معتبر برای appId به‌تنهایی کافی نیست.

Account API Key باید به همان App دسترسی داشته باشد؛ یعنی App یا متعلق به همان حساب باشد یا با آن Share شده باشد.

اگر حساب اجازه دسترسی به App را نداشته باشد، Public API می‌تواند درخواست را با خطای Authorization رد کند.

برای پیدا کردن Appهای قابل‌دسترسی، همیشه می‌توانید از:

text

GET /api/v1/apps

استفاده کنید.

تفاوت timezoneها#

یکی از نکات مهم API نشست‌ها این است که تمام endpointها از یک timezone واحد استفاده نمی‌کنند.

برای مثال:

Endpoint / حالت	مبنای زمانی
`overview/kpis` بدون Range	امروز / دیروز UTC
`user-growth`	روزهای UTC
`traffic-heatmap`	`Asia/Tehran`
`traffic-audience-activity`	`Asia/Tehran`
endpointهای دارای `from` / `to`	Timestamp صریح ISO 8601 ارسال‌شده توسط Client

اگر چند گزارش را در یک Dashboard کنار هم نمایش می‌دهید، timezone هرکدام را در نظر بگیرید تا تفاوت مرز روز باعث برداشت اشتباه از داده نشود.

انتخاب endpoint مناسب#

برای اینکه فقط داده موردنیاز را دریافت کنید، endpoint را بر اساس سؤال تحلیلی انتخاب کنید:

محدوده واقعی داده چیست؟ → data-bounds
یک Overview چندبخشی می‌خواهم → overview/extended
KPI و تغییر دوره‌ای می‌خواهم → overview/kpis
کدام صفحات بیشتر دیده شده‌اند؟ → pageviews
کاربران چقدر زمان صرف کرده‌اند؟ → timespent
روند روزانه چگونه تغییر کرده؟ → user-growth
Traffic اخیر در چه روز و ساعتی بیشتر است؟ → traffic-heatmap
الگوی معمول فعالیت Audience چیست؟ → traffic-audience-activity
کاربران از چه Locationهایی هستند؟ → locations/all

این تفکیک کمک می‌کند به‌جای دریافت داده زیاد و پردازش غیرضروری در Client، از endpointی استفاده کنید که مستقیماً برای همان سؤال طراحی شده است.

نکات اجرایی#

برای استفاده پایدارتر از API نشست‌ها:

appId را از GET /api/v1/apps دریافت کنید و از UUID حدسی استفاده نکنید.
from و to را فقط برای endpointهایی ارسال کنید که Range می‌پذیرند.
Timestampها را با قالب کامل ISO 8601 ارسال کنید.
واحد Time Spent را میلی‌ثانیه در نظر بگیرید.
تفاوت UTC و Asia/Tehran را بین گزارش‌های مختلف فراموش نکنید.
روی traffic-heatmap و traffic-audience-activity Range سفارشی فرض نکنید.
پاسخ‌های خالی و مقدارهای null مثل Data Bounds یک App بدون داده را در Client مدیریت کنید.
Account API Key را فقط در Backend نگهداری کنید.

API نشست‌ها

پارامترهای زمانی#

Endpointهای Session#

Data Bounds#

Overview Extended#

KPIها#

Pageviews#

Time Spent#

User Growth#

Traffic Heatmap#

Audience Activity#

تفاوت Traffic Heatmap و Audience Activity#

Locations#

appId در همه درخواست‌ها#

Scope دسترسی#

تفاوت timezoneها#

انتخاب endpoint مناسب#

نکات اجرایی#

`appId` در همه درخواست‌ها#