نصب و راهاندازی
برای نصب و شروع به کار 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';
newEvent('EVENT_SLUG', attributes);
ساختن رویداد درآمدی (مختص سرویس اتریبیوشن)
با استفاده از این تابع میتوانید یک رویداد درآمدی بسازید. برای این کار در ابتدا در پنل خود از قسمت مدیریت رویدادها، رویداد موردنظر خود را ثبت کنید و نامک (slug) آن را به عنوان نام رویداد در اپلیکیشن استفاده کنید.
newRevenue('EVENT_SLUG', 12000, 'IRR');
ورودیهای متد newRevenue بدین شرح هستند:
نام | type | توضیحات | اجباری |
---|---|---|---|
slug | string | slug ساخته شده در داشبورد متریکس برای ایونت مورد نظر | بله |
revenue | number | مقدار درآمد | بله |
currency | IRR (Default) or USD or EUR | واحد پول | خیر |
فعالسازی 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://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 به دو صورت میتواند به کاربر نمایش داده شود و از آن اجازه ارسال پوش را دریافت کنید. این دو روش به صورت زیر است:
- باز شدن هنگام شروع به کار 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
بهروزرسانی اطلاعات 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
به متریکس شناسانده شده باشد.