@metrixorg/websdk NPM

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} with latest.

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:
Netxjs sample
Pure html/js sample

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 before subscribePush method and config publicKey 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.