تحلیل سفر مینی‌اپ

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

• معرفی تحلیل سفر مینی‌اپ
• مینی‌اپ بومی: حالت خودکار و تنظیم سفر در پنل
• مینی‌اپ بومی: ثبت دستی مراحل و نتیجه سفر
• مینی‌اپ وب: تحلیل خودکار و ثبت دستی سفر

معرفی تحلیل سفر مینی‌اپ

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

با این قابلیت می‌توان مشخص کرد کاربران از کدام مسیر عبور می‌کنند، در کدام مرحله متوقف می‌شوند و نرخ تکمیل هر فرایند چقدر است. نتیجه در پنل اپسان، هم به‌صورت تجمیعی و هم در جزئیات هر سفر نمایش داده می‌شود.

چه اطلاعاتی ثبت می‌شود؟

نکته امنیتی: در رابط تحلیل سفر پنل، شناسه کاربر و شناسه نشست نمایش داده نمی‌شود. در داده‌های سفر نیز اطلاعات شخصی، توکن، شماره تماس و ورودی آزاد کاربر را ثبت نکنید.

نسخه‌های موردنیاز

برای مینی‌اپ کاملاً بومی، دو مورد اول لازم است. برای مینی‌اپ وب داخل Android WebView، هر چهار مورد باید با نسخه‌های بالا یا نسخه سازگار جدیدتر استفاده شوند.

روش‌های ثبت سفر

حالت خودکار

شروع سفر، نمایش صفحات بومی و تغییر مسیرهای معمول وب بدون ثبت دستی توسعه‌دهنده شناسایی می‌شود. این حالت، انتخاب پیش‌فرض است.

حالت دستی

برای مراحل معنایی که از چرخه صفحه یا URL قابل تشخیص نیست، توسعه‌دهنده رویداد را صریحاً ثبت می‌کند؛ مانند نمایش پنجره تأیید، انتخاب روش پرداخت یا پایان موفق یک فرایند چندمرحله‌ای.

صفحات بعدی، نحوه استفاده از هر دو حالت در مینی‌اپ بومی و وب و همچنین تنظیم و مشاهده نتیجه در پنل را توضیح می‌دهند.

مینی‌اپ بومی: حالت خودکار و تنظیم سفر در پنل

در مینی‌اپ بومی، افزونه Analytics چرخه اجرای مینی‌اپ و نمایش عناصر page و dialog را به‌صورت خودکار به رویدادهای سفر تبدیل می‌کند.

چه چیزهایی خودکار ثبت می‌شوند؟

نکته: شناسه عناصر باید پایدار، کوتاه و غیرحساس باشد؛ مانند checkout، payment-confirmation یا error-network. متن قابل‌نمایش، شماره سفارش و اطلاعات کاربر را به‌عنوان ID استفاده نکنید.

تنظیم سفر در پنل اپسان

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

۱. ورود به زبانه سفرها

۲. باز کردن تنظیمات سفر

۳. ایجاد تعریف جدید و افزودن مراحل

قوانین خطا

مشاهده یک صفحه یا دیالوگ می‌تواند سفر را خودکار خطادار کند. در حالت تطبیق دقیق، ID باید کاملاً برابر باشد. در حالت Regex، الگو روی کل ID اجرا می‌شود؛ برای نمونه error-(network|timeout).

Regex فقط روی شناسه فنی اجرا می‌شود، نه متن دیالوگ یا محتوای لاگ. موتور مشترک سرور و Android از قواعد RE2 استفاده می‌کند و Lookaround یا Backreference را پشتیبانی نمی‌کند.

مشاهده نتیجه

در زبانه سفرها، جدول سفرها شناسه سفر، زمان شروع، نتیجه و تعداد مراحل را نشان می‌دهد. با انتخاب آیکون مشاهده، جزئیات مرتب مراحل باز می‌شود. داشبورد نیز تعداد کل سفرها، نرخ تکمیل، مراحل مشاهده‌شده و تفکیک نتایج را نمایش می‌دهد.

مینی‌اپ بومی: ثبت دستی مراحل و نتیجه سفر

حالت خودکار برای ثبت نمایش صفحات و دیالوگ‌ها کافی است. هرجا یک مرحله از روی چرخه رابط قابل تشخیص نیست، یا نتیجه سفر باید صریح باشد، از اکشن‌های Analytics استفاده کنید.

چه زمانی ثبت دستی لازم است؟

اکشن‌های سفر

ثبت نتیجه همراه تغییر صفحه

اکشن‌ها مانند سایر اکشن‌های Appsan با -> زنجیره می‌شوند. در مثال زیر ابتدا صفحه موفقیت باز و سپس سفر تکمیل می‌شود.

<button
    id="pay-button"
    text="پرداخت"
    onclick="page/success->analytics/journey/complete" />

ثبت مرحله سفارشی

<button
    id="confirm-button"
    text="تأیید"
    onclick="analytics/journey/step/custom/payment-authorized" />

