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

شروع کار با آلفانا

مسیر کوتاه و منبع‌محور برای نصب SDK، دریافت شناسه‌های اپ و دیدن نخستین داده‌ها.

آلفانا رفتار کاربران را از طریق SDK مرورگر جمع‌آوری می‌کند و داده‌های ثبت‌شده را برای ساخت گزارش‌ها و تحلیل‌های رفتاری به داشبورد می‌فرستد.

برای شروع، به یک App فعال در آلفانا و دو مقدار مربوط به همان App یعنی appId و secretKey نیاز دارید. این اطلاعات مشخص می‌کنند داده‌های SDK به کدام App در آلفانا تعلق دارند.

پس از نصب و راه‌اندازی Tracker، رفتارهایی مثل Pageview، Navigation و سایر telemetryهای فعال SDK ثبت می‌شوند و می‌توانید نخستین داده‌ها را در داشبورد بررسی کنید.

مسیر پیشنهادی#

برای اینکه نصب را با کمترین تنظیمات شروع کنید، این مسیر را دنبال کنید:

  1. در داشبورد آلفانا یک App بسازید و دامنه واقعی وب‌سایتی را که قرار است SDK روی آن اجرا شود ثبت کنید.

  2. نسخه alphana-sdk@2.0.7 را با Package Manager پروژه نصب کنید. اگر پروژه شما از Package Manager استفاده نمی‌کند، می‌توانید از فایل IIFE رسمی SDK استفاده کنید.

  3. با appId و secretKey همان App یک instance از UserTracker بسازید و init() را فقط یک‌بار در lifecycle مناسب برنامه اجرا کنید.

  4. اگر محصول شما SPA است و تغییر مسیرها بدون reload کامل صفحه انجام می‌شوند، Navigation و Pageviewهای لازم را با usePageView() ثبت کنید.

  5. بعد از اجرای سایت، DevTools مرورگر را باز کنید و در بخش Network بررسی کنید که درخواست زیر با موفقیت ارسال می‌شود:

text
POST /api/collect

رسیدن این درخواست به backend اولین نشانه فنی است که Tracker راه‌اندازی شده و داده‌ها در حال ورود به pipeline آلفانا هستند.

## ساخت App و دریافت شناسه‌ها

هر نصب SDK باید به یک App مشخص در آلفانا متصل باشد.
id: getting-started
بعد از ساخت App در داشبورد، `appId` و `secretKey` مربوط به همان App را در تنظیمات Tracker استفاده کنید:

```typescript
const tracker = new UserTracker({
  appId: "YOUR_APP_ID",
  secretKey: "YOUR_APP_SECRET",
});

tracker.init();

appId مشخص می‌کند داده‌ها برای کدام App ثبت شوند و secretKey برای ingestion داده‌های همان App توسط SDK استفاده می‌شود.

همچنین دامنه‌ای که SDK روی آن اجرا می‌شود باید با دامنه ثبت‌شده برای App هماهنگ باشد.

فقط یک‌بار init()#

برای هر instance از Tracker، init() را فقط یک‌بار اجرا کنید.

اجرای init() چرخه اصلی SDK را شروع می‌کند، pluginهای فعال را راه می‌اندازد و collection و flush دوره‌ای را فعال می‌کند.

typescript
tracker.init();

اگر Tracker را در Frameworkهایی مثل React یا Next.js راه‌اندازی می‌کنید، آن را در جایی قرار دهید که با هر Render یا Navigation دوباره ساخته و initialize نشود.

راه‌اندازی چندباره Tracker می‌تواند باعث ایجاد listenerهای تکراری یا ثبت چندباره بعضی رفتارها شود.

بررسی نخستین داده‌ها#

بعد از راه‌اندازی SDK، سایت را باز کنید و چند تعامل عادی انجام دهید؛ برای مثال بین صفحات حرکت کنید یا روی بخش‌های مختلف سایت کلیک کنید.

سپس در DevTools مرورگر وارد بخش Network شوید و درخواست‌های collection را بررسی کنید.

در نسخه فعلی، جریان اصلی داده‌های SDK از endpoint زیر عبور می‌کند:

text
POST /api/collect

اگر درخواست با موفقیت ارسال می‌شود، Tracker توانسته با backend آلفانا ارتباط برقرار کند.

بعد از آن می‌توانید وارد داشبورد شوید و بررسی کنید که Sessionها، Pageviewها و سایر داده‌های فعال برای App ظاهر می‌شوند.

SPA و Navigation#

در سایت‌های معمولی، reload صفحه می‌تواند Pageview جدید را به‌صورت طبیعی ایجاد کند. اما در SPAها، تغییر Route معمولاً بدون reload کامل مرورگر انجام می‌شود.

اگر از React یا Frameworkهایی مثل Next.js استفاده می‌کنید، مطمئن شوید Navigationهای داخلی به‌درستی ثبت می‌شوند.

در integrationهای React می‌توانید برای این کار از usePageView() استفاده کنید.

tsx
usePageView(path);

ثبت درست Routeها اهمیت زیادی دارد، چون Pageview و Navigation پایه بسیاری از تحلیل‌های بعدی مثل Journey، Attribution و رفتار Session هستند.

تفاوت secretKey و Account API Key#

secretKey مربوط به App با Account API Key یکسان نیست.

اگر فقط در حال نصب SDK روی سایت هستید، از credentialهای مربوط به همان App استفاده کنید و Account API Key را وارد کد Client نکنید.

قدم بعدی#

بعد از اینکه نخستین داده‌ها را دریافت کردید، می‌توانید integration را بر اساس ساختار پروژه خود کامل‌تر کنید:

  • نصب پکیج — نصب SDK با Package Manager و راه‌اندازی اولیه
  • نصب Script و CDN — استفاده از SDK بدون Package Manager
  • React — استفاده از Provider و Hookهای React
  • Next.js — ثبت درست SDK و Navigation در Next.js
  • مرجع SDK — تنظیمات، متدهای Tracker، React Hooks و رفتارهای نسخه فعلی