O2MC Mobile tracking libraries

Summary

The mobile tracking library exists of two seperate applications. There's an Android version and an IOS version which both can be used as 'native' libraries. on top of that there are React-native bindings available for both platforms.

Prerequisites

As stated above. There are libraries availble for both Android and IOS platforms. To be able to use them you need to have the source code of the application where it's going to be implemented and the latest version of the library. The library can be found on NPM INSERT NPM PACKAGE NAME HERE and inside of the private repository.

Installation Android (Native)

When you have the library downloaded and available make sure to add it to the build path of your application. In Android studio this is done by
1.right clicking on your app package then selecting open module settings
2. Navigate to dependecies in the tabs at the top of the window.
3. Next click the + icon and select add module dependency.
4. A file browser will pop-up and you will need to select the Android folder of the library.
5. After adding the library to your build path it is no available for use within the application.

The current android version of the library has a strong incorperation with the datastreams application
Useage instructions in combination with the datastreams-manager are available at the private application repository.

To initiate the library and use the basic tagging functionalitiy you need to create a new instance of it.

This can be done the following way: 

public class App extends Application {

    private static O2MC o2mc;
    private static Application instance;

    public App(){
        o2mc = new O2MC(this, <HTTP_ENDPOINT>);
        o2mc.tracker.setDispatchInterval(10);
        o2mc.getSettings().setMapViews(false);
    }
}

o2mc.tracker is the attribute that can be used for the basic key-value app tagging functionality. The methods of the API are described at the bottom of the page. They're both identical for IOS & Android

Useage in React native

Edit android/settings.gradle to declare the project directory:

include ':O2MCTracker', ':app'
project(':O2MCTracker').projectDir = new File(rootProject.projectDir, '../node_modules/o2mc-android-tracker/android')

Edit android/app/build.gradle to declare the project dependency: dependencies { ... compile project(':O2MCTracker') }

Edit android/app/src/main/java/.../MainActivity.java to register the native module:

...
import hobby.nickyromeijn.datastreamsforandroid.Dimml.ReactBindings.ReactTrackerPackage; // <-- New
... make sure above import statement is correct. (current example is own environment)

public class MainActivity extends ReactActivity {
  ...
  @Override
  protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
        new new ReactTrackerPackage(<AppName>,<DataEndPoint>,<DispatchInterval>)() // <-- New
    );
  }

When index.js is declared correctly and the steps above are executed the module can be loaded from within the react-native app by importing the module

Installation IOS (Native)

When you have the library downloaded and available make sure to add it to the build path of your application. For IOS this is done in the following way:

  1. Navigate to your Xcode project
  2. Drag & drop the o2mc ios tracking library folder into your project
  3. Select the added folder in Xcode. navigate to build settings
  4. In build settings add a header search path to a react-native folder; make sure to tick recursive search. (react-native can be downloaded from npm)
  5. After this make sure to add the o2mc ios tracking library folder to the header search path of the original app.
  6. this is done the same way as stated at step 4

To initialise the tracking library you need to instantiate the O2MC class. The contructor of this class takes 4 parameters.

  1. The application name
  2. A HTTP endpoint where the data will be sent
  3. Interval in seconds to send data (NSNumber)
  4. ForceTimerStart, set this to true when using the library in an IOS native application.
#import <O2MC.h>
#import <Tagger.h>

@interface ViewController ()

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.O2MC = [[O2MC alloc] init:<APPNAME> :<HTTP ENDPOINT> :<DISPATCH INTERVAL> :<FORCETIMERSTART>;
}

the Tracker object has a public interface of tracking methods which are described at the bottom of the page. Tracking methods can be called by using the Objective C messaging system.

[self.O2MC.tracker track:@"btnPress"]; This demonstrates a simple 'event track'. The "btnPress" is sent to the http endpoint togheter with a timestamp. The resuling message that is sent to the server looks like the following: In this example multiple tracking events have been gathered and are being sent as 'batch' to the designated endpoint.

