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

SDK آلفانا

مرجع سطح بالای exports، چرخه عمر، telemetry و integrationهای نسخه 2.0.7.

پکیج alphana-sdk@2.0.7 لایه اصلی اتصال وب‌سایت یا محصول شما به آلفاناست. SDK رفتارهای موردنیاز برای تحلیل تجربه کاربر را در مرورگر ثبت می‌کند و ابزارهای لازم برای کار مستقیم با Tracker را نیز در اختیار برنامه قرار می‌دهد.

در نسخه 2.0.7، SDK قابلیت‌های مربوط به Navigation، زمان حضور کاربر، Heatmap، Session Replay، Log، Goal، Revenue، Journey، Feature Flag، A/B Assignment و Widgetهای داخل سایت را پوشش می‌دهد.

بخش زیادی از collection به‌صورت خودکار توسط UserTracker و pluginهای داخلی انجام می‌شود. در کنار آن، APIهای عمومی SDK به شما اجازه می‌دهند رفتارهایی را که معنای مشخصی در محصول دارند، مثل تکمیل یک Goal، ثبت Revenue یا رسیدن کاربر به یک مرحله از Journey، به‌صورت مستقیم ثبت کنید.

ورودی‌های package#

پکیج آلفانا دو ورودی اصلی برای استفاده در JavaScript و React ارائه می‌کند:

alphana-sdk#

ورودی اصلی package برای کار مستقیم با Tracker و APIهای پایه SDK است.

از این مسیر موارد زیر export می‌شوند:

  • UserTracker برای ساخت و مدیریت instance اصلی Tracker
  • DEFAULT_ENDPOINT برای دسترسی به endpoint پیش‌فرض SDK
  • LogCapture برای قابلیت‌های مربوط به ثبت Log
  • renderHeatmap برای کار با داده‌های Heatmap
  • ALPHANA_SDK_VERSION برای خواندن نسخه فعلی SDK
  • normalizeTrackerPath برای normalize کردن مسیرهایی که Tracker با آن‌ها کار می‌کند
  • typeهای عمومی موردنیاز برای استفاده TypeScript

نمونه import:

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

UserTracker نقطه اصلی تعامل با SDK است و lifecycle ثبت داده، pluginها، queue و ارسال Eventها را مدیریت می‌کند.

برای جزئیات متدهای عمومی آن، صفحه Tracker API را ببینید.

alphana-sdk/react#

اگر محصول شما با React ساخته شده است، ورودی زیر integrationهای مخصوص React را در اختیار شما قرار می‌دهد:

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

این entry شامل UserTrackerProvider و Hookهای React است و کمک می‌کند Tracker را بدون دسترسی مستقیم مداوم به instance آن، در بخش‌های مختلف Component Tree استفاده کنید.

Hookهای این package برای Pageview، Goal، Revenue، Journey، Feature Flag، A/B Test و داده‌های Heatmap در دسترس‌اند.

فهرست کامل آن‌ها در React Hooks توضیح داده شده است.

چرخه عمر SDK#

چرخه اصلی Tracker با ساخت یک instance از UserTracker و اجرای init() شروع می‌شود.

پس از initialization، SDK pluginهای فعال را راه‌اندازی می‌کند، collection موردنیاز را آغاز می‌کند و queue ارسال داده را مدیریت می‌کند. بخشی از داده‌ها در حافظه نگهداری می‌شوند و در زمان مناسب از طریق جریان شبکه SDK به backend آلفانا ارسال می‌شوند.

در طول اجرای صفحه، Tracker می‌تواند داده‌هایی مثل Navigation، Pageview، زمان حضور، Heatmap، Replay و Eventهای ثبت‌شده به‌صورت دستی را جمع‌آوری کند.

برای پایان دادن کنترل‌شده به lifecycle نیز destroy() listenerها و timerهای ایجادشده را حذف می‌کند و flush نهایی را انجام می‌دهد.

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

tracker.init();

// ...

tracker.destroy();

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

Telemetry و جریان شبکه#

نسخه فعلی SDK داده‌های telemetry را در قالب envelopeهای مشخص برای backend آلفانا ارسال می‌کند.

Envelopeهای مربوط به Event، Heartbeat و Log در نسخه‌های فعلی به endpoint زیر ارسال می‌شوند:

text
POST {apiBase}/collect

به این ترتیب، جریان اصلی ingestion در نسخه‌های جدید از یک endpoint مشترک عبور می‌کند و backend نوع payload دریافت‌شده را بر اساس envelope آن پردازش می‌کند.

Endpointهای قدیمی مربوط به Batch، Heartbeat و Log همچنان در backend باقی مانده‌اند تا SDKهای قدیمی‌تر بتوانند در دوره سازگاری به کار خود ادامه دهند.

اگر از نسخه 2.0.7 استفاده می‌کنید، integration جدید باید بر رفتار فعلی SDK و مسیر /collect متکی باشد و نباید مستقیماً endpointهای قدیمی را به‌عنوان مسیر اصلی پیاده‌سازی کند.

قابلیت‌های تحت پوشش#

SDK فقط برای ثبت Pageview طراحی نشده است. مجموعه داده‌هایی که در نسخه فعلی می‌تواند مدیریت کند، بخش‌های مختلف رفتار و context کاربر را پوشش می‌دهد.

از جمله:

  • Navigation و Pageview
  • زمان حضور در صفحه
  • داده‌های Heatmap
  • Session Replay
  • Logهای پشتیبانی‌شده
  • Goalها
  • Revenue Eventها
  • Journey Stepها
  • Feature Flagها
  • A/B Test Assignmentها
  • Widgetهای داخل سایت

این داده‌ها هرکدام نشانه متفاوتی از تجربه واقعی کاربر را ثبت می‌کنند. بخشی از آن‌ها به‌صورت خودکار collect می‌شوند و بخشی دیگر، مثل Goal یا Journey Step، زمانی ارزش بیشتری دارند که بر اساس معنای واقعی رفتار در محصول شما تعریف شوند.

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

برای جزئیات بیشتر درباره نصب و استفاده از SDK، بخش‌های زیر را ببینید:

  • پیکربندی — تنظیمات UserTracker و گزینه‌های قابل استفاده هنگام initialization
  • Tracker API — متدهای عمومی برای Pageview، Goal، Revenue، Journey، Flags، آزمایش‌ها و Session
  • React Hooks — Provider و Hookهای آماده برای integration با React
  • حریم خصوصی — Consent، Session Replay Masking و مرز استفاده از credentialهای مرورگر و سرور