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

ثبت Revenue

ثبت خرید، اشتراک، تمدید، ارتقای پلن یا Refund با trackRevenue و payload واقعی SDK.

Revenue Event برای ثبت اتفاق‌هایی استفاده می‌شود که مستقیماً ارزش مالی دارند؛ مثل خرید، شروع اشتراک، تمدید، ارتقای پلن یا Refund.

بهتر است Revenue را زمانی ثبت کنید که نتیجه پرداخت یا تغییر مالی با اطمینان مشخص شده باشد. به این شکل، داده‌ای که در آلفانا می‌بینید فقط نشان نمی‌دهد کاربر چه رفتاری داشته، بلکه مشخص می‌کند کدام مسیرها و تعامل‌ها در نهایت به درآمد منجر شده‌اند.

متد trackRevenue در payload فعلی از فیلدهای eventName، transactionId، amount و currency پشتیبانی می‌کند. در کنار آن می‌توانید اطلاعات تکمیلی مثل Order، Product، Plan، Coupon، Status، Items و Metadata را نیز همراه Event ارسال کنید.

نمونه ثبت خرید#

پس از تأیید موفق یک خرید می‌توانید Revenue Event را به این شکل ثبت کنید:

typescript
tracker.trackRevenue({
  eventName: "purchase",
  transactionId: "order_12345",
  orderId: "order_12345",
  amount: 1490000,
  currency: "IRR",
  status: "paid",
  items: [
    {
      id: "pro-plan",
      name: "Pro Plan",
      quantity: 1,
      price: 1490000,
    },
  ],
});

در این مثال:

  • eventName نوع اتفاق مالی را مشخص می‌کند.
  • transactionId شناسه یکتای تراکنش است.
  • orderId سفارش مرتبط با Revenue Event را مشخص می‌کند.
  • amount مبلغ ثبت‌شده برای تراکنش است.
  • currency واحد پول را مشخص می‌کند.
  • status وضعیت نهایی تراکنش را نگه می‌دارد.
  • items جزئیات محصول، پلن یا آیتم‌های مرتبط با خرید را در اختیار تحلیل قرار می‌دهد.

چه زمانی Revenue ثبت کنیم؟#

Revenue فقط برای خرید اولیه نیست. هر اتفاق مالی معناداری می‌تواند به‌عنوان یک Revenue Event ثبت شود.

برای مثال:

  • خرید موفق
  • شروع اشتراک پولی
  • تمدید اشتراک
  • ارتقای Plan
  • خرید Add-on یا قابلیت اضافه
  • Refund کامل یا جزئی
  • سایر تراکنش‌هایی که لازم است در تحلیل درآمد دیده شوند

بهتر است eventName را طوری انتخاب کنید که معنای مالی Event در گزارش‌ها روشن باشد.

برای مثال:

text
purchase
subscription_started
subscription_renewed
plan_upgraded
refund

استفاده از نام‌های ثابت و قابل‌پیش‌بینی باعث می‌شود بعداً بتوانید Eventهای مالی را راحت‌تر در گزارش‌ها، Segmentها و تحلیل Journey از یکدیگر تفکیک کنید.

transactionId#

مقدار transactionId باید برای هر تراکنش یکتا باشد.

برای مثال، اگر سیستم شما برای هر سفارش یک Order ID یکتا تولید می‌کند، می‌توانید همان شناسه را به‌عنوان transactionId استفاده کنید:

typescript
transactionId: "order_12345";

از ایجاد مقدار تصادفی در سمت مرورگر برای تراکنشی که در Backend شناسه واقعی دارد خودداری کنید. بهتر است شناسه‌ای که سیستم پرداخت یا Backend شما به‌عنوان مرجع تراکنش می‌شناسد در Revenue Event نیز استفاده شود.

مبلغ و واحد پول#

amount باید مبلغ واقعی تراکنش را با ساختاری ثابت در کل محصول ارسال کند.

typescript
amount: 1490000,
currency: "IRR",

اگر واحد پول محصول شما IRR است، تمام Revenue Eventهای همان جریان را با همین واحد ثبت کنید تا داده‌ها بعداً قابل مقایسه باقی بمانند.

در پروژه‌هایی که بیش از یک Currency دارند، مقدار currency را برای هر تراکنش بر اساس واحد واقعی همان پرداخت ارسال کنید و از تبدیل خودسرانه مبلغ در سمت Client خودداری کنید.

ثبت Refund#

Refund نیز می‌تواند به‌عنوان یک Revenue Event مستقل ثبت شود.

برای مثال:

typescript
tracker.trackRevenue({
  eventName: "refund",
  transactionId: "refund_order_12345",
  orderId: "order_12345",
  amount: 1490000,
  currency: "IRR",
  status: "refunded",
});

بهتر است Refund را به Order یا Transaction اصلی مرتبط نگه دارید تا در تحلیل‌های بعدی مشخص باشد بازگشت وجه مربوط به کدام خرید بوده است.

استفاده در React#

در React می‌توانید از useTrackRevenue() استفاده کنید. این Hook یک callback پایدار برای همان عملیات trackRevenue در اختیار شما قرار می‌دهد.

tsx
import { useTrackRevenue } from "alphana-sdk/react";

export function PaymentSuccess() {
  const trackRevenue = useTrackRevenue();

  const handleSuccess = () => {
    trackRevenue({
      eventName: "purchase",
      transactionId: "order_12345",
      amount: 1490000,
      currency: "IRR",
      status: "paid",
    });
  };

  return <button onClick={handleSuccess}>ثبت پرداخت</button>;
}

اگر از React استفاده می‌کنید، این روش کمک می‌کند بدون دسترسی مستقیم به instance اصلی UserTracker، Revenue Event را از داخل Component ثبت کنید.

داده قابل اعتماد را ثبت کنید#

Revenue با سایر Eventهای رفتاری تفاوت مهمی دارد: این داده مستقیماً به درآمد و تراکنش مالی مربوط است.

به همین دلیل، مقدارهایی مثل amount، status و transactionId باید از منبعی قابل اعتماد دریافت شوند.

اگر پرداخت فقط در Backend تأیید می‌شود، ابتدا نتیجه معتبر پرداخت را در Server مشخص کنید و سپس اطلاعات تأییدشده را به Success Flow سمت Client منتقل کنید.

مقداری که مستقیماً از DOM، Query Parameter قابل‌ویرایش یا State قابل دست‌کاری مرورگر خوانده شده است نباید به‌تنهایی به‌عنوان حقیقت مالی در نظر گرفته شود.