Web SDK Getting Started | متریکس Metrix

شروع کار

Metrix Web SDK کاربران، رویدادها، اتریبیوشن، اشتراک‌های وب‌پوش و پیام‌های درون‌سایتی را برای وب‌سایت شما ثبت می‌کند.

پیش‌نیازها

یک APP_ID و API_KEY از داشبورد متریکس
مرورگری که JavaScript در آن فعال باشد
HTTPS برای وب‌پوش ضروری است. البته برای توسعهٔ محلی روی localhost، مرورگرها به HTTPS نیازی ندارند.

نصب با npm

پکیج @metrixorg/websdk را نصب کنید:


npm install @metrixorg/websdk

SDK را فقط یک بار و در اولین فرصت ممکن در برنامه راه‌اندازی (initialize) کنید:


import { init } from '@metrixorg/websdk';
 
init('APP_ID', 'API_KEY');

SDK باید قبل از فراخوانی هر API دیگری از Metrix راه‌اندازی شود. فراخوانی init بیش از یک بار هیچ اثری ندارد.

استفاده با script tag

اگر امکان نصب پکیج npm را ندارید، می‌توانید bundle مخصوص مرورگر را داخل <head> صفحه قرار دهید. در محیط production بهتر است نسخهٔ مشخصی را پین کنید (ثابت نگه دارید). تنها در صورتی از latest استفاده کنید که بخواهید همیشه آخرین نسخه به‌صورت خودکار بارگذاری شود.


<script src="https://cdn.metrix.ir/sdk/web/metrix.umd-2.8.1.js"></script>
<script>
  Metrix.init('APP_ID', 'API_KEY');
</script>

برای اینکه همیشه آخرین bundle منتشرشده بارگذاری شود، به‌جای 2.8.1 از latest استفاده کنید.

برای پروژه‌های TypeScript که از روش script tag استفاده می‌کنند، قبل از استفاده، متغیر گلوبال Metrix را به صورت زیر declare (تعریف) کنید:


declare const Metrix: {
  init: (appId: string, apiKey: string, config?: Record<string, unknown>) => void;
};
 
Metrix.init(APP_ID, API_KEY);

پیکربندی مقداردهی اولیه

آرگومان سوم init اختیاری است. برای type checking، SDKConfig را import کنید:


import { init, SDKConfig } from '@metrixorg/websdk';
 
const config: SDKConfig = {
  sessionTracking: {
    enabled: true,
    packageName: 'my-web-app',
  },
  push: {
    enabled: true,
    publicKey: 'YOUR_VAPID_PUBLIC_KEY',
    showBell: true,
    showBackdrop: false,
    hasSW: false,
  },
  onSiteMessaging: {
    enabled: true,
  },
};
 
init('APP_ID', 'API_KEY', config);

پارامتر	نوع	توضیح	الزامی
`appId`	`string`	شناسه اپلیکیشن از داشبورد متریکس	بله
`apiKey`	`string`	کلید API تولیدشده در داشبورد متریکس	بله
`config`	`SDKConfig`	تنظیمات اختیاری قابلیت‌ها	خیر

SDKConfig از این بخش‌های اختیاری پشتیبانی می‌کند:

بخش	فیلدها	پیش‌فرض
`sessionTracking`	`enabled`, `packageName`	غیرفعال
`push`	`enabled`, `publicKey`, `hasSW`, `showBell`, `showBackdrop`, `backdropText`, `backdropDelay`	غیرفعال
`onSiteMessaging`	`enabled`	غیرفعال

توصیهٔ امنیتی: تا حد امکان API Key را در تنظیمات خصوصی برنامه نگه دارید و از قرار دادن کلیدهای API سمت سرور در کد فرانت‌اند خودداری کنید.

مرحله بعد چیست؟

بعد از راه‌اندازی SDK، می‌توانید این قابلیت‌ها را بررسی کنید:

ردیابی کاربران — شناسایی و مدیریت اطلاعات کاربر
ردیابی رویدادها — ثبت تعاملات و رویدادهای کاربر
اتریبیوشن — ردیابی اتریبیوشن نصب و conversion
وب‌پوش — ارسال نوتیفیکیشن پوش به کاربران مشترک (subscribed)
پیام‌رسانی درون‌سایتی — نمایش پیام‌های درون‌برنامه‌ای/درون‌سایتی به کاربران

