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

نصب SDK

نصب نسخه فعلی alphana-sdk با npm، pnpm، Yarn یا Bun و راه‌اندازی نخستین Tracker.

نسخه فعلی پکیج alphana-sdk در این مخزن 2.0.7 است. این پکیج دو ورودی اصلی منتشر می‌کند:

  • alphana-sdk برای استفاده مستقیم از UserTracker و APIهای اصلی SDK
  • alphana-sdk/react برای استفاده از UserTrackerProvider و Hookهای مخصوص React

اگر پروژه شما با یکی از Package Managerهای رایج JavaScript مدیریت می‌شود، می‌توانید SDK را مستقیماً به dependencies پروژه اضافه کنید.

نصب پکیج#

بسته به Package Manager پروژه، یکی از فرمان‌های زیر را اجرا کنید:

bash
# npm
npm install alphana-sdk

# pnpm
pnpm add alphana-sdk

# Yarn
yarn add alphana-sdk

# Bun
bun add alphana-sdk

پس از نصب، می‌توانید `UserTracker` را از ورودی اصلی پکیج import کنید و اتصال اولیه پروژه به آلفانا را راه‌اندازی کنید.

## اجرای پایه

برای شروع، یک instance از `UserTracker` بسازید و `appId` و `secretKey` مربوط به App خود را در اختیار آن قرار دهید:
id: getting-started-installation
```typescript
import { UserTracker } from "alphana-sdk";

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

appId و secretKey باید متعلق به همان Appی باشند که در داشبورد آلفانا ساخته‌اید. همچنین دامنه‌ای که SDK روی آن اجرا می‌شود باید با دامنه ثبت‌شده برای App هماهنگ باشد.

فراخوانی init() چرخه اصلی Tracker را شروع می‌کند؛ pluginهای فعال راه‌اندازی می‌شوند، collection آغاز می‌شود و flush دوره‌ای Eventهای ثبت‌شده فعال خواهد شد.

مقدار برگشتی init()#

متد init() همان instance فعلی UserTracker را برمی‌گرداند.

به همین دلیل می‌توانید ساخت Tracker و initialization را به‌صورت زنجیره‌ای انجام دهید:

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

بعد از آن، همان متغیر tracker برای فراخوانی متدهایی مثل trackGoal()، trackRevenue()، identify() یا flush() قابل استفاده است.

برای مثال:

typescript
tracker.trackGoal({
  key: "signup_completed",
});

پایان دادن به Tracker#

اگر integration شما lifecycle مشخصی دارد و لازم است Tracker به‌طور کامل متوقف شود، می‌توانید destroy() را فراخوانی کنید:

typescript
tracker.destroy();

destroy() listenerها و timerهای ایجادشده توسط Tracker را پاک می‌کند و پیش از پایان، flush نهایی را انجام می‌دهد.

این متد معمولاً زمانی کاربرد دارد که integration به‌طور کامل از صفحه خارج می‌شود، Tracker دیگر نباید فعال بماند یا در Framework موردنظر unmount نهایی اتفاق می‌افتد.

در integrationهای معمول وب، Tracker باید در سطحی initialize شود که با هر Render یا تغییر Route دوباره ساخته نشود.

فقط یک‌بار initialize کنید#

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

ساخت یا initialize کردن چندباره Tracker می‌تواند باعث ایجاد listenerهای تکراری، timerهای اضافه یا ثبت چندباره بعضی رفتارها شود.

برای مثال، در Frameworkهایی مثل React یا Next.js بهتر است Tracker را در سطحی پایدار از application lifecycle ایجاد کنید و از ساخت instance جدید در هر Render خودداری کنید.

Endpoint پیش‌فرض#

Endpoint پیش‌فرض SDK برابر است با:

text
https://api.alphana.ir/api/events

SDK از این آدرس، API Base موردنیاز خود را مشخص می‌کند و مسیر unified ingest را به شکل زیر می‌سازد:

text
https://api.alphana.ir/api/collect

در نسخه فعلی، Eventها، Heartbeatها و Logهای SDK از مسیر unified collection ارسال می‌شوند.

در بیشتر پروژه‌ها نیازی به تغییر این endpointها ندارید و مقادیر پیش‌فرض برای اتصال مستقیم به زیرساخت آلفانا کافی هستند.

اگر integration خاصی دارید که به endpoint متفاوت نیاز دارد، تنظیمات مربوط به endpoint و collectEndpoint در پیکربندی SDK توضیح داده شده‌اند.

بررسی نصب#

بعد از راه‌اندازی Tracker، سایت را اجرا کنید و DevTools مرورگر را باز کنید.

در بخش Network باید درخواست‌های collection به endpoint زیر قابل مشاهده باشند:

text
POST https://api.alphana.ir/api/collect

اگر این درخواست‌ها با موفقیت ارسال می‌شوند، SDK توانسته به backend آلفانا متصل شود و telemetry وارد pipeline collection شده است.

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

استفاده در React#

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

tsx
import {
  UserTrackerProvider,
  useTracker,
  useTrackGoal,
} from "alphana-sdk/react";

این ورودی Provider و Hookهایی را در اختیار شما قرار می‌دهد که استفاده از Tracker را در Component Tree ساده‌تر می‌کنند.

جزئیات کامل در React Hooks توضیح داده شده است.

قدم بعدی#

بعد از اینکه SDK نصب شد و نخستین داده‌ها را دریافت کردید، می‌توانید integration را بر اساس نیاز محصول کامل‌تر کنید: