metastreamio-reactjs

React Native data collection for MetaStreamIO analytics services

Installation

npm install metastreamio-reactjs

Run the following to link dependencies:

npm install react-native-device-info &&\
npm install @react-native-community/netinfo &&\
react-native link react-native-device-info &&\
react-native link @react-native-community/netinfo &&\
cd ios &&\
pod install &&\
cd .. &&\
npx pod-install

For Android, add the following to dependencies in android/app/build.gradle:

implementation project(':react-native-device-info')

Modify your android/build.gradle:

buildscript {
  ext {
    buildToolsVersion = "28.0.3"
    minSdkVersion = 16
    compileSdkVersion = 28
    targetSdkVersion = 28
    # Only using Android Support libraries
    supportLibVersion = "28.0.0"
  }

For Android with AndroidX:

buildscript {
  ext {
    buildToolsVersion = "28.0.3"
    minSdkVersion = 16
    compileSdkVersion = 28
    targetSdkVersion = 28
    # Remove 'supportLibVersion' property and put specific versions for AndroidX libraries
    androidXCore = "1.0.2"
    // Add other AndroidX dependencies here
  }

Setup

Enable session tracking by keeping the tracker instance in state

Configure an instance

const msio = require("metastreamio-reactjs");

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

let tracker = new msio.MetaStreamIO(metastreamioConfig);
export { 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

• Added post headers to instantiation configuration

1.1.4

• Reinstated network info - connection type and cellular generation
• 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
• Unique device ID defaults to null instead of not set

1.1.3

• Added unique device ID to device model
• Fixed bug where allowTrackCategories and loggingCategories did not evaluate empty arrays properly

1.1.2

• Last update time and first installation time bug fixes

1.1.0

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

1.0.14

• Removed AsyncStorage dependency
• Forced the setting of a null CIAM ID for convenience

1.0.13

• Introduced CIAM ID support
• Forced the starting of a session in guestMode for convenience