استفاده از آزمایش در SDK

SDK آلفانا بعد از اجرای init()، آزمایش‌های فعال با وضعیت running را دریافت و Assignment مربوط به Visitor فعلی را ارزیابی می‌کند. بنابراین در حالت معمول لازم نیست برای دریافت Variantها یک fetch سفارشی به endpoint آزمایش‌ها پیاده‌سازی کنید.

در React و Next.js می‌توانید از Hookهای آماده ورودی alphana-sdk/react استفاده کنید. این Hookها Assignment فعلی را از Tracker می‌خوانند و در صورت تغییر نتیجه آزمایش، Component را با مقدار جدید به‌روزرسانی می‌کنند.

استفاده در React و Next.js#

برای خواندن Variant یک Experiment مشخص، از useAbVariant() استفاده کنید. اگر فقط می‌خواهید بدانید Visitor در یک Variant مشخص قرار گرفته است یا نه، useIsAbVariant() نتیجه را به‌صورت boolean در اختیار شما قرار می‌دهد.

import { useAbVariant, useIsAbVariant } from "alphana-sdk/react";

export function CheckoutCta() {
  const variant = useAbVariant("checkout-cta-test");

  const isB = useIsAbVariant("checkout-cta-test", "variant-b");

  if (variant === null) {
    return <button disabled>...</button>;
  }

  return <button className={isB ? "blue" : "green"}>ادامه خرید</button>;
}

در این مثال، `useAbVariant()` Variant اختصاص‌داده‌شده به آزمایش `checkout-cta-test` را برمی‌گرداند.

تا زمانی که نخستین پاسخ Evaluation دریافت نشده باشد یا Assignment فعالی برای آزمایش وجود نداشته باشد، مقدار Hook می‌تواند `null` باشد.

بعد از دریافت Assignment، می‌توانید Variant را مستقیماً بررسی کنید یا با `useIsAbVariant()` منطق UI را خواناتر نگه دارید.
id: experiments-frameworks
## حالت اولیه و Loading

Evaluation آزمایش یک عملیات asynchronous است. به همین دلیل، در نخستین Render ممکن است Assignment هنوز در اختیار SDK نباشد.

در این فاصله:

```tsx
const variant = useAbVariant("checkout-cta-test");

می‌تواند مقدار زیر را برگرداند:

null

بهتر است برای این وضعیت یک حالت اولیه مشخص طراحی کنید و فرض نکنید null همان Control Variant است.

برای مثال:

if (variant === null) {
  return <button disabled>...</button>;
}

یا می‌توانید یک UI خنثی نمایش دهید تا نتیجه Evaluation مشخص شود.

انتخاب رفتار مناسب به نوع Experiment بستگی دارد، اما بهتر است Loading باعث تغییر شدید ساختار صفحه بعد از دریافت Assignment نشود.

استفاده در Next.js#

در Next.js نیز Hookهای A/B Test باید داخل Client Component و زیر UserTrackerProvider استفاده شوند.

برای مثال:

"use client";

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

export function PricingCta() {
  const variant = useAbVariant("pricing-cta-test");

  if (variant === null) {
    return null;
  }

  if (variant === "short-copy") {
    return <button>شروع کنید</button>;
  }

  return <button>آلفانا را رایگان امتحان کنید</button>;
}

لازم نیست برای Next.js یک Route Handler یا Server-side fetch جداگانه برای دریافت Assignment ایجاد کنید. Evaluation توسط SDK مرورگر انجام می‌شود و نتیجه از طریق Hookهای React در اختیار Component قرار می‌گیرد.

استفاده در Vanilla SDK#

اگر مستقیماً با UserTracker کار می‌کنید، APIهای A/B Test روی همان instance در دسترس هستند.

برای refresh کردن یک یا چند آزمایش مشخص می‌توانید از fetchAbTests() استفاده کنید:

await tracker.fetchAbTests(["checkout-cta-test"]);

سپس Variant فعلی را با getAbVariant() بخوانید:

const variant = tracker.getAbVariant("checkout-cta-test");

اگر برای Experiment موردنظر Assignment فعالی وجود نداشته باشد، مقدار برگشتی می‌تواند null باشد.

بررسی یک Variant مشخص#

اگر فقط می‌خواهید بدانید Visitor در یک Variant مشخص قرار گرفته است، در Vanilla SDK می‌توانید از isAbVariant() استفاده کنید.

برای مثال:

const isVariantB = tracker.isAbVariant("checkout-cta-test", "variant-b");

if (isVariantB) {
  showVariantB();
} else {
  showCurrentVersion();
}

این روش زمانی مناسب است که نیازی به خود Variant Key ندارید و فقط نتیجه یک شرط مشخص برایتان مهم است.

دنبال کردن تغییر Assignmentها#

برای واکنش به تغییر Assignmentها، onAbTestsChange() در دسترس است.

const unsubscribe = tracker.onAbTestsChange((tests) => {
  console.log(tests);
});

این API برای زمانی مناسب است که Assignmentها بعد از initialization refresh شوند و بخواهید منطق Vanilla یا UI سفارشی خود را با snapshot جدید هماهنگ کنید.

در React معمولاً نیازی به مدیریت مستقیم این subscription ندارید، چون Hookهای useAbTests()، useAbVariant() و useIsAbVariant() این جریان را با lifecycle Component هماهنگ می‌کنند.

Fetch دستی همیشه لازم نیست#

بعد از اجرای:

tracker.init();

SDK آزمایش‌های running را fetch می‌کند و Evaluation اولیه انجام می‌شود.

بنابراین لازم نیست در شروع هر صفحه یا پیش از هر بار خواندن Variant، fetchAbTests() را دوباره اجرا کنید.

این متد بیشتر زمانی کاربرد دارد که می‌خواهید Assignmentها را در زمان مشخصی refresh کنید یا فقط مجموعه‌ای از Experiment Keyها را دوباره ارزیابی کنید.

APIهای مرتبط#

برای کار با A/B Test در Vanilla SDK می‌توانید از APIهای زیر استفاده کنید:

در React نیز APIهای اصلی عبارت‌اند از: