Web SDK (New) | Metrix

نصب و راه‌اندازی

برای نصب و شروع به کار WebSDK متریکس مراحل زیر را انجام دهید:

برای نصب با استفاده از npm دستور زیر را در پروژه خود اجرا نمایید:

npm install @metrixorg/websdk

سپس با استفاده از قطعه کد زیر WebSDK متریکس شروع به کار می‌کند:

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

با استفاده از تگ <script> :

اگر امکان نصب با استفاده از npm را ندارید می‌توانید تگ <script> زیر را درون <head> پروژه خود قرار دهید.

<script src="https://cdn.metrix.ir/sdk/web/metrix.umd-2.2.0.js"></script>

سپس برای شروع به کار WebSDK متریکس، به این صورت متد زیر را فراخوانی نمایید:

typescript:

declare let Metrix: any;
 
Metrix.init(APP_ID, API_KEY, config);

javascript:

Metrix.init(APP_ID, API_KEY, config);

پارامترهایی که متد init دریافت می‌کند به صورت جدول زیر است:

نام	type	توضیحات	اجباری
APP_ID	`string`	شناسه اپلیکیشن شما. می‌توانید این شناسه را از قسمت Settings > App Info داشبورد متریکس پیدا کنید.	بله
API_KEY	`string`	این کلید را از قسمت Settings > S2S Integration داشبورد متریکس بردارید یا جدید بسازید.	بله
config	`Object`	این کانفیک برای فعال کردن WebPush و OnSite Messaging و ردیابی نشست کاربران استفاده خواهد شد، که در ادامه توضیح داده می‌شود.	خیر

شمارش نصب و ردیابی نشست کاربران(مختص سرویس اتریبیوشن)

برای فعال کردن ردیابی نشست کاربران از طریق SDK متریکس باید در پارامتر config که پارامتر سوم از متد init است کانفیگ زیر را قرار دهید:

{
  sessionTracking: {
    enabled: true; // default is false.
    packageName: 'YOUR_APP_PACKAGE_NAME';
  }
}

شمارش نصب در اپ‌های TWA

با توجه به اینکه شناسه های مورد نیاز برای فرآیند اتریبیوشن مثل Google Advertising Id در سمت وب قابل دریافت نیست و در حال حاضر، تنها راه ارتباط بین اندروید نیتیو و وب‌اپ، در TWA آدرس لانچ شدن وب‌اپ است؛ بنابراین برای افزایش دقت اتریبیوشن و شمارش نصب در چنین شرایطی، نیازمند دریافت این شناسه، توسط اپلیکیشن اندرویدی مشتری از کتابخانه گوگل و اضافه شدن آن به کوئری پارامترهای آدرس اپلیکیشن وب است. در زیر دستورالعمل های لازم برای انجام این فرآیند و لینک مستندات مورد نیاز برای پیادسازی توضیح داده شده است.

وابستگی مورد نیاز که باید برای دریافت این id به پروژه اضافه شود:

com.google.android.gms:play-services-ads-identifier:18.0.1

و همینطور مستندات مربوط به پیاده‌سازی جهت دریافت Google Advertising Id از طریق این لینک در دسترس است.

این آی‌دی باید با کلید gps_adid به کوئری پارامترهای آدرس لانچ‌شدن وب‌اپ مانند مثال زیر اضافه شود:
https://domain.example?gps_adid=DEVICE_ADVERTISING_ID

نمونه کد TWA که پیاده‌سازی دریافت Google Advertising Id در آن انجام شده است از طریق این لینک در دسترس است.

شمارش نصب در اپ‌های PWA

از آنجایی که در اپ‌های PWA که تحت وب هستند؛ شناسه‌ی یکتایی از دستگاهی که آن را نصب کرده است در دسترس نیست اولین نشست کاربران در این‌گونه اپ‌ها به عنوان نصب شمرده‌ می‌شود، لذا پیشنیازی برای شمارش نصب اینگونه اپ‌ها لازم نیست. تنها باید ردیابی نشست کاربران همانگونه که ذکر شد، فعال شود.

دریافت شناسه

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

onMetrixUserIdReceived().then((metrixUserId: string) => {
  // todo
});

شناساندن کاربر به متریکس و ساخت User (مختص سرویس اتومیشن)

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

authorizeUser(username: string) : void

نام	type	توضیحات	اجباری
username	`string`	شناسه یکتایی که به یوزر وبسایت خود اختصاص داده‌اید.	بله

همچنین برای بازگرداندن کاربر به حالت ناشناس در هنگام logout، متد زیر را فراخوانی کنید.

deauthorizeUser() : void

دریافت شناسه

برای هر User ایکه در جدول User Lookup در دسترس است؛ سمت متریکس یک شناسه در نظر گرفته می‌شود؛ این شناسه به محض ایجاد از طریق متد زیر در دسترس است:

