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

JavaScript و TypeScript ساده

استفاده مستقیم از UserTracker در پروژه‌های JavaScript و TypeScript بدون React.

اگر پروژه شما از React استفاده نمی‌کند، می‌توانید مستقیماً با کلاس UserTracker کار کنید. در پروژه‌های JavaScript یا TypeScript که از bundler و Package Manager استفاده می‌کنند، API اصلی SDK از package root یعنی alphana-sdk در دسترس است.

در این روش lifecycle Tracker مستقیماً در اختیار شماست؛ یعنی خودتان instance را می‌سازید، init() را اجرا می‌کنید و در زمانی که integration دیگر به Tracker نیاز ندارد، destroy() را فراخوانی می‌کنید.

استفاده با Package Manager#

در پروژه‌های bundler-based، UserTracker را از ورودی اصلی package import کنید:

typescript
import { UserTracker } from "alphana-sdk";

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

tracker.init();

// در teardown نهایی
tracker.destroy();

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

بعد از اجرای init()، Tracker lifecycle اصلی SDK را شروع می‌کند، pluginهای فعال راه‌اندازی می‌شوند و collection داده‌های مربوط به تنظیمات فعلی آغاز خواهد شد.

در پایان lifecycle برنامه یا زمانی که دیگر نباید Tracker فعال بماند، destroy() را اجرا کنید تا listenerها و timerهای ایجادشده پاک شوند و cleanup نهایی انجام شود.

ساخت و راه‌اندازی Tracker#

می‌توانید ساخت Tracker و اجرای init() را به‌صورت جداگانه انجام دهید:

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

tracker.init();

یا از مقدار برگشتی init() استفاده کنید، چون این متد همان instance فعلی Tracker را برمی‌گرداند:

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

بعد از initialization، همان instance برای ثبت Goal، Revenue، Journey Step، Pageview و سایر عملیات عمومی Tracker قابل استفاده است.

ثبت Pageview#

اگر پروژه شما Navigation بدون reload کامل صفحه دارد، لازم است Pageviewهای جدید را در زمان تغییر مسیر ثبت کنید.

برای این کار می‌توانید از trackPageView() استفاده کنید:

typescript
tracker.trackPageView("/pricing");

اگر path را ارسال نکنید، Tracker می‌تواند از مسیر فعلی برای ثبت Pageview استفاده کند:

typescript
tracker.trackPageView();

در پروژه‌های SPA بهتر است منطق Router خود را به این فراخوانی متصل کنید تا هر Navigation واقعی کاربر در داده‌های آلفانا دیده شود.

ثبت Goal#

برای رفتارهایی که یک هدف مشخص در محصول را نشان می‌دهند، از trackGoal() استفاده کنید:

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

Goal برای رفتارهایی مناسب است که می‌خواهید بعداً آن‌ها را به‌عنوان یک نتیجه مشخص در Journey کاربر بررسی کنید؛ مثل تکمیل ثبت‌نام، ارسال فرم یا رسیدن به یک مرحله مهم.

ثبت Journey Step#

اگر لازم است یک milestone مشخص از مسیر کاربر را ثبت کنید، می‌توانید از trackJourneyStep() استفاده کنید:

typescript
tracker.trackJourneyStep({
  key: "plan_selected",
  label: "Plan selected",
});

این Event کمک می‌کند مراحل معنادار Journey به‌صورت مشخص در کنار سایر رفتارهای کاربر ثبت شوند.

ثبت Revenue#

برای اتفاق‌های مالی از trackRevenue() استفاده کنید:

typescript
tracker.trackRevenue({
  eventName: "purchase",
  transactionId: "order_12345",
  amount: 1490000,
  currency: "IRR",
  status: "paid",
});

Revenue را بهتر است فقط زمانی ثبت کنید که نتیجه مالی از منبع قابل اعتماد تأیید شده باشد.

جزئیات بیشتر درباره payload و نحوه ثبت تراکنش در ثبت Revenue قرار دارد.

شناسایی کاربر#

بعد از Login یا زمانی که اطلاعات کاربر برای محصول شما مشخص می‌شود، می‌توانید ویژگی‌های او را با identify() به Tracker اضافه کنید:

typescript
tracker.identify({
  id: "user_123",
  plan: "pro",
  role: "admin",
});

identify() در نسخه فعلی مقدارهایی با ساختار Record<string, string> دریافت می‌کند. اگر داده شما عددی یا boolean است، قبل از ارسال آن را به string تبدیل کنید.

این ویژگی‌ها می‌توانند در Segmentها، تحلیل Audience و ارزیابی Feature Flagها استفاده شوند.

ارسال دستی Queue#

Tracker ارسال Eventها را به‌صورت دوره‌ای مدیریت می‌کند، اما اگر در یک نقطه مشخص لازم است queue فعلی بدون انتظار برای flush بعدی ارسال شود، می‌توانید flush() را اجرا کنید:

