React Hooks

پکیج alphana-sdk/react مجموعه‌ای از Hookها را برای استفاده مستقیم از Tracker آلفانا در کامپوننت‌های React در اختیار شما قرار می‌دهد. این Hookها دسترسی به Tracker، ثبت Pageview، ارسال Goal و Revenue، خواندن Feature Flagها، بررسی Variant آزمایش‌ها و استفاده از داده‌های Heatmap را ساده‌تر می‌کنند.

برای اینکه Hookها به instance فعال Tracker دسترسی داشته باشند، باید داخل UserTrackerProvider استفاده شوند.

اگر یک Hook خارج از Provider اجرا شود، SDK به‌جای ایجاد خطا از رفتار fallback امن استفاده می‌کند. در این حالت، useTracker() مقدار null برمی‌گرداند و Hookهایی که عملیاتی مثل ثبت Goal، Revenue یا Journey Step انجام می‌دهند به‌صورت امن no-op می‌شوند.

این رفتار کمک می‌کند نبود Provider باعث شکستن Render یا اجرای کامپوننت نشود؛ با این حال، برای ثبت واقعی داده‌ها باید Provider در سطح مناسب از درخت React قرار گرفته باشد.

Hookهای در دسترس#

استفاده از useTracker#

اگر به instance اصلی Tracker نیاز دارید، می‌توانید از useTracker() استفاده کنید:

import { useTracker } from "alphana-sdk/react";

export function DebugTracker() {
  const tracker = useTracker();

  if (!tracker) {
    return null;
  }

  return <button onClick={() => tracker.flush()}>Flush</button>;
}

در این مثال، اگر کامپوننت خارج از UserTrackerProvider قرار گرفته باشد، tracker مقدار null خواهد داشت و کامپوننت بدون ایجاد خطا Render می‌شود.

ثبت Goal با useTrackGoal#

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

import { useTrackGoal } from "alphana-sdk/react";

export function SignupDone() {
  const trackGoal = useTrackGoal();

  return (
    <button
      onClick={() =>
        trackGoal({
          key: "signup_completed",
        })
      }
    >
      ثبت
    </button>
  );
}

useTrackGoal() یک callback پایدار برمی‌گرداند؛ بنابراین می‌توانید آن را مستقیماً داخل handlerهای کامپوننت استفاده کنید.

اگر Provider در دسترس نباشد، فراخوانی این callback خطایی ایجاد نمی‌کند و به‌صورت no-op اجرا می‌شود.

ثبت Pageview#

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

usePageView(path);

هر زمان مقدار path تغییر کند، Hook یک Pageview جدید ثبت می‌کند.

اگر path را به‌صورت دستی مدیریت می‌کنید، مطمئن شوید مقدار ارسال‌شده نمایانگر مسیر واقعی‌ای است که می‌خواهید در گزارش‌های آلفانا دیده شود.

Feature Flagها#

برای دسترسی به همه Flagهای فعلی می‌توانید از useFeatureFlags() استفاده کنید:

const flags = useFeatureFlags();

اگر فقط وضعیت یک Flag مشخص مهم است، useFeatureFlag(key) انتخاب ساده‌تری است:

const enabled = useFeatureFlag("new_checkout");

این Hook مقدار boolean مربوط به همان Flag را برمی‌گرداند و با refresh شدن ارزیابی Flagها، کامپوننت دوباره Render می‌شود.

A/B Test و Variantها#

برای خواندن assignmentهای آزمایش می‌توانید از useAbTests()، useAbVariant() یا useIsAbVariant() استفاده کنید.

const variant = useAbVariant("checkout_experiment");

در صورتی که assignment برای آزمایش موردنظر وجود نداشته باشد، useAbVariant() مقدار null برمی‌گرداند.

اگر فقط می‌خواهید بدانید کاربر در یک Variant مشخص قرار دارد یا نه:

const isVariantB = useIsAbVariant("checkout_experiment", "variant_b");

خروجی این Hook یک مقدار boolean است و می‌تواند مستقیماً برای کنترل Render یا رفتار کامپوننت استفاده شود.

داده‌های Heatmap#

useHeatmapData(path?, refreshMs?) داده‌های Heatmap موجود در حافظه Tracker را به‌صورت live در اختیار کامپوننت قرار می‌دهد.

به‌طور پیش‌فرض، این Hook هر 500ms داده را refresh می‌کند:

const heatmapData = useHeatmapData();

در صورت نیاز می‌توانید فاصله refresh را تغییر دهید:

const heatmapData = useHeatmapData("/pricing", 1000);

مقدار refreshMs را متناسب با نیاز کامپوننت انتخاب کنید. refresh سریع‌تر همیشه به معنای تجربه بهتر نیست و می‌تواند باعث rerenderهای بیشتر شود.

رفتار fallback خارج از Provider#

Hookهای React آلفانا طوری طراحی شده‌اند که نبود UserTrackerProvider باعث ایجاد خطای Runtime نشود.

در خارج از Provider:

• useTracker() مقدار null برمی‌گرداند.
• Hookهای عملیاتی مثل useTrackGoal()، useTrackRevenue() و useTrackJourneyStep() به callbackهای امن no-op تبدیل می‌شوند.
• Hookهای وابسته به داده، در نبود Tracker از fallback امن خود استفاده می‌کنند.

این رفتار برای جلوگیری از شکستن اپلیکیشن است، نه جایگزینی برای Provider.

اگر انتظار دارید داده‌ای واقعاً در آلفانا ثبت یا ارزیابی شود، مطمئن شوید کامپوننت موردنظر در محدوده UserTrackerProvider قرار دارد.