پیکربندی SDK

تنظیمات TrackerConfig رفتار اصلی SDK آلفانا را مشخص می‌کنند؛ از مسیر ارسال داده و نحوه ساخت Session گرفته تا Heatmap، Session Replay، batching، compression و مدیریت consent.

گزینه‌های این صفحه مستقیماً بر اساس typeهای نسخه 2.0.7 نوشته شده‌اند تا هنگام تنظیم Tracker بتوانید به مقادیر واقعی نسخه فعلی SDK تکیه کنید.

Endpointها#

endpoint آدرس پایه مورد استفاده SDK را مشخص می‌کند:

https://api.alphana.ir/api/events

در نسخه فعلی، جریان اصلی Eventها از collectEndpoint عبور می‌کند. اگر این مقدار را به‌صورت دستی مشخص نکنید، SDK مسیر زیر را بر اساس API Base فعلی می‌سازد:

{apiBase}/collect

در بیشتر integrationها نیازی به تغییر این دو مقدار نیست. فقط زمانی آن‌ها را override کنید که زیرساخت یا محیط اجرای شما واقعاً به endpoint متفاوتی نیاز داشته باشد.

App و Session#

هر Tracker باید به یک App مشخص در آلفانا متصل باشد. appId مشخص می‌کند داده‌های collectشده متعلق به کدام App هستند و secretKey برای Bearer ingestion همان App استفاده می‌شود.

اگر sessionId را خودتان ارسال نکنید، SDK هنگام اجرا یک Session ID ایجاد می‌کند و مدیریت Session را به‌صورت خودکار ادامه می‌دهد.

const tracker = new UserTracker({
  appId: "YOUR_APP_ID",
  secretKey: "YOUR_APP_SECRET",
});

در حالت معمول، بهتر است ساخت و مدیریت sessionId را به SDK بسپارید؛ مگر اینکه integration شما دلیل مشخصی برای کنترل دستی Session داشته باشد.

کنترل collection#

سه گزینه اصلی رفتارهای پایه collection را کنترل می‌کنند:

{
  trackNavigation: true,
  trackTime: true,
  trackHeatmap: true,
}

trackNavigation تغییر مسیرهای کاربر را ثبت می‌کند، trackTime برای اندازه‌گیری زمان حضور استفاده می‌شود و trackHeatmap collection داده‌های موردنیاز Heatmap را فعال نگه می‌دارد.

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

تنظیم Heatmap#

رفتار Heatmap را می‌توانید با mouseSampleRate و maxHeatmapPoints کنترل کنید.

mouseSampleRate عددی بین 0 و 1 است و مشخص می‌کند چه نسبتی از داده‌های حرکت موس نمونه‌برداری شوند. مقدار پیش‌فرض آن:

mouseSampleRate: 0.3;

است.

maxHeatmapPoints نیز تعداد نقاطی را که برای هر صفحه نگهداری می‌شوند محدود می‌کند:

maxHeatmapPoints: 2000;

این تنظیمات کمک می‌کنند بین جزئیات داده و حجم collection تعادل ایجاد کنید.

Batch و Flush#

SDK Eventها را قبل از ارسال در queue نگه می‌دارد و آن‌ها را بر اساس batchSize و flushInterval ارسال می‌کند.

مقادیر پیش‌فرض:

batchSize: 20,
flushInterval: 5000,

یعنی SDK می‌تواند با رسیدن queue به ۲۰ مورد یا بر اساس چرخه flush پنج‌ثانیه‌ای، داده‌های آماده را ارسال کند.

در بیشتر پروژه‌ها مقادیر پیش‌فرض انتخاب مناسبی هستند. تغییر بیش از حد batchSize یا flushInterval می‌تواند روی تعداد requestها، تأخیر ارسال و حجم هر payload اثر بگذارد.

Compression#

در مرورگرهای سازگار، compression به‌صورت پیش‌فرض فعال است:

compressPayloads: true,
compressionThresholdBytes: 1024,

SDK زمانی از compression استفاده می‌کند که اندازه payload از compressionThresholdBytes عبور کند.

با مقدار پیش‌فرض، payloadهای کوچک‌تر از 1024 بایت بدون compression ارسال می‌شوند و payloadهای بزرگ‌تر، در صورت پشتیبانی محیط، می‌توانند فشرده شوند.

Session Replay#

Session Replay در تنظیمات پیش‌فرض فعال است:

sessionReplay: true,
sessionReplayMaskAllInputs: true,

در کنار فعال بودن Replay، مقدار sessionReplayMaskAllInputs نیز به‌صورت پیش‌فرض true است تا محتوای inputها در داده Replay mask شود.

اگر Session Replay در محصول شما استفاده می‌شود، تنظیمات Privacy و masking را پیش از انتشار بررسی کنید و فقط به مقدار پیش‌فرض اکتفا نکنید.

جزئیات بیشتر در حریم خصوصی و رضایت توضیح داده شده است.

Consent#

مقدار پیش‌فرض consentMode برابر با auto است:

consentMode: "auto";

در این حالت، اگر Cookie Consent از طریق runtime config فعال باشد، SDK می‌تواند شروع collection را تا مشخص شدن تصمیم visitor متوقف کند.

اگر مقدار زیر را تنظیم کنید:

consentMode: "disabled";

جریان Cookie Consent در SDK نادیده گرفته می‌شود و collection بدون انتظار برای تصمیم کاربر آغاز خواهد شد.

انتخاب این مقدار باید با سیاست رضایت و حریم خصوصی محصول شما هماهنگ باشد.

دریافت Eventها با onEvent#

onEvent یک callback همگام است که هنگام تولید هر Event توسط Tracker اجرا می‌شود.

const tracker = new UserTracker({
  appId: "YOUR_APP_ID",
  secretKey: "YOUR_APP_SECRET",

  onEvent(event) {
    console.log(event);
  },
});

این callback می‌تواند برای مشاهده جریان Eventها، debugging یا integrationهایی که به Eventهای تولیدشده نیاز دارند استفاده شود.

استفاده از onEvent مسیر اصلی collection را جایگزین نمی‌کند؛ Event همچنان وارد pipeline عادی Tracker می‌شود.

heatmapPages#

گزینه heatmapPages در نسخه فعلی deprecated است.

صفحه‌هایی که Heatmap برای آن‌ها فعال است از طریق داشبورد آلفانا مدیریت می‌شوند و backend فقط داده مسیرهایی را نگه می‌دارد که در تنظیمات مجاز شده‌اند.

بنابراین برای integrationهای جدید نباید به heatmapPages در تنظیمات SDK متکی باشید.