@metrixorg/websdk
v2.4.0
Published
These instructions will get you setup to use `WebSDK` in your project.
Downloads
597
Keywords
Readme
Getting Started
These instructions will get you setup to use WebSDK
in your project.
install using npm
:
npm install @metrixorg/websdk
Initialize Metrix at the start of your application by calling the following method:
import { init } from '@metrixorg/websdk';
init(APP_ID, API_KEY, config);
Or add within <script>
tag:
Place the following <script>
inside <head>
of your project.
<script src="https://box.backtory.com/metricx/sdk/web/metrix.umd-${VERSION}.js"></script>
Note: Replace
${VERSION}
with desired version(e.g.,1.6.0
). or to always use latest version replace${VERSION}
withlatest
.
Initialize Metrix at the start of your application by calling the following method:
typescript:
declare let Metrix: any;
Metrix.init(APP_ID, API_KEY, config);
javascript:
Metrix.init(APP_ID, API_KEY, config);
| name | type | description | required |
| :-----: | :------: | :-------------------------------------------------------------------------------------------------------: | :------: |
| APP_ID | string
| Your application identifier. You can find this id in your Metrix dashboard under Settings > App Info. | true |
| API_KEY | string
| You can find this key in dashboard. | true |
| config | Object
| config to enabling PUSH_SDK and track user location | false |
API
authorizeUser
To authorize user to Metrix server, you must call this API.
authorizeUser(username: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-----------------------------------------: | :------: |
| username | string
| name of user to authorize to metrix servers | true |
Note: To know the user to Metrix's servers call this method, before sending any data to Metrix's servers
newEvent
Each interaction that the user has with your application can be introduced as an Event in your dashboard and application in order for Metrix to collect and present its statistics.
newEvent(slug: string, customAttributes: {[key: string]: string}): void
| name | type | description | required |
| :--------------: |:-------------------------:| :-----------------------------------: | :------: |
| slug | string
| generated event slug in dashboard | true |
| customAttributes | {[key: string]: string}
| any custom attribute related to event | false |
You can use Metrix to track any events in your application.
Suppose you want to track every tap on a button.
You would have to create a new event in the Events Management section of your dashboard (Settings > Events > Add event) and retrieve the generated slug
for the event.
The slug
is to be used in the application code to send the event to Metrix library.
So In your button's onClick method you could then invoke the Metrix newEvent
method providing the event slug
and
optionally some attributes named customAttributes
related to the event like the following:
// 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);
setCustomAttribute
setCustomAttribute(key: string, value: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-----------------------: | :------: |
| key | string
| key of custom attribute | true |
| value | string
| value of custom attribute | true |
setCustomUserId
setCustomUserId(customId: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :------------: | :------: |
| customId | string
| user custom ID | true |
setFirstName
you can use metrix WebSDK to store user session visiting your application. By this method you can send user first name to metrix library.
setFirstName(firstName: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-------------: | :------: |
| firstName | string
| user first name | true |
setLastName
By this method you can send user last name to metrix library.
setLastName(lastName: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-------------: | :------: |
| lastName | string
| user first name | true |
setEmail
By this method you can send user email to metrix library.
setEmail(email: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------: | :------: |
| email | string
| user email | true |
setHashedEmail
By this method you can send user hashed email to metrix library.
setHashedEmail(hashedEmail: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------------: | :------: |
| hashedEmail | string
| user hashed email | true |
setPhoneNumber
By this method you can send user phone number to metrix library.
setPhoneNumber(phoneNumber: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------------: | :------: |
| phoneNumber | string
| user phone number | true |
setHashedPhoneNumber
By this method you can send user phone number as hashed phone number to metrix library.
setHashedPhoneNumber(hashedPhoneNumber: string) : void
| Parameter Name | Parameter Type | description | required |
| :---------------: | :------------: | :----------------------: | :------: |
| hashedPhoneNumber | string
| user hashed phone number | true |
setCountry
By this method you can send user country to metrix library.
setCountry(country: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :----------: | :------: |
| country | string
| user country | true |
setCity
By this method you can send user city to metrix library.
setCity(city: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------: | :------: |
| city | string
| user city | true |
setRegion
By this method you can send user city to metrix library.
setRegion(region: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------: | :------: |
| region | string
| user region | true |
setLocality
By this method you can send user locality to metrix library.
setLocality(locality: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-----------: | :------: |
| locality | string
| user locality | true |
setGender
By this method you can send user gender to metrix library.
setGender(gender: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :---------: | :------: |
| gender | string
| user gender | true |
setBirthday
By this method you can send user birthday date to metrix library.
setBirthday(birthday: string) : void
| Parameter Name | Parameter Type | description | required |
| :------------: | :------------: | :-----------: | :------: |
| birthday | string
| user birthday | true |
Web Push
You can find sample applications for implementing Metrix WebSdk to sending web push notifications in following:
To enabling web push, follow these steps:
Step 1: Add Service Worker File (only for sites with HTTPS protocol)
download this file and put it at root of your project files ( this means somewhere beside index.html
or index.php
file ).
Note: this file must be accessible with end of your site domain URL. for example if domain is https://dashboard.metrix.ir this file must be accessible with https://dashboard.metrix.ir/metrix-sw.js.
Step 2: Enable Push config
pass this config as third parameter to init
method.
import { init } from '@metrixorg/websdk';
init(APP_ID, API_KEY, config);
PUSH initialization config:
{
push: {
enabled: true; // default is false but if set to true you must provide publicKey.
publicKey: YOUR_PUBLIC_KEY; // your push subscription public key.
showBell: true; // default is false
hasSW: false // default is false
}
}
There are two modes to grant permission from user and send web push notification.
Mode 1: Metrix Bell
By adding showBell
set to true
to push config. Metrix bell shows and can get permission from user and send push to user.
{
push: {
...
showBell: true // defaults to false
}
}
Mode 2: Calling method
You can call subscribePush()
method anywhere from your website to get permission from user and send push to user.
subscribePush() : void
Note: Logically you should call
init
method beforesubscribePush
method and configpublicKey
and other configs to sending push.
On-Site messaging
Enable this feature, by adding enabled
set to true
to onSiteMessaging
in config object.
{
...
onSiteMessaging: {
enabled: true // defaults to false
}
}
Note: You should authorize your user to Metrix by
authorizeUser(username: string): void
method.
Additional Features
Session Tracking (coming soon)
Metrix
, tracks sessions visiting your website/application and collect data from their activity.
types of activity are:
duration
: session duration time, the time that user is active on your website/application tab by specified session.note: The time when the user leaves your website/application tab is not counted as session duration. Therefore, when the user returns to your website/application tab, the duration of the session is calculated from that moment.
activityFlow
: array of pages address of your website/application that the user has viewed.
Metadata
Metrix
, collect metadata from user device, browser and location of user visiting your website/application.
data that is collect from device is:
os
osVersion
deviceLang
screen
data that is collect from browser is:
browserName
browserVersion
timezone
timezoneOffset
location data is:
latitude
longitude