onAutomationUserIdReceived().then((automationUserId: string) => {
  // todo
});

ارسال ایونت (سرویس اتریبیوشن و اتومیشن)

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

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

 
newEvent(slug: string, customAttributes: {[key: string]: string}): void

نام	type	توضیحات	اجباری
slug	`string`	slug ساخته شده در داشبورد متریکس برای ایونت مورد نظر	بله
customAttributes	`{[key: string]: string}`	هر خصیصه دلخواهی که مرتبط با ایونت مورد نظر باشد می‌تواند در customAttributes ارسال شود	خیر

شما می‌توانید از متریکس برای ردیابی هرگونه رخداد و ایونتی درون وبسایت خود استفاده کنید.
بعنوان مثال فرض کنید قصد دارید کلیک کردن روی یک button در وبسایت خود را ردیابی نمایید. برای این کار باید ایونت مخصوص به این رخداد را در قسمت مدیریت ایونت‌های داشبورد متریکس ایجاد نمایید. (Settings > Events > Add event) و slug تولیدی این ایونت را برای ارسال ایونت، در کد وبسایت خود استفاده کنید. بنابراین در متد onckick برای button مورد نظر خود باید متد newEvent متریکس را با slug ایونت ساخته شده و همچنین، به صورت دلخواه، همراه با تعدادی customAttribute به صورت زیر فراخوانی کنید:

// Send simple event
import { newEvent } from '@metrixorg/websdk';
newEvent('EVENT_SLUG');
 
// Send an event with custom attribute
const attributes = {};
attributes['first_name'] = 'Ali';
attributes['last_name'] = 'Bagheri';
attributes['manufacturer'] = 'Nike';
attributes['product_name'] = 'shirt';
attributes['type'] = 'sport';
attributes['size'] = 'large';
attributes['purchase_date'] = '2024-11-20T11:24:03.000Z'; // use ISO 8601 to consider this attribute as a date
 
newEvent('EVENT_SLUG', attributes);

فعالسازی WebPush (مختص سرویس اتومیشن)

متریکس برای ارسال پوش به هر کاربر، یک User سمت خود می‌سازد (اگر Userای برای آن کاربر وجود نداشته باشد.) که این User بعد از کسب اجازه دریافت پوش از کاربر، ساخته شده و در داشبورد متریکس در صفحه User Lookup قابل نمایش است.
اگر متد authorizeUser برای کاربری که اجازه دریافت پوش را می‌دهد فراخوانی نشده باشد، این یوزر به صورت Anonymous یا ناشناس سمت سرورهای متریکس ساخته می‌شود. در واقع در این حالت بازای هر Device که اجازه دریافت پوش را می‌دهد یک User سمت سرورهای متریکس ساخته می‌شود.
اما اگر می‌خواهید کاربری که اجازه دریافت پوش را می‌دهد، شناخته‌شده باشد و کاربر ناشناس نباشد باید متد authorizeUser برای این کاربر فراخوانی شده باشد. همچنین با صدا زدن متدهای مرتبط با User می‌توانید اطلاعات آن User را تکمیل نمایید.

می‌توانید از نمونه پیاده‌سازی‌های زیر برای پیاده‌سازی WebPush در وبسایت خود استفاده نمایید

Netxjs sample

Pure html/js sample

برای فعالسازی WebPush، مراحل زیر را دنبال نمایید:

مرحله ۱: اضافه‌کردن فایل ServiceWorker (تنها برای وبسایت‌هایی که پروتکل https دارند)

در صورتی که در وبسایت خود فایل ServiceWorker ندارید یا اگر سرویس‌ورکری دارید که در قبل برای ارسال وب‌پوش به کاربر استفاده می‌کردید، این فایل را دانلود کرده و در root پروژه خود قرار دهید. (به این معنی است که در جایی در کنار فایل‌های index.html یا index.php قرار دهید. )

توجه کنید: این فایل باید در انتهای آدرس دامنه وبسایت شما در دسترس باشد. بطور مثال اگر دامنه وبسایت شما https://dashboard.metrix.ir است، این فایل باید در آدرس https://dashboard.metrix.ir/metrix-sw.js در دسترس باشد.

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

importScripts('https://cdn.metrix.ir/sdk/web/metrixweb-sw.js');

همچنین داخل کانفیگ راه‌اندازی وب‌پوش ، hasSW: true را قرار دهید.

مرحله ۲: فعالسازی تنظیمات پوش

تنظیمات پوش در پارامتر سومی که بعنوان config به متد init پاس داده می‌شود، صورت می‌گیرد.

کانفیگ راه‌اندازی وب‌پوش:

{
  push: {
    enabled: true; // default is false but if set to true you must provide publicKey.
    publicKey: YOUR_PUBLIC_KEY; // your push subscription public key.
    hasSW: false; // (OPTIONAL) default is false, if you already have a serviceWoker that does something except sending webpush set this to true.
  }
}

