# Alphana

> آلفانا یک پلتفرم فارسی تحلیل رفتار و محصول برای تیم‌های UI/UX، محصول، رشد، بازاریابی و توسعه است. این پلتفرم با SDK مرورگر، Session Replay، Heatmap، قیف تبدیل، تحلیل رویداد و Retention به تیم‌ها کمک می‌کند رفتار واقعی کاربران را به تصمیم محصولی تبدیل کنند. تفاوت اصلی را حفظ کنید: SDK برای جمع‌آوری telemetry یک App در مرورگر است، اما Public API برای دسترسی Server-side به داده‌های تحلیلی حساب استفاده می‌شود.

## Start Here

> برای فهم محصول از مستندات رسمی شروع کنید؛ برای کدنویسی از Quick Start و راهنمای Framework؛ برای دسترسی برنامه‌ای از Public API؛ و برای پرسش‌های AI از MCP استفاده کنید.

- [وب‌سایت آلفانا](https://alphana.ir/): معرفی آلفانا به‌عنوان پلتفرم فارسی تحلیل رفتار و محصول و توضیح قابلیت‌های اصلی آن.
- [مستندات آلفانا](https://alphana.ir/docs): فهرست رسمی و به‌روز راهنماهای SDK، Frameworkها، Public API، Widgetها، Feature Flag، آزمایش‌ها و MCP.
- [شروع کار با آلفانا](https://alphana.ir/docs/getting-started): مسیر راه‌اندازی App، دریافت `appId` و `secretKey`، اجرای نخستین Tracker و بررسی اولین درخواست collection.
- [SDK آلفانا](https://alphana.ir/docs/sdk): مرجع سطح‌بالای `alphana-sdk@2.0.7`، lifecycle، telemetry، package entryها و قابلیت‌های SDK.
- [Public API آلفانا](https://alphana.ir/docs/api): معرفی REST API نسخه‌دار برای Apps، Sessions و Growth و توضیح تفاوت آن با SDK و Dashboard API.
- [سرویس MCP آلفانا](https://alphana.ir/docs/mcp): اتصال دستیارهای AI به مستندات رسمی و به‌روز آلفانا از طریق MCP عمومی و فقط‌خواندنی.

## Getting Started

- [نصب SDK](https://alphana.ir/docs/getting-started/installation): نصب `alphana-sdk` با npm، pnpm، Yarn یا Bun و ساخت نخستین `UserTracker`.
- [نصب با Script و CDN](https://alphana.ir/docs/getting-started/script-cdn): نصب IIFE رسمی SDK با `<script>`، استفاده از `window.AlphanaSDK` و Command API بدون bundler.
- [راهنمای Frameworkها](https://alphana.ir/docs/frameworks): انتخاب روش مناسب برای React/Vite، Next.js، JavaScript ساده، WordPress و سایت‌های بدون bundler.
- [React و Vite](https://alphana.ir/docs/frameworks/react): قرار دادن `UserTrackerProvider`، استفاده از Hookها، ثبت Pageview و بررسی نصب در React و Vite.
- [Next.js App Router](https://alphana.ir/docs/frameworks/nextjs): اجرای Provider در Client Component، ثبت Navigation با `usePathname()` و تفکیک credentialهای Client و Server.
- [JavaScript و TypeScript ساده](https://alphana.ir/docs/frameworks/vanilla): استفاده مستقیم از `UserTracker`، ثبت Pageview، Goal، Revenue، Journey و کار با Command API.
- [WordPress](https://alphana.ir/docs/frameworks/wordpress): نصب افزونه Alphana Tracker، تنظیم App، استفاده از CDN manifest نسخه‌دار و شناسایی کاربران واردشده.
- [یکپارچه‌سازی‌های آلفانا](https://alphana.ir/integrations): مسیرهای نصب رسمی برای Next.js، React، WordPress و JavaScript.

## Core Concepts

- [تحلیل رفتار کاربران](https://alphana.ir/behavior-analytics): تفاوت تحلیل رفتار با آمار ترافیک و رابطه Heatmap، Session Replay، قیف و تحلیل محصول.
- [تحلیل محصول](https://alphana.ir/product-analytics): تعریف رویدادهای معنادار، فعال‌سازی، لحظه ارزش، Retention و اتصال داده به تصمیم محصول.
- [Retention](https://alphana.ir/docs/behavior/retention): رابطه `visitorId`، Sessionهای تکراری، `identify()`، Segmentها و محدودیت‌های تحلیل بین دستگاه‌ها.
- [قیف تبدیل](https://alphana.ir/funnels): تعریف مسیر مرحله‌ای Conversion، شناسایی محل ریزش و اتصال آن به Heatmap و Session Replay.
- [هیت مپ سایت](https://alphana.ir/heatmap): توضیح Heatmap کلیک، حرکت و اسکرول و روش تفسیر آن در صفحات، کمپین‌ها و فرم‌ها.
- [بازپخش نشست کاربران](https://alphana.ir/session-replay): مشاهده مسیر بازسازی‌شده کاربر برای یافتن اصطکاک، خطاهای فرم و علت ریزش.
- [قابلیت‌های آلفانا](https://alphana.ir/features): فهرست قابلیت‌های موجود یا در حال توسعه مانند Feature Flag، A/B Testing، Attribution، Retention و تحلیل محصول.

## Features

- [تحلیل رفتار و ترافیک](https://alphana.ir/features/behavior-and-traffic-analytics): تحلیل الگوهای رفتاری و ترافیک برای یافتن نقاط ضعف تجربه و مسیر تبدیل.
- [Feature Flags](https://alphana.ir/docs/feature-flags): ساخت، هدف‌گیری و ارزیابی Flagها برای rollout، kill switch و کنترل تجربه بدون deploy جدید.
- [A/B Testing](https://alphana.ir/docs/experiments): تعریف Experiment، Variant، Weight، Goal، Assignment پایدار و Conversion Window.
- [بهینه‌سازی تبدیل](https://alphana.ir/use-cases/conversion-optimization): چارچوب تبدیل یافته‌های رفتاری به فرضیه و اصلاح قابل‌اندازه‌گیری.

## SDKs

- [پیکربندی SDK](https://alphana.ir/docs/sdk/configuration): مرجع `TrackerConfig` شامل endpoint، Session، collection، Heatmap، batching، Replay، compression و consent.
- [Tracker API](https://alphana.ir/docs/sdk/tracker): فهرست متدهای `UserTracker` برای Pageview، Goal، Revenue، Journey، identify، Flag، آزمایش، Session و flush.
- [React Hooks](https://alphana.ir/docs/sdk/react-hooks): مرجع Hookهای `alphana-sdk/react` مانند `usePageView`، `useTrackGoal`، `useFeatureFlag` و `useAbVariant`.
- [حریم خصوصی و رضایت SDK](https://alphana.ir/docs/sdk/privacy): تنظیم consent، masking ورودی‌ها و متن، مسدودسازی بخش‌های Replay و تفکیک credential مرورگر و سرور.
- [ثبت Revenue](https://alphana.ir/docs/growth/revenue): ثبت رویدادهای مالی با `trackRevenue` یا `useTrackRevenue` و قرارداد مبلغ، ارز، تراکنش و وضعیت پرداخت.
- [UTM و Attribution](https://alphana.ir/docs/growth/utm): ثبت پارامترهای UTM، first-touch، last-touch و Click ID در context ترافیک و Attribution.

## Tracking / Data Collection

> برای نصب، ابتدا App و credential همان App را بسازید. `appId` و `secretKey` مربوط به SDK هستند؛ Account API Key با پیشوند `alphana_api_` فقط برای Public API سمت سرور است.

- [ویجت‌های داخل سایت](https://alphana.ir/docs/widgets): معماری و رفتار Cookie Consent، Feedback و Survey از طریق runtime config.
- [رضایت کوکی](https://alphana.ir/docs/widgets/cookie-consent): کنترل شروع collection بر اساس تصمیم کاربر درباره رضایت کوکی.
- [Feedback](https://alphana.ir/docs/widgets/feedback): نمایش Widget بازخورد با امتیازدهی و comment اختیاری.
- [Survey](https://alphana.ir/docs/widgets/survey): ساخت و نمایش نظرسنجی با سؤال‌های متنی، rating، single-choice و multi-choice.
- [هدف‌گیری Feature Flag](https://alphana.ir/docs/feature-flags/sdk-targeting): استفاده از `identify()`، عملگرهای `equals`، `contains` و `is_in` و منطق AND شرط‌ها.
- [استفاده از A/B Test در SDK](https://alphana.ir/docs/experiments/frameworks): APIهای Vanilla و React برای دریافت، refresh و خواندن Variantها.

## API

> برای integration سروری، ابتدا Authentication را بخوانید، سپس Appهای قابل‌دسترسی را با `GET /api/v1/apps` پیدا کنید و `appId` را به Queryهای تحلیلی بدهید.

- [احراز هویت Public API](https://alphana.ir/docs/api/authentication): ساخت و نگهداری Account API Key، Bearer Authentication، تفاوت `alphana_api_` با App Secret و JWT.
- [مرجع رسمی OpenAPI](https://api.alphana.ir/public/docs): قرارداد OAS نسخه 3 برای endpointها، پارامترها، schemaها، پاسخ‌ها و Status Codeهای Public Analytics API.
- [API اپلیکیشن‌ها](https://alphana.ir/docs/api/apps): فهرست Appهای owned یا shared و ساخت App جدید با `POST /api/v1/apps`.
- [API نشست‌ها](https://alphana.ir/docs/api/sessions): endpointهای Data Bounds، KPI، Pageview، Time Spent، رشد کاربران، Heatmap ترافیک و Location.
- [API رشد](https://alphana.ir/docs/api/growth): دریافت عملکرد ترکیب‌های UTM همراه Session و Visitor یکتا از `GET /api/v1/growth/utm`.
- [محدودیت نرخ و خطاهای API](https://alphana.ir/docs/api/rate-limits-errors): Rate Limit، Headerهای محدودیت، Statusهای 400 تا 429 و الگوی Retry با `Retry-After`.

## Integrations

- [Next.js](https://alphana.ir/integrations/nextjs): نصب SDK در App Router، دریافت credentialهای App، افزودن Provider به Layout و ثبت Navigation سمت Client.
- [React](https://alphana.ir/integrations/react): راه‌اندازی `UserTrackerProvider` در React/Vite و ثبت routeها با `usePageView`.
- [WordPress](https://alphana.ir/integrations/wordpress): فعال‌سازی افزونه رسمی، تنظیم App ID و Secret Key و بارگذاری SDK نسخه‌دار از CDN.
- [JavaScript](https://alphana.ir/integrations/javascript): نصب در HTML، Laravel Blade یا پروژه‌های بدون React با package یا build سراسری SDK.

## AI and Agents

- [MCP آلفانا](https://alphana.ir/docs/mcp#ai-agents): MCP عمومی و فقط‌خواندنی برای جست‌وجوی مستندات منتشرشده و دریافت Markdown صفحات رسمی.
- [Remote MCP Endpoint](https://alphana.ir/mcp): آدرس اتصال رسمی `https://alphana.ir/mcp` با transport نوع Streamable HTTP و بدون Authentication.

## Security and Privacy

- [امنیت و حریم خصوصی](https://alphana.ir/security): مسئولیت مشترک، حداقل‌سازی داده، کنترل دسترسی، masking در Replay و ملاحظات سازمانی.
- [سیاست حریم خصوصی آلفانا](https://alphana.ir/privacy-policy): سیاست رسمی حریم خصوصی محصول و نحوه برخورد با داده‌های کاربران.
- [راهکار سازمانی](https://alphana.ir/enterprise): مسیر بررسی فنی و سازمانی برای تیم‌هایی که نیاز به ارزیابی عمیق‌تر دارند.

## Troubleshooting

- بررسی نصب، Provider، CDN و WordPress در راهنماهای همان integration در بخش Getting Started توضیح داده شده است.
- [خطاهای Public API](https://alphana.ir/docs/api/rate-limits-errors#troubleshooting): تشخیص تفاوت 400، 401، 403، 404، 409 و 429 و جلوگیری از Retry Loop.

## Reference

- [فهرست قابلیت‌ها](https://alphana.ir/features#reference): وضعیت قابلیت‌های مستندشده و قابلیت‌هایی که هنوز صفحه تخصصی ندارند.

## Examples and Tutorials

- نمونه‌های نصب، SDK و API در صفحات Getting Started، SDK و API بالاترین اولویت retrieval را دارند.

## Changelog / Versioning

- [Manifest رسمی SDK](https://storage.alphana.ir/cdn/alphana-sdk/manifest.json): manifest رسمی برای یافتن build نسخه‌دار SDK، به‌ویژه در افزونه WordPress.
- [Sitemap رسمی](https://alphana.ir/sitemap.xml): sitemap و سیگنال‌های `lastmod` صفحات منتشرشده را نشان می‌دهد.

## Common Questions

- «چطور آلفانا را نصب کنم؟» → [نصب SDK](https://alphana.ir/docs/getting-started/installation#common-question-install)
- «چطور آلفانا را بدون npm روی سایت قرار دهم؟» → [نصب با Script و CDN](https://alphana.ir/docs/getting-started/script-cdn#common-question-cdn)
- «چطور آلفانا را در React راه‌اندازی کنم؟» → [React و Vite](https://alphana.ir/docs/frameworks/react#common-question-react)
- «چطور آلفانا را در Next.js App Router نصب کنم؟» → [Next.js App Router](https://alphana.ir/docs/frameworks/nextjs#common-question-nextjs)
- «چطور آلفانا را در WordPress نصب کنم؟» → [WordPress](https://alphana.ir/docs/frameworks/wordpress#common-question-wordpress)
- «چطور Pageview در SPA ثبت کنم؟» → [Tracker API](https://alphana.ir/docs/sdk/tracker#common-question-pageview)
- «تفاوت `secretKey` و Account API Key چیست؟» → [احراز هویت Public API](https://alphana.ir/docs/api/authentication#common-question-credentials)
- «چطور custom Goal ثبت کنم؟» → [React Hooks](https://alphana.ir/docs/sdk/react-hooks#common-question-goal)
- «چطور Revenue ثبت کنم؟» → [ثبت Revenue](https://alphana.ir/docs/growth/revenue#common-question-revenue)
- «چطور کاربر را با `identify()` شناسایی کنم؟» → [Retention](https://alphana.ir/docs/behavior/retention#common-question-identify)
- «چطور Feature Flag را هدف‌گیری کنم؟» → [SDK و هدف‌گیری Feature Flag](https://alphana.ir/docs/feature-flags/sdk-targeting#common-question-targeting)
- «چطور A/B Test را در React بخوانم؟» → [استفاده از آزمایش در SDK](https://alphana.ir/docs/experiments/frameworks#common-question-ab-test)
- «چطور داده‌های Session را از API بخوانم؟» → [API نشست‌ها](https://alphana.ir/docs/api/sessions#common-question-sessions)
- «چطور عملکرد کمپین‌های UTM را دریافت کنم؟» → [API رشد](https://alphana.ir/docs/api/growth#common-question-utm)
- «Public API چه Rate Limit و خطاهایی دارد؟» → [محدودیت نرخ و خطاهای API](https://alphana.ir/docs/api/rate-limits-errors#common-question-errors)
- «چطور به MCP آلفانا وصل شوم؟» → [سرویس MCP آلفانا](https://alphana.ir/docs/mcp#common-question-mcp)
- «آیا MCP به API Key نیاز دارد؟» → [احراز هویت Public API](https://alphana.ir/docs/api/authentication#common-question-mcp-auth)
- «چطور داده‌های حساس را در Session Replay پنهان کنم؟» → [حریم خصوصی و رضایت](https://alphana.ir/docs/sdk/privacy#common-question-masking)
- «تفاوت Heatmap و Session Replay چیست؟» → [بازپخش نشست کاربران](https://alphana.ir/session-replay#common-question-heatmap)
- «چطور محل ریزش کاربران را پیدا کنم؟» → [قیف تبدیل](https://alphana.ir/funnels#common-question-funnel)
- «چطور بفهمم کاربران روی صفحه به چه چیزی توجه می‌کنند؟» → [هیت مپ سایت](https://alphana.ir/heatmap#common-question-attention)

## Source Priority

1. [مرجع OpenAPI فعلی](https://api.alphana.ir/public/docs#source-priority) برای مسیرها، schemaها، پارامترها و Status Codeهای Public API.
2. مستندات رسمی جاری در `alphana.ir/docs` برای SDK، Frameworkها، API، Widgetها و قابلیت‌های فنی.
3. راهنماهای integration رسمی برای روش نصب متناسب با React، Next.js، WordPress یا JavaScript.
4. صفحات رسمی قابلیت‌ها برای تعریف محصولی Heatmap، Session Replay، قیف، تحلیل محصول و Retention.
5. صفحات قیمت‌گذاری، امنیت و سازمانی برای ظرفیت، ملاحظات خرید و مسئولیت‌های عملیاتی.

اگر بین یک نمونه قدیمی و قرارداد فعلی اختلاف وجود داشت، مرجع OpenAPI، مستندات نسخه فعلی SDK و راهنمای نسخه‌دار جدیدتر مقدم هستند. APIهای داخلی Dashboard و endpointهای مشاهده‌شده در Network Dashboard، قرارداد Public API محسوب نمی‌شوند.

## Freshness

مستندات SDK در زمان بررسی نسخه `2.0.7` را مرجع قرار می‌دهند. برای CDN، مسیر `latest` ممکن است با انتشارهای بعدی تغییر کند؛ در Production از URL نسخه‌دار و manifest رسمی استفاده کنید. برای Public API، مسیرهای `/api/v1/*` و OpenAPI فعلی را بر مسیرهای داخلی یا نمونه‌های قدیمی ترجیح دهید.

## Markdown Alternatives

صفحات HTML مستندات در این فایل canonical هستند. MCP آلفانا ابزار `get_doc` را برای دریافت Markdown کامل هر صفحه ارائه می‌کند و برای مصرف AI، در صورت دسترسی Client، باید از آن برای بازیابی محتوای صفحه رسمی استفاده شود.

## MCP

- [نمای کلی MCP آلفانا](https://alphana.ir/docs/mcp#mcp-overview): توضیح هدف MCP، پوشش مستندات، عمومی و فقط‌خواندنی بودن و نبود نیاز به Account API Key.
- [Remote MCP Endpoint](https://alphana.ir/mcp#connection): آدرس اتصال رسمی `https://alphana.ir/mcp` با transport نوع Streamable HTTP.
- [ابزارهای MCP](https://alphana.ir/docs/mcp#tools): ابزارهای `search_docs`، `get_doc`، `list_docs` و `get_api_endpoint`.
- [محدوده دسترسی MCP](https://alphana.ir/docs/mcp#scope): MCP فقط مستندات عمومی را می‌خواند و به Dashboard، Analytics مشتری، Database، Filesystem یا URL دلخواه دسترسی ندارد.