react-native-ibm-mobilefirst/wlAnalytics.js

React Native SDK for IBM Mobile Foundation on IBM Cloud

/* Licensed Materials - Property of IBM
 * 5725-I43 (C) Copyright IBM Corp. 2018. All Rights Reserved.
 * US Government Users Restricted Rights - Use, duplication or
 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 */

 /* author - Srihari Kulkarni | skulkarni@in.ibm.com | Slack - @Srihari */

import {
  NativeModules,
} from 'react-native';

var wlAnalytics = NativeModules.RNWLAnalytics;

const _mandatoryParam = function(parameterName){ throw new Error('Error: Missing parameter ' + parameterName ); };


/**
 * WLAnalytics means of persistently capturing analytics data and provides a method call to send captured data to the IBM MobileFirst Platform server, to be forwarded to the Operational Analytics engine.
 *
 * Capture is on by default.
 * 
 * When this WLAnalytics class's capture flag is turned on via enable method call, all messages passed through this class's log method will be persisted to file in the following JSON object format:
 * 
 * {
 *   "timestamp"    : "17-02-2013 13:54:27:123",  // "dd-MM-yyyy hh:mm:ss:S"
 *   "level"        : "ERROR",                    // ERROR || WARN || INFO || LOG || DEBUG
 *   "package"      : "your_tag",                 // typically a class name, app name, or JavaScript object name
 *   "msg"          : "the message",              // a helpful log message
 *   "metadata"     : {"hi": "world"},            // (optional) additional JSON metadata, appended via doLog API call
 *   "threadid"     : long                        // (optional) id of the current thread
 * }
 */
class WLAnalytics{
  
 /**
  * @ignore
  */
  constructor(){
  }


 /**
  * Accepted values for device events
  */
  DeviceEvent = {
      LIFECYCLE: "appSession",
      NETWORK: "network"
  }
  
  /**
   * Enable persistent capture of analytics data. Enable, and thus capture, is the default.
   */
  enable(){
    wlAnalytics.enable(); 
  }

  /**
   * Disable persistent capture of analytics data.
   */
  disable(){
    wlAnalytics.disable(); 
  }

  /**
   * Log data you want to be captured in the context of "analytics". Some data is already captured by the framework. 
   * To avoid collisions, the following keys will be excluded if logged:
   * appStoreID
   * appStoreLabel
   * appStoreVersion
   * appStoreVersionDisplay
   * mfpAppName
   * mfpAppVersion
   * deviceBrand
   * deviceOSversion
   * deviceOS
   * deviceModel
   * deviceID
   * timezone
   * timestamp
   * @param {string} message - The message to be logged
   * @param {Object} metadata - Any additional metadata to be added to the log message.
   */
  log(message = _mandatoryParam('message'), metadata){
    wlAnalytics.log(message, metadata); 
  }
  
  /**
   * Enable analytics to capture the specified DeviceEvent
   * @param {string} deviceEvent - A string representation of the device event to capture. Accepted values are in DeviceEvent object - check usage example below
   * @example 
   * WLAnalytics.addDeviceEventListener(WLAnalytics.DeviceEvent.LIFECYCLE);
   * WLAnalytics.addDeviceEventListener(WLAnalytics.DeviceEvent.NETWORK);
   */
  addDeviceEventListener(deviceEvent = _mandatoryParam('deviceEvent')){ 
    wlAnalytics.addDeviceEventListener(deviceEvent);
  }

  /**
   * Disable analytics from capturing the specified DeviceEvent
   * @param {string} deviceEvent - A string representation of the device event to remove. Accepted values are in DeviceEvent object - check usage example below
   * @example 
   * WLAnalytics.removeDeviceEventListener(WLAnalytics.DeviceEvent.LIFECYCLE);
   * WLAnalytics.removeDeviceEventListener(WLAnalytics.DeviceEvent.NETWORK);
   */
  removeDeviceEventListener(deviceEvent = _mandatoryParam('deviceEvent')){ 
    wlAnalytics.removeDeviceEventListener(deviceEvent);
  }

  /**
   * Send the accumulated log data when the persistent log buffer exists and is not empty.
   */
  send(){
    wlAnalytics.send(); 
  }

  /**
   * Send the accumulated log data when the persistent log buffer exists and is not empty.
   * @return {Promise} 
   */
  async sendWithCallback(){
    return await wlAnalytics.sendWithCallback(); 
  }

  /**
   * Specify current application user. If you want user-based analytics, you must use this method call. 
   * For example, use it when the user logs in, and call the unsetUserContext method when the user logs out. 
   * Or if your application supports user profiles, call this method when the user profile changes.
   * @param {string} user - User ID for the current app user. 
   */
  setUserContext(user = _mandatoryParam('user')){
    wlAnalytics.setUserContext(user);
  }

  /**
   * Unset any user context previously set.
   */
  unsetUserContext(){
    wlAnalytics.unsetUserContext();
  }
}
export default WLAnalytics