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

برای نصب و شروع به کار 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://box.backtory.com/metricx/sdk/web/metrix.umd-${VERSION}.js"></script>

توجه: به‌ جای ${VERSION}، نسخه مدنظر برای پیاده‌سازی (بطور مثال 1.6.1) را قرار دهید.

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

typescript:

declare let Metrix: any;

Metrix.init(APP_ID, API_KEY, config);

javascript:

Metrix.init(APP_ID, API_KEY, config);

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

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

شناساندن کاربر به متریکس

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

authorizeUser(username: string) : void
نامtypeتوضیحاتاجباری
usernamestringشناسه یکتایی که به یوزر وبسایت خود اختصاص داده‌اید.بله

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

deauthorizeUser() : void

ارسال ایونت

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

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


newEvent(slug: string, customAttributes: {[key: string]: string}): void
نامtypeتوضیحاتاجباری
slugstringslug ساخته شده در داشبورد متریکس برای ایونت مورد نظربله
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';

newEvent('EVENT_SLUG', attributes);

فعالسازی WebPush

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

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


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

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

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

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

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

importScripts('https://box.backtory.com/metricx/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 باشد.

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

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

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

ساخت User و به‌روزرسانی اطلاعات

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

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
setCustomUserId(customId: string) : void

فعالسازی On-Site Messaging

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

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

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

سایر قابلیت‌ها

Metadata

متریکس متادیتاهایی نظیر device و browser را از کاربری که در حال بازدید از وبسایت شماست جمع‌آوری می‌کند.

داده‌هایی که از device کاربر جمع‌آوری می‌شوند عبارتند از:

  • os
  • osVersion
  • deviceLang
  • screen

داده‌هایی که از browser کاربر جمع‌آوری می‌شوند عبارتند از:

  • browserName
  • browserVersion
  • timezone
  • timezoneOffset