publicKey توسط متریکس در اختیار شما قرار می‌گیرد.

مرحله ۳: گرفتن اجازه ارسال پوش به کاربر

گرفتن اجازه ارسال پوش به کاربر به دو روش امکان‌پذیر است:

روش اول: فراخوانی متد

شما می‌توانید با فراخونی متد subscribePush() در هرجایی از وبسایت خود (بطور مثال پاپ‌آپی که مختص وبسایت شماست) از کاربر اجازه ارسال پوش را دریافت کنید.

subscribePush() : void

این مورد را در نظر داشته باشید که فراخوانی متد init همراه با کانفیک پوش باید قبل از فراخوانی متد subscribePush باشد.

روش دوم: Backdrop

backdrop-image

Backdrop به دو صورت می‌تواند به کاربر نمایش داده شود و از آن اجازه ارسال پوش را دریافت کنید. این دو روش به صورت زیر است:

باز شدن هنگام شروع به کار SDK: با اضافه کردن پارامتر‌های زیر به کانفیگ پوش می‌توانید backdrop را هنگام شروع به کار SDK باز کنید. بازشدن backdrop می‌تواند با تنظیم مقدار backdropDelay به تاخیر بیوفتد. و همچنین متن نمایشی درون آن با مقدار backdropText قابلیت شخصی‌سازی دارد.

{
  push: {
  ...
  showBackdrop: true,
  backdropDelay: 1000,  // Delay time in ms.
  backdropText: 'SAMPLE_TEXT', // Text to show inside backdrop.
}
}

باز شدن با فراخوانی متد: با فراخوانی متد openPushConfirmBackdrop می‌توانید backdrop را به طور دلخواه در هر زمان باز کنید.

openPushConfirmBackdrop({
  backdropDelay: 1000, // Delay time in ms.
  backdropText: 'SAMPLE_TEXT', // Text to show inside backdrop.
});

روش سوم: زنگوله متریکس

با اضافه کردن showBell که مقدار true دارد به کانفیگ پوش زنگوله متریکس نمایش داده شده و با کلیک‌شدن روی آن اجازه ارسال پوش را از کاربر می‌گیرد.

{
  push: {
  ...
  showBell: true // default is false
}
}

نکات ارسال پوش در ios

به دلیل وجود محدودیت‌هایی در سیستم‌عامل ios برای ارسال پوش لازم است نکات زیر در نظر گرفته شود:

طبق این لینک ، ارسال پوش در ios از ios 16.4 به بالا و در سیستم‌عامل مک از نسخه macOS 13 به بالا پشتیبانی می‌شود.
در سیستم‌عامل ios تنها اپ‌های PWA که Add to home screen شده باشند اجازه ارسال پوش دارند. (حتی webpageهایی که Add to home screen شده باشند هم اجازه ارسال پوش را نخواهند داشت. در نتیجه حتما باید از اپ PWA استفاده کنید.)
پرامپت اجازه ارسال پوش حتما باید روی اکشنی از کاربر باز شود. (بطور مثال کلیک روی یک دکمه). در نتیجه فراخوانی متد subscribePush یا بازکردن Backdrop در لود اپ بی‌تاثیر بوده و توسط سیستم‌عامل بلاک خواهد شد. (این اتفاق در مرورگرهایی نظیر سافاری و گوگل‌کروم یکسان است.)

اطلاع از وضعیت دریافت پوش کاربر

با استفاده از متد زیر، می‌توانید از وضعیت اجازه کاربر به مرورگر برای پوش مطلع شوید:

notificationPermissionState(): 'granted' | 'denied' | 'default' | undefined

Permission State Values

به‌روزرسانی اطلاعات User (مختص سرویس اتومیشن)

با استفاده از متدهای زیر پس از فراخوانی authorizeUser می‌توانید اطلاعات User های موجود در User Lookup را به‌روز‌رسانی کنید.

setFirstName(firstName: string) : void

setLastName(lastName: string) : void

setEmail(email: string) : void

setHashedEmail(hashedEmail: string) : void

setPhoneNumber(phoneNumber: string) : void

setHashedPhoneNumber(hashedPhoneNumber: string) : void

setCountry(country: string) : void

setCity(city: string) : void

setRegion(region: string) : void

setLocality(locality: string) : void

setGender(gender: string) : void

setBirthday(birthday: string) : void

setCustomAttribute(key: string, value: string) : void

فعالسازی On-Site Messaging (مختص سرویس اتومیشن)

برای فعالسازی، در داخل onSiteMessaging در آبجکت کانفیگ، مقدار enabled را true قرار دهید.

{
  ...
    onSiteMessaging: {
  enabled: true // defaults to false
}
}

توجه داشته باشید کاربر برای دریافت مسیج‌های درون‌سایتی باید توسط authorizeUser به متریکس شناسانده شده باشد.