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

}

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

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

ارسال ایونت

فعالسازی WebPush

مرحله ۱: اضافه‌کردن فایل ServiceWorker (تنها برای وبسایت‌هایی که پروتکل https دارند)
مرحله ۲: فعالسازی تنظیمات پوش
مرحله ۳: گرفتن اجازه ارسال پوش به کاربر

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

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

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

نسخه

{
title: ‘New Web SDK’,
lang: ‘fa’,
permalink: ‘/sdk/new-web’,
slug: ‘new-web’,
version: ‘1.5.3’,
latest: false,
toc: true,

}

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

برای نصب و شروع به کار 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.5.3) را قرار دهید.

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

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

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

authorizeUser(username: string) : void

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

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

deauthorizeUser() : void

ارسال ایونت

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

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


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';
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 دارند)

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

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

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

تنظیمات پوش
در پارامتر سومی که بعنوان 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.
  }
}

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

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

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

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

Metadata

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

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

os
osVersion
deviceLang
screen

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

browserName
browserVersion
timezone
timezoneOffset