typescript
await tracker.flush();

در بیشتر integrationها نیازی نیست این متد را بعد از هر Event فراخوانی کنید. SDK خودش چرخه ارسال را مدیریت می‌کند.

flush() بیشتر برای موقعیت‌هایی مناسب است که ارسال فوری Eventهای موجود در queue اهمیت دارد.

پایان lifecycle#

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

typescript
tracker.destroy();

این متد listenerها و timerهای Tracker را حذف می‌کند و cleanup مربوط به lifecycle SDK را انجام می‌دهد.

در پروژه‌های SPA معمولاً Tracker باید در سطحی ساخته شود که در طول Navigationهای داخلی باقی بماند؛ بنابراین destroy() را روی هر تغییر Route اجرا نکنید.

استفاده با Script Tag#

اگر پروژه شما bundler یا Package Manager ندارد، می‌توانید build مرورگر SDK را با Script Tag بارگذاری کنید.

بعد از load شدن Script، API اصلی از طریق object زیر در دسترس است:

javascript
window.AlphanaSDK;

برای ساخت مستقیم Tracker می‌توانید از window.AlphanaSDK.UserTracker استفاده کنید.

برای مثال:

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

tracker.init();

این روش همان API اصلی UserTracker را در محیطی در اختیار شما قرار می‌دهد که import کردن package ممکن نیست.

Command API#

Build مرورگر علاوه بر window.AlphanaSDK، command API سراسری زیر را نیز ایجاد می‌کند:

javascript
window.alphana;

از این API می‌توانید بدون نگهداری مستقیم instance Tracker، commandهای پشتیبانی‌شده را اجرا کنید.

Commandهای فعلی شامل موارد زیر هستند:

Commandکاربرد
initراه‌اندازی Tracker
identifyافزودن ویژگی‌های شناسایی‌شده Visitor
trackPageViewثبت Pageview
trackRevenueثبت Revenue Event
trackGoalثبت Goal
trackJourneyStepثبت مرحله‌ای از Journey
flushارسال queue فعلی
destroyپایان lifecycle Tracker

برای مثال، ثبت Goal از طریق Command API:

javascript
window.alphana("trackGoal", {
  key: "signup_completed",
  name: "Signup completed",
});

این روش برای سایت‌هایی مناسب است که SDK با Script Tag، CMS یا Google Tag Manager نصب شده و دسترسی مستقیم به module import ندارند.

نمونه استفاده از identify#

javascript
window.alphana("identify", {
  id: "user_123",
  plan: "pro",
  role: "admin",
});

ویژگی‌های ارسال‌شده باید با قرارداد فعلی identify() سازگار باشند و مقدارها به‌صورت string ارسال شوند.

نمونه ثبت Revenue#

javascript
window.alphana("trackRevenue", {
  eventName: "purchase",
  transactionId: "order_12345",
  amount: 1490000,
  currency: "IRR",
  status: "paid",
});

حتی زمانی که از Command API استفاده می‌کنید، اطلاعات مالی باید از منبع معتبر محصول یا Backend شما آمده باشند و نباید مقدارهای قابل دست‌کاری مرورگر را به‌عنوان حقیقت مالی در نظر بگیرید.

Package یا Script؟#

اگر پروژه شما build system و Package Manager دارد، استفاده مستقیم از alphana-sdk معمولاً انتخاب مناسب‌تری است؛ چون typeهای TypeScript، APIهای package و کنترل مستقیم lifecycle در اختیار شما قرار می‌گیرند.

Script Tag و Command API برای محیط‌هایی مناسب‌اند که:

  • Package Manager ندارند
  • نمی‌خواهند SDK وارد bundle اصلی شود
  • از CMS استفاده می‌کنند
  • integration از طریق GTM انجام می‌شود
  • دسترسی مستقیم به source code محدود است

در هر دو روش، هسته collection و رفتار اصلی Tracker یکسان باقی می‌ماند.

بررسی integration#

بعد از اجرای init()، DevTools مرورگر را باز کنید و در بخش Network بررسی کنید که درخواست‌های collection ارسال می‌شوند:

text
POST /api/collect

سپس چند رفتار معمول انجام دهید؛ برای مثال Pageview جدید ثبت کنید یا یک Goal آزمایشی بفرستید و مطمئن شوید Tracker بدون خطا به کار خود ادامه می‌دهد.

اگر داده ارسال نمی‌شود، موارد زیر را بررسی کنید:

  • appId صحیح باشد
  • secretKey متعلق به همان App باشد
  • دامنه فعلی در App ثبت شده باشد
  • init() اجرا شده باشد
  • Tracker چندبار initialize نشده باشد
  • Console و Network خطای مرتبط نداشته باشند

ادامه مستندات#

برای جزئیات بیشتر درباره APIهای قابل استفاده در این نوع integration، صفحات زیر را ببینید: