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

Journeys

ساخت مسیر کاربر از Pageviewهای خودکار و Milestoneهای ثبت‌شده با trackJourneyStep.

Journeys در آلفانا مسیر حرکت کاربر را از Pageviewهای ثبت‌شده می‌سازند و کمک می‌کنند ببینید کاربر برای رسیدن به یک نتیجه از چه مسیرهایی عبور کرده است.

بخش زیادی از Journey به‌صورت خودکار از Navigation و Pageviewهای SDK شکل می‌گیرد. اما بعضی مرحله‌های مهم محصول بدون تغییر URL اتفاق می‌افتند؛ مثل انتخاب پلن، تکمیل یک مرحله از فرم چندمرحله‌ای یا تأیید یک تنظیم.

برای این نوع Milestoneها می‌توانید از trackJourneyStep() استفاده کنید.

ثبت Milestone#

اگر مرحله‌ای در Journey اهمیت دارد اما باعث تغییر Route نمی‌شود، آن را به‌صورت صریح ثبت کنید:

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

در این مثال، انتخاب Plan یک Milestone معنادار در مسیر کاربر است و بدون نیاز به تغییر URL در Journey ثبت می‌شود.

ساختار Journey#

یک Journey می‌تواند ترکیبی از Pageviewهای خودکار و Journey Stepهای صریح باشد.

برای مثال:

text
/pricing
↓
plan_selected
↓
/signup
↓
account_created
↓
/dashboard

در این مسیر، Pageviewها از Navigation ثبت می‌شوند و مرحله‌هایی مثل plan_selected یا account_created می‌توانند با trackJourneyStep() به مسیر اضافه شوند.

این ترکیب کمک می‌کند Journey فقط به URLها محدود نباشد و رفتارهایی که واقعاً معنای محصولی دارند نیز داخل مسیر دیده شوند.

چه زمانی از trackJourneyStep() استفاده کنیم؟#

Journey Step برای رفتارهایی مناسب است که:

  • یک مرحله مشخص در مسیر کاربر هستند
  • بدون تغییر URL اتفاق می‌افتند
  • می‌خواهید در تحلیل Journey به‌صورت مستقل دیده شوند
  • معنای ثابت و مشخصی در محصول دارند

برای مثال:

text
plan_selected
onboarding_step_completed
payment_method_selected
profile_completed
workspace_created

اگر رفتار فقط یک Interaction ساده و کم‌اهمیت است، لازم نیست آن را به Journey Step تبدیل کنید. بهتر است Milestoneها را برای مرحله‌هایی نگه دارید که واقعاً به فهم مسیر کاربر کمک می‌کنند.

انتخاب key#

key شناسه اصلی Journey Step است و بهتر است ثابت، کوتاه و انگلیسی باشد.

برای مثال:

text
plan_selected

انتخاب بهتری از چیزی مثل:

text
pricing_blue_button_clicked

است؛ چون ظاهر یا محل Button ممکن است تغییر کند، اما معنای انتخاب Plan ثابت باقی می‌ماند.

اگر یک Journey Step در Production استفاده شده است، Key آن را بدون دلیل جدی تغییر ندهید تا داده‌های قبل و بعد از تغییر به‌صورت یک مسیر پیوسته باقی بمانند.

label#

label نام خواناتر Milestone است و می‌تواند برای نمایش یا فهم بهتر Event استفاده شود.

برای مثال:

typescript
{
  key: "plan_selected",
  label: "Plan selected"
}

در حالی که key بهتر است برای ثبات داده ثابت بماند، label می‌تواند خواناتر و مناسب نمایش باشد.

Metadata#

با metadata می‌توانید context بیشتری درباره همان Journey Step ثبت کنید.

برای مثال:

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

در این حالت، Milestone اصلی همان plan_selected است اما Metadata مشخص می‌کند کدام Plan انتخاب شده است.

این روش معمولاً بهتر از ساخت چند Key جداگانه مثل:

text
pro_plan_selected
free_plan_selected
enterprise_plan_selected

است؛ مگر اینکه این رفتارها واقعاً در محصول معنای متفاوتی داشته باشند.

Pageviewهای خودکار#

آلفانا بخش اصلی Journey را از Pageviewها می‌سازد.

اگر Tracker Navigation را به‌درستی ثبت کند، مسیرهایی که کاربر بازدید کرده است به Journey اضافه می‌شوند.

برای مثال:

text
/landing
/pricing
/signup
/dashboard

این Pageviewها بدون نیاز به تعریف Journey Step جداگانه می‌توانند مسیر پایه کاربر را شکل دهند.

