رفتن به محتوای اصلی
آلفاناDocs

Public API آلفانا

مرجع امن APIهای نسخه‌دار Apps، Sessions و Growth با استفاده از Account API Key.

Public API آلفانا برای دسترسی Server-side به داده‌ها و قابلیت‌های تحلیلی حساب طراحی شده است. از طریق این API می‌توانید Appهای قابل‌دسترسی را مدیریت کنید، داده‌های Session و KPIها را بخوانید و گزارش‌های Growth را در سیستم‌ها، داشبوردها یا ابزارهای داخلی خودتان استفاده کنید.

Base URL اصلی Public Analytics API:

text
https://api.alphana.ir

Endpointهای Public API نسخه‌دار هستند و در حال حاضر از مسیر زیر ارائه می‌شوند:

```text
/api/v1/*

id: api نسخه‌دار بودن مسیرها کمک می‌کند قرارداد integration از APIهای داخلی و تغییرات پیاده‌سازی Backend جدا بماند.

مرجع OpenAPI مربوط به Backend نیز از آدرس زیر در دسترس است:

text
https://api.alphana.ir/public/docs

این مرجع برای بررسی schemaها، پارامترها، responseها و قرارداد فنی endpointهای Public API قابل استفاده است.

گروه‌های Public API#

Endpointهای فعلی Public API در سه گروه اصلی قرار می‌گیرند:

Apps#

APIهای Apps برای پیدا کردن Appهایی که حساب شما به آن‌ها دسترسی دارد و در صورت نیاز ساخت App جدید استفاده می‌شوند.

از این بخش می‌توانید:

  • فهرست Appهای متعلق به حساب را دریافت کنید
  • Appهایی را که با همان حساب Share شده‌اند ببینید
  • appId موردنیاز برای Queryهای تحلیلی را پیدا کنید
  • از طریق API یک App جدید بسازید

برای جزئیات بیشتر، API اپلیکیشن‌ها را ببینید.

Sessions#

APIهای Sessions برای دسترسی به بخش‌های مختلف داده‌های تحلیلی یک App استفاده می‌شوند.

این گروه داده‌هایی مثل موارد زیر را پوشش می‌دهد:

  • KPIهای Session
  • Pageviewها
  • Time Spent
  • روند رشد
  • داده‌های Heatmap Traffic
  • فعالیت Visitorها
  • Location

این endpointها برای زمانی مناسب‌اند که بخواهید بخشی از گزارش‌های آلفانا را در Dashboard داخلی، ابزار BI یا Workflowهای Server-side خودتان استفاده کنید.

Growth#

APIهای Growth برای تحلیل داده‌های مربوط به جذب کاربر و Campaignها طراحی شده‌اند.

در نسخه فعلی، این بخش امکان دریافت عملکرد ترکیب‌های UTM را فراهم می‌کند؛ از جمله Source، Medium، Campaign، Term و Content در کنار تعداد Sessionها و Visitorهای یکتا.

برای جزئیات بیشتر، API رشد را ببینید.

احراز هویت#

تمام عملیات Public API به Account API Key نیاز دارند.

کلید باید در Header درخواست به‌صورت Bearer Token ارسال شود:

text
Authorization: Bearer YOUR_ALPHANA_API_KEY

Account API Keyهای آلفانا با پیشوند زیر ساخته می‌شوند:

text
alphana_api_

برای مثال:

curl
curl https://api.alphana.ir/api/v1/apps \
  -H "Authorization: Bearer $ALPHANA_API_KEY" \
  -H "Accept: application/json"

این Credential باید فقط در Backend یا محیط امن Server نگهداری شود.

جزئیات ساخت و نگهداری کلید در احراز هویت Public API توضیح داده شده است.

محدوده دسترسی#

Account API Key در context همان حساب عمل می‌کند.

درخواست‌های Public API می‌توانند به Appهایی دسترسی داشته باشند که:

  • متعلق به حساب متصل به API Key هستند
  • یا با همان حساب Share شده‌اند

بنابراین داشتن یک appId به‌تنهایی برای خواندن داده کافی نیست؛ Account API Key نیز باید به همان App دسترسی داشته باشد.

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

text
GET /api/v1/apps

سپس مقدار id مربوط به App موردنظر را به‌عنوان appId در Queryهای تحلیلی استفاده کنید.

Public API با SDK API متفاوت است#

Public API و endpointهایی که SDK آلفانا برای collection استفاده می‌کند دو قرارداد متفاوت هستند.

SDK مرورگر برای ارسال telemetry از App Credential و endpointهای مخصوص ingestion استفاده می‌کند.

در مقابل، Public API برای درخواست‌های Server-side و خواندن یا مدیریت داده‌های سطح حساب طراحی شده است و از Account API Key استفاده می‌کند.

به‌صورت خلاصه:

APIکاربردCredential
Public APIintegrationهای Server-side و داده‌های تحلیلیAccount API Key
SDK APIcollection و ingestion داده‌های VisitorApp secretKey
Dashboard APIعملیات مدیریتی داخلیJWT

این سه جریان را با یکدیگر جایگزین نکنید.

Public API با Dashboard API متفاوت است#

Dashboard آلفانا از APIهای مدیریتی داخلی استفاده می‌کند که با JWT محافظت می‌شوند.

این endpointها بخشی از قرارداد Public Integration نیستند و ممکن است برای نیازهای داخلی Dashboard طراحی شده باشند.

اگر در حال ساخت integration خارجی هستید، فقط از endpointهایی استفاده کنید که صراحتاً در مستندات Public API معرفی شده‌اند.

استفاده مستقیم از Network Requestهای Dashboard به‌عنوان API عمومی می‌تواند integration شما را به جزئیات داخلی محصول وابسته کند.

قرارداد نسخه‌دار#

مسیرهای Public API زیر namespace نسخه‌دار قرار دارند:

text
/api/v1/*

Integration خود را بر اساس همین endpointهای مستندشده بسازید و از مسیرهای داخلی یا بدون قرارداد به‌عنوان جایگزین استفاده نکنید.

برای مشاهده فهرست endpointهای Public Integration، مرجع endpointها را ببینید.

OpenAPI#

مرجع OpenAPI Backend از آدرس زیر در دسترس است:

text
https://api.alphana.ir/public/docs

از این مرجع می‌توانید برای بررسی جزئیات فنی endpointها استفاده کنید؛ مثل:

  • HTTP Method
  • Query Parameterها
  • Request Body
  • Response Schema
  • Status Codeها
  • قرارداد DTOها

اگر بین یک نمونه قدیمی و قرارداد فعلی API اختلافی وجود داشت، endpoint مستندشده فعلی و OpenAPI منتشرشده را مبنای integration قرار دهید.

جریان پیشنهادی integration#

برای شروع کار با Public API، این مسیر معمولاً کافی است:

  1. در داشبورد یک Account API Key بسازید.
  2. کلید را در Secret Manager یا Environment امن Backend نگهداری کنید.
  3. با GET /api/v1/apps Appهای قابل‌دسترسی را دریافت کنید.
  4. id App موردنظر را به‌عنوان appId انتخاب کنید.
  5. Endpoint تحلیلی موردنیاز را از گروه Sessions یا Growth فراخوانی کنید.
  6. فقط از endpointهایی استفاده کنید که در قرارداد Public API مستند شده‌اند.
  7. Account API Key را هرگز به Client یا SDK مرورگر منتقل نکنید.