metastreamio-web

React JS data collection for MetaStreamIO analytics services

Installation

npm install metastreamio-web

Setup

Enable session tracking by keeping the tracker instance in state

Configure an instance

import MetaStreamIO from "metastreamio-web";

let metastreamioConfig = {
  app: {
    id: "core",
    channel: "web",
    environment: "default",
    endpoints: ["http://127.0.0.1:5000"],
    headers: {},
  },
  config: {
    logging: true,
    loggingLevel: "INFO",
    loggingCategories: ["event", "cart", "network", "user"],
    loggingAlwaysWarn: true,
    loggingAlwaysError: true,
    silentMode: false,
    sessionLength: null,
  },
  user: {
    guestMode: true,
    user_id: null,
    ciam_id: null,
    email_id: null,
    country: null,
    cart_id: null,
  },
};

let tracker = new MetaStreamIO(metastreamioConfig);
export default tracker;

Config: app

id project id from MetaStreamIO

channel identify the project as web/app/other (any value)

environment usually dev or live depending on configuration

endpoints an array of endpoints that share the project

headers an object containing headers to send with endpoint checks and event tracking

Config: config

allowTrackCategories an array of categories to allow - events tracked with no or null category will always be allowed, and specifying an empty array or null allows all event categories to be tracked

logging turns on console logging

loggingLevel logs events above a certain level; values are INFO, DEBUG, WARN, ERROR

loggingCategories an array of user defined categories to show logs for ([cart,environment,event,network,network-request,project]) - specifying null or an empty array will log all types

loggingAlwaysWarn allows warnings to be logged regardless of their category (obeys loggingEnabled)

loggingAlwaysError allows errors to be logged regardless of their category (obeys loggingEnabled)

silentMode prevents data from being posted

sessionLength controls the timeout and creation of new session IDs (seconds); defaults to 1800 (30 minutes)

Config: user

guestMode forces the session to start when the tracker is initialised - assigns a non-unique "guest" id

user_id set a user ID immediately; defaults to an auto-generated ID

email_id set an email ID immediately; defaults to null

cart_id set a cart ID immediately; left blank it will be auto-generated or retrieved from app storage

country use the ISO-3166 Alpha 2 country code

Session Management

Start the session

User ID and cart ID are optional. Must be called if guestMode is disabled.

tracker.start_session({user_id: '', cart_id: '', email_id: ''});

End the session

Starts a new session

An event named logout will trigger the same behaviour

tracker.start_session({reset: true});

Set the session source

tracker.session.setSource("your source")

Set the session UTM parameters

tracker.session.setUTM({
  utm_source: "your source",
  utm_medium: "your medium",
  utm_campaign: "your campaign",
  utm_term: "your term or keyword",
  utm_content: "your content",
})

Track Events

tracker.trackEvent({
    eventName: "action",
    eventParameters: [{
        key: "param name",
        value: "a value"
    }],
    transactionId: "your txid",
    category: "your event category"
});

eventParameters is an array of key/value pairs as illustrated

transactionId is an id returned by the transactional system, if applicable

category is used to identify the event when checking against allowTrackCategories if it should be tracked or not

Track a quick purchase (bypass cart)

tracker.trackQuickBuy({
  eventName: "quick_buy",
  eventParameters: [{
    key: "name",
    value: "value"
  }],
  temporaryCart: {
    id: "unique bundle ID",
    name: "bundle name",
    type: "product type",
    validity: "xx days",
    value: "GB | MB",
    price: 123.45,
    quantity: 1,
    recipients: [],
  },
  transactionId: "your txid"
})

Set User Attributes

Set user ID

tracker.user.set("user id");

Set CIAM ID

tracker.user.setCiam("ciam id");

Set Email ID

tracker.user.setEmail("email id");

Set user country

tracker.user.setCountry("country");

Set device token (push notifications)

tracker.user.setDeviceToken("token");

Set a user property

tracker.userproperties.set({
  key: "property name",
  value: "property value"
});

Delete a user property

tracker.userproperties.delete({key: "property key"});

Set user account type

tracker.account.setType("account type");

Set user account balance

tracker.account.setBalance({
  account: "account name",
  balance: 123.55
});

Set multiple balances

tracker.account.setBalances(
  [{
    account: "account name",
    balance: 123.55
  }, ...]
)

Shopping Cart

The cart will be tracked with every event until it’s cleared, or an event named "purchase" is tracked.

Set cart ID

tracker.cart.setCartId("cart id");

Add items to the cart

tracker.cart.add(
  [
    {
      id: "unique bundle ID",
      name: "bundle name",
      type: "product type",
      validity: "xx days",
      value: "GB | MB",
      price: 123.45,
      quantity: 1,
      recipients: [],
    },
  ]
)

Reduce the quantity of an item in the cart

quantity represents the amount to reduce the existing quantity by

tracker.cart.reduce(id, quantity)

Delete an item from the cart

tracker.cart.delete(id)

Clear the cart

tracker.cart.clear()

Logging

Set allowed categories after initialisation

categories is a list of allowed categories, setting to [] allows all events to pass

setAllowTrackCategories(categories)

Changelog

1.1.6

• Read recipients from cart.add() method
• Add user.setEmail() method

1.1.5

• Omitted for clarity

1.1.4

• Added post headers to instantiation configuration
• Updated implementation example

1.1.3

• Renamed network request object logging category to network-request
• UTM parameters default to null instead of unassigned
• Session source defaults to null instead of not set

1.1.2

• Fixed bug where allowTrackCategories and loggingCategories did not evaluate empty arrays properly

1.1.1

• Moved from import to require for all dependencies

1.1.0

• Introduce allowTrackCategories feature for finer control over what gets tracked in a permission-based context

1.0.0

• First release