ثبت خطا با دلیل

<button
    id="retry-button"
    text="تلاش دوباره"
    onclick="analytics/journey/fail/payment_declined" />

افزودن داده به سفر

<button
    id="wallet-button"
    text="کیف پول"
    onclick="analytics/journey/data/payment.method/wallet" />

قواعد شناسه و داده

نکته امنیتی: نام کاربر، شماره تماس، توکن، شماره سفارش و متن آزاد را در شناسه، دلیل خطا یا داده سفر قرار ندهید. برای موارد متغیر از کدهای عمومی و پایدار استفاده کنید.

ارتباط با تعریف پنل

نوع و شناسه‌ای که در اکشن step می‌فرستید باید با مرحله تعریف‌شده در پنل یکسان باشد. برای نمونه، اکشن analytics/journey/step/custom/payment-authorized در پنل به‌صورت نوع custom و شناسه payment-authorized تعریف می‌شود.

مینی‌اپ وب: تحلیل خودکار و ثبت دستی سفر

در مینی‌اپ وب، SDK مسیرهای داخل صفحه را شناسایی و از طریق سوپراپ به Analytics بومی Appsan ارسال می‌کند. همین کد در نسخه PWA نیز قابل استفاده خواهد بود.

نصب و فعال‌سازی

نسخه 0.1.0 یا جدیدتر بسته زیر را به پروژه وب اضافه کنید:

npm install @appsan-web/mini-web-sdk@^0.1.0

در پروژه Android میزبان نیز Appsan Core 0.1.78، Appsan Analytics 0.1.0 و Appsan Web Extension 0.0.8 یا نسخه سازگار جدیدتر لازم است.

import { AppsanWeb } from '@appsan-web/mini-web-sdk';

AppsanWeb.analytics.configure({
  autoTrackRoutes: true
});

حالت خودکار

گزینه autoTrackRoutes به‌صورت پیش‌فرض فعال است. SDK مسیر اولیه و تغییرات بعدی را از منابع زیر تشخیص می‌دهد:

مسیرهای تکراریِ پشت‌سرهم دوباره ثبت نمی‌شوند. در حالت پیش‌فرض Query String و Fragment معمولی از شناسه مرحله حذف می‌شوند؛ اما مسیر Hash Router مانند #/checkout نگهداری می‌شود.

مسیرهای پویا و حساس

اگر URL شامل شناسه سفارش، شناسه کاربر یا مقدار متغیر است، همیشه routeIdResolver تعریف کنید تا پیش از ثبت، مسیر عمومی و پایدار شود.

AppsanWeb.analytics.configure({
  autoTrackRoutes: true,
  routeIdResolver: url =>
    url.pathname.replace(//orders/[^/]+/, '/orders/:id')
});

برای نادیده گرفتن یک مسیر، از Resolver مقدار null برگردانید.

چه زمانی حالت دستی لازم است؟

متدهای دستی

مثال کامل

import { AppsanWeb } from '@appsan-web/mini-web-sdk';

AppsanWeb.analytics.step('dialog', 'payment.confirmation');
AppsanWeb.analytics.setData('payment.method', 'wallet');

AppsanWeb.analytics.complete().subscribe({
  next: () => console.log('Journey completed'),
  error: error => console.error(error)
});

تمام متدهای سفر یک Subject از RxJS برمی‌گردانند و در صورت نیاز می‌توان نتیجه ارسال را با subscribe دریافت کرد.

خطا و لاگ

خطاهای Runtime و Promiseهای بدون Handler به‌صورت خودکار گزارش می‌شوند. SDK عمداً console، fetch و XMLHttpRequest را شنود نمی‌کند. برای ثبت پیام تشخیصی از AppsanWeb.analytics.log، warn یا error استفاده کنید. این پیام‌ها فقط در صورت وجود قانون فعال و منطبق در تعریف سفر پنل جمع‌آوری می‌شوند.

مسیر انتقال اطلاعات

نمایش نتیجه در پنل

سفرهای ثبت‌شده از زبانه «سفرها» در پنل اپسان در دسترس هستند. برای مشاهده جزئیات هر سفر، آیکون مشاهده همان ردیف را انتخاب کنید.

تنظیم مراحل وب در پنل

برای مسیرهای خودکار، نوع مرحله را page و شناسه را دقیقاً برابر خروجی Resolver وارد کنید؛ مانند /checkout یا /orders/:id. برای مراحل دستی نیز نوع و شناسه باید با آرگومان‌های متد step یکسان باشد؛ برای نمونه dialog / payment.confirmation.

پیشنهاد: ابتدا خروجی Resolver و نام مرحله‌های دستی را به‌صورت یک قرارداد ثابت در پروژه تعریف کنید، سپس همان مقادیر را در پنل وارد کنید. این کار از شکسته شدن گزارش‌ها پس از تغییر مسیرهای رابط جلوگیری می‌کند.