"application" : {
    "AppId" : "TestApp",
    "device" : "Simulator",
    "connection" : "3G",
    "ip" : "192.168.34.142",
    "operatingSystem" : "9.3.1"
  },
  "tracked" : {
    "btnPress" : [
      {
        "alias" : "995D18ED-FD6B-49E7-8AB9-280B9A1493C3",
        "event" : "btnPress",
        "identitiy" : "",
        "time" : 1470746933.821314
      },
      {
        "alias" : "995D18ED-FD6B-49E7-8AB9-280B9A1493C3",
        "event" : "btnPress",
        "identitiy" : "",
        "time" : 1470746933.951939
      },
      {
        "alias" : "995D18ED-FD6B-49E7-8AB9-280B9A1493C3",
        "event" : "btnPress",
        "identitiy" : "",
        "time" : 1470746934.067823
      }
    ]
  }

Useage in React native

  1. Navigate to your react-native application
  2. Navigate to the IOS folder and open up the Xcode project
  3. Execute same steps as mentioned above (adding the correct header search paths)

After executing these steps you can import the react-native IOS module the following way:
Create an index.js file in the module directory (or it is automatically supplied by pulling from npm). Due to the different nature of Android(Java) and IOS(ObjectiveC) the react-native module is initialised in a slighty different way. The if(NativeModules.o2mcTracker.start) block makes sure the module will be correctly loaded for React-native IOS.

NativeModules.o2mcTracker.start Takes the following constructing parameters
String appId,
String destination,
int dispatchInterval

import { NativeModules } from 'react-native';

if(NativeModules.o2mcTracker.start){
    NativeModules.o2mcTracker.start("AppID", "<HTTP ENDPOINT>", <DISPATCH_INTERVAL_IN_SECONDS>);
    console.log("IOS init");
}

module.exports = NativeModules.o2mcTracker;

When index.js is declared correctly and the steps above are executed the module can be loaded from within the react-native app by importing the module.

DimML & HTTP endpoints

As stated several times above the libraries require the use of an http-endpoint to know where to send the gathered tracking data. Prefereably this is a DimML endpoint so that the data can be parsed and written to a database accordingly.

Example http endpoint (development environment): https://baltar-dev.dimml.io/flow/code.js?dimml.concept=//<USER>@<DIMML_FILE>/<CONCEPT> In my test scenario i sent all the data to a self-written DimmL script which did some json parsing. It unpacked and sorted the data-structure sent by the library (example showed above).

Example flow DimML 

    flow
        => addjson['data']
        => expand['data']
        => expand['application']
        => filter['-application']
        => expand['location']
        => filter['-location']
        => split['tracked']
        => expand['tracked']
        => filter['-tracked']
        => filter['-data']
        => console

The application key of the incoming JSON object exists of general application data. such as : ip, connectionType, phoneType, OS version.

The tracked key is a list of all events that have been gathered by the tracking library.

Public API: React-native, IOS & Android

All events automatically get a timestamp assigned
The system automatically gathers general phone data. (Screensize, Android OS version, Phone type)

Send single string to endpoint
Void Track(String eventName)

Send key value pair to endpoint (make sure second argument is a string and not a javascript object (Use JSON.stringify()) Void trackWithproperties(String eventName, String propertiesAsJson)

Give the user an alias, can be used to match an anonymous user.
Void createAlias(String alias)

Couple an identifier to a user. (Only set once. for example when an user authenticates) When not set the system automatically assigns an uuid at initialisation).
Void identify(String alias)

Start an eventtimer coupled to an eventName.
Void timeEventStart(String eventName)

Stop an eventtimer coupled to eventname. Must be the same as the eventName used at timeEventStart Void timeEventStop(String eventName)

Start an eventtimer coupled to an eventName.
Void timeEventStartWithProps(String eventName, String propertiesAsJson)

Stop an eventtimer coupled to eventname. Must be the same as the eventName used at timeEventStart Void timeEventStopWithProps(String eventName, String propertiesAsJson)

Reset the datafunnel. Removes all gathered data from memory. (Be carefull using this method. it might remove unsent data) Void reset()

Set an endpoint for the data funnel. (Http url)
Void setEndpoint(String endpoint)

Sets the dispatchinterval
Void setDispatchInterval(int interval)