اگر ترجیح می‌دهید به‌جای خواندن، تماشا کنید، ویدیوهای آموزشی Web SDK همین مباحث را پوشش می‌دهند: راه‌اندازی، شناسایی کاربران و ارسال رویدادها.

پرسش‌های متداول

آیا قبل از ردیابی باید کاربر را authorize کنم؟

بیشتر قابلیت‌ها بدون نیاز به احراز هویت (authorize) کاربر نیز کار می‌کنند. اما اگر بخواهید رویدادها به هویت یک کاربر خاص متصل شوند، بهتر است قبل از ارسال رویدادها authorizeUser() را فراخوانی کنید:


import { authorizeUser, newEvent } from '@metrixorg/websdk';
 
authorizeUser('user123');
newEvent('EVENT_SLUG');

آیا می‌توانم از SDK در SPA استفاده کنم؟

بله. SDK برای برنامه‌های تک‌صفحه‌ای (SPA) طراحی شده و جابه‌جایی بین صفحه‌ها را به‌صورت خودکار مدیریت می‌کند. اگر می‌خواهید تغییر روت‌ها (routes) در SPA شما به عنوان بخشی از ردیابی سشن ثبت شود، این قابلیت را در config مربوط به init فعال کنید.

SDK چه داده‌هایی را به‌صورت خودکار جمع‌آوری می‌کند؟

SDK به‌صورت خودکار این اطلاعات را جمع‌آوری می‌کند:

اطلاعات دستگاه: سیستم‌عامل، نسخه سیستم‌عامل، زبان دستگاه، رزولوشن صفحه
اطلاعات مرورگر: نام مرورگر، نسخه، timezone، offset منطقه زمانی
داده‌های session (در صورت فعال بودن): مدت زمان سشن و جریان فعالیت

اطلاعات اختیاری با تنظیمات:

اطلاعات موقعیت مکانی (اگر location.enabled: true باشد): عرض و طول جغرافیایی
session tracking (اگر sessionTracking.enabled: true باشد): مدت زمان و جریان فعالیت

چطور conversion و install attribution را ردیابی کنم؟

برای راهنمای کامل، مستندات Attribution را ببینید.

آیا HTTPS لازم است؟

HTTPS برای موارد زیر ضروری است:

نوتیفیکیشن‌های وب‌پوش
برخی APIهای مرورگر که SDK از آن‌ها استفاده می‌کند

برای توسعه محلی روی localhost، بیشتر مرورگرها HTTP را می‌پذیرند. با این حال، نوتیفیکیشن پوش همچنان حتی روی localhost هم به HTTPS نیاز دارد.

آیا SDK در WebView کار می‌کند؟

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

رفع اشکال

هشدار “Init called more than once”

SDK به‌صورت خودکار فراخوانی‌های تکراری init را نادیده می‌گیرد. اگر معماری برنامه شما باعث شود init در چند نقطه فراخوانی شود، این رفتار ایمن و طبیعی است. فقط اولین فراخوانی اثر خواهد داشت.

رویدادها در داشبورد نمایش داده نمی‌شوند

بررسی کنید که init قبل از هر متد دیگری از SDK فراخوانی شده باشد.
مطمئن شوید APP_ID و API_KEY درست هستند.
console مرورگر را برای خطاها بررسی کنید.
برای اتصال رویدادها به یک کاربر خاص، در صورت نیاز از authorizeUser() استفاده کنید.
مطمئن شوید اسلاگ (slug) رویداد در داشبورد متریکس تعریف شده است.

نوتیفیکیشن‌های Push کار نمی‌کنند

مطمئن شوید HTTPS فعال است (یا از localhost استفاده می‌کنید).
بررسی کنید فایل Service Worker از ریشه دامنه در دسترس باشد.
مجوزهای نوتیفیکیشن مرورگر را بررسی کنید.
مطمئن شوید در config مربوط به init، گزینه push.enabled: true و publicKey تنظیم شده‌اند.
متد subscribePush() را فراخوانی کنید و هنگام درخواست مرورگر، مجوز را تایید کنید.

پشتیبانی

برای راهنمایی بیشتر:

subscribePush() را فراخوانی کنید و هنگام نمایش اعلان (prompt) مرورگر، دسترسی لازم را تأیید کنید.