مینی‌اپ وب: تحلیل خودکار و ثبت دستی سفر
در مینی‌اپ وب، 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 مسیر اولیه و تغییرات بعدی را از منابع زیر تشخیص می‌دهد:
| رویداد یا API مرورگر | نمونه کاربرد |
|---|---|
| بارگذاری مسیر اولیه | اولین صفحه‌ای که کاربر می‌بیند |
history.pushState |
مسیریابی SPA به صفحه جدید |
history.replaceState |
جایگزینی مسیر فعلی |
popstate |
دکمه برگشت یا جلو مرورگر |
hashchange |
مسیریابی مبتنی بر #/ |
مسیرهای تکراریِ پشت‌سرهم دوباره ثبت نمی‌شوند. در حالت پیش‌فرض Query String و Fragment معمولی از شناسه مرحله حذف می‌شوند؛ اما مسیر Hash Router مانند #/checkout نگهداری می‌شود.
مسیرهای پویا و حساس
اگر URL شامل شناسه سفارش، شناسه کاربر یا مقدار متغیر است، همیشه routeIdResolver تعریف کنید تا پیش از ثبت، مسیر عمومی و پایدار شود.
AppsanWeb.analytics.configure({
autoTrackRoutes: true,
routeIdResolver: url =>
url.pathname.replace(//orders/[^/]+/, '/orders/:id')
});برای نادیده گرفتن یک مسیر، از Resolver مقدار null برگردانید.
چه زمانی حالت دستی لازم است؟
- نمای مهمی باز می‌شود ولی URL تغییر نمی‌کند.
- دیالوگ تأیید، پرداخت یا خطا باید در سفر دیده شود.
- یک رویداد تجاری مانند انتخاب روش پرداخت یا تأیید نهایی رخ می‌دهد.
- نتیجه نهایی سفر باید صریحاً تکمیل، لغو، Timeout یا خطا اعلام شود.
- باید یک مقدار فنی و غیرحساس به سفر اضافه شود.
متدهای دستی
| متد | ورودی | کاربرد |
|---|---|---|
start |
- | شروع صریح سفر |
complete |
- | پایان موفق |
cancel |
- | لغو سفر |
timeout |
- | پایان به‌علت اتمام زمان |
fail |
reasonCode? |
پایان ناموفق با دلیل اختیاری |
step |
type, id |
ثبت مرحله page، dialog یا custom |
setData |
key, value |
افزودن داده فنی به سفر |
log / warn / error |
message |
ثبت پیام تشخیصی در صورت فعال بودن قانون متناظر در پنل |
مثال کامل
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 استفاده کنید. این پیام‌ها فقط در صورت وجود قانون فعال و منطبق در تعریف سفر پنل جمع‌آوری می‌شوند.
مسیر انتقال اطلاعات
- SDK وب مسیر یا رویداد دستی را به پیام Analytics تبدیل می‌کند.
- Web Extension پیام را از WebView به میزبان Android منتقل می‌کند.
- Appsan Analytics رویداد را مرتب و به سرویس Analytics ارسال می‌کند.
- تعریف فعال پنل، مراحل را به سفر یا قیف تبدیل می‌کند.
نمایش نتیجه در پنل
سفرهای ثبت‌شده از زبانه «سفرها» در پنل اپسان در دسترس هستند. برای مشاهده جزئیات هر سفر، آیکون مشاهده همان ردیف را انتخاب کنید.
تنظیم مراحل وب در پنل
برای مسیرهای خودکار، نوع مرحله را page و شناسه را دقیقاً برابر خروجی Resolver وارد کنید؛ مانند /checkout یا /orders/:id. برای مراحل دستی نیز نوع و شناسه باید با آرگومان‌های متد step یکسان باشد؛ برای نمونه dialog / payment.confirmation.
/home و /checkout و مرحله دستی payment.confirmationپیشنهاد: ابتدا خروجی Resolver و نام مرحله‌های دستی را به‌صورت یک قرارداد ثابت در پروژه تعریف کنید، سپس همان مقادیر را در پنل وارد کنید. این کار از شکسته شدن گزارش‌ها پس از تغییر مسیرهای رابط جلوگیری می‌کند.