Journey Step زمانی لازم می‌شود که یک اتفاق مهم بین این Pageviewها رخ دهد و URL تغییر نکند.

Journeys در SPA#

در Single Page Applicationها، تغییر Route معمولاً بدون reload کامل صفحه انجام می‌شود.

اگر فقط نخستین load ثبت شود و Navigationهای بعدی به SDK اعلام نشوند، Journey نیز فقط همان Pageview اولیه را خواهد داشت.

برای مثال، اگر کاربر این مسیر را طی کند:

text
/pricing
/signup
/dashboard

اما SDK فقط /pricing را ثبت کرده باشد، Journey واقعی کاربر کامل دیده نمی‌شود.

به همین دلیل در SPAها باید مطمئن شوید تمام Navigationهای Client-side به‌درستی به Tracker می‌رسند.

React#

در React می‌توانید مسیر فعلی Router را به usePageView() بدهید:

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

export function NavigationTracker({ path }: { path: string }) {
  usePageView(path);

  return null;
}

هر بار که مقدار path تغییر کند، Pageview جدید ثبت می‌شود و می‌تواند وارد Journey کاربر شود.

Next.js App Router#

در Next.js App Router می‌توانید از usePathname() همراه usePageView() استفاده کنید:

tsx
"use client";

import { usePathname } from "next/navigation";
import { usePageView } from "alphana-sdk/react";

export function NavigationTracker() {
  const pathname = usePathname();

  usePageView(pathname);

  return null;
}

NavigationTracker باید داخل UserTrackerProvider Render شود.

ثبت درست Navigation در Next.js برای Journey اهمیت زیادی دارد، چون Route Changeها معمولاً بدون Page Reload انجام می‌شوند.

برای جزئیات بیشتر، راهنمای Next.js App Router را ببینید.

ترکیب Pageview و Milestone#

فرض کنید جریان خرید شما به این شکل است:

  1. کاربر وارد /pricing می‌شود.
  2. Plan Pro را انتخاب می‌کند.
  3. وارد /checkout می‌شود.
  4. روش پرداخت را انتخاب می‌کند.
  5. به /checkout/success می‌رسد.

Pageviewهای این Journey:

text
/pricing
/checkout
/checkout/success

اما دو رفتار مهم بدون Route مستقل رخ می‌دهند:

text
plan_selected
payment_method_selected

با ثبت این Milestoneها، Journey می‌تواند تصویر دقیق‌تری ایجاد کند:

text
/pricing
↓
plan_selected
↓
/checkout
↓
payment_method_selected
↓
/checkout/success

این مسیر نسبت به مجموعه ساده Pageviewها context بیشتری درباره تصمیم‌های کاربر در اختیار شما قرار می‌دهد.

Journey و Goal#

Journey Step و Goal دو نقش متفاوت دارند.

Journey Step یک Milestone در مسیر است:

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

Goal یک نتیجه مهم را ثبت می‌کند:

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

یک Journey ممکن است چند Milestone داشته باشد و در نهایت به یک Goal برسد.

برای مثال:

text
pricing_viewed
↓
plan_selected
↓
signup_started
↓
signup_completed

در این مثال plan_selected می‌تواند Journey Step باشد و signup_completed یک Goal نهایی.

Journey را بیش از حد شلوغ نکنید#

لازم نیست هر Click، Input یا Interaction کاربر را به Milestone تبدیل کنید.

اگر تعداد Journey Stepها بیش از حد زیاد باشد، مسیر اصلی رفتار سخت‌تر دیده می‌شود و تفاوت بین Event عادی و مرحله مهم محصول از بین می‌رود.

Milestoneها را برای نقطه‌هایی انتخاب کنید که پاسخ به یکی از این سؤال‌ها کمک می‌کنند:

  • کاربر وارد کدام مرحله شد؟
  • کدام تصمیم مهم را گرفت؟
  • کدام بخش از فرآیند را کامل کرد؟
  • قبل از Goal نهایی از چه مرحله‌ای عبور کرد؟

تعریف کمتر اما دقیق‌تر Journey Step معمولاً تحلیل خواناتری ایجاد می‌کند.

مسیر داشبورد#

Journeyهای ثبت‌شده از مسیر فعلی زیر در داشبورد آلفانا در دسترس هستند:

text
/dashboard/journeys

از این بخش می‌توانید مسیرهای ثبت‌شده کاربران را در کنار Pageviewها و Milestoneهای محصول بررسی کنید.