مستندات فنی اتومیشن

راهنمای Automation New Web برای توسعه دهندگان

متریکس
نسخه

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

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

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

  1. npm install @metrixorg/websdk

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

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

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

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

  1. <script src="https://box.backtory.com/metricx/sdk/web/metrix.umd-${VERSION}.js"></script>

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

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

typescript:

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

javascript:

  1. 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 استفاده خواهد شد، که در ادامه توضیح داده می‌شود. خیر

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

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

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

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

  1. deauthorizeUser() : void

ارسال ایونت

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

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

  1. 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
به صورت زیر فراخوانی کنید:

  1. // Send simple event
  2. import { newEvent } from '@metrixorg/websdk';
  3. newEvent('EVENT_SLUG');
  4. // Send an event with custom attribute
  5. const attributes = {};
  6. attributes['first_name'] = 'Ali';
  7. attributes['last_name'] = 'Bagheri';
  8. attributes['manufacturer'] = 'Nike';
  9. attributes['product_name'] = 'shirt';
  10. attributes['type'] = 'sport';
  11. attributes['size'] = 'large';
  12. 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
نمایید.

  1. importScripts('https://box.backtory.com/metricx/sdk/web/metrixweb-sw.js');

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

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

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

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

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

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

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

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

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

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

  1. subscribePush() : void

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

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

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

  1. {
  2. push: {
  3. ...
  4. showBell: true // default is false
  5. }
  6. }

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

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

  1. setFirstName(firstName: string) : void
  1. setLastName(lastName: string) : void
  1. setEmail(email: string) : void
  1. setHashedEmail(hashedEmail: string) : void
  1. setPhoneNumber(phoneNumber: string) : void
  1. setHashedPhoneNumber(hashedPhoneNumber: string) : void
  1. setCountry(country: string) : void
  1. setCity(city: string) : void
  1. setRegion(region: string) : void
  1. setLocality(locality: string) : void
  1. setGender(gender: string) : void
  1. setBirthday(birthday: string) : void
  1. setCustomAttribute(key: string, value: string) : void
  1. setCustomUserId(customId: string) : void

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

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

  1. {
  2. ...
  3. onSiteMessaging: {
  4. enabled: true // defaults to false
  5. }
  6. }

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

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

Metadata

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

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

  • os
  • osVersion
  • deviceLang
  • screen

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

  • browserName
  • browserVersion
  • timezone
  • timezoneOffset