DOCUMENTATION

Datagran
IOS SDK

For mobile app developers, looking to track their application usage, Datagran provides an IOS framework. When embedded, this framework automatically collects data about a number of standardIOS events and sends them to Datagran servers. Additionally, the framework exposes key APP methods that developers can use to pass on additional interaction data specific to their business case.

This document provides a brief overview of the app architecture, the data it collects automatically, and also examples of how developers can use this framework to collect arbitrary interaction data.

1. App Architecture and Workflow

The Datagran IOS framework is written in Swift to process all user interaction data. All data collected by an app using our framework is internally formatted as structured events and then transparently sent to our backend APIs which do the necessary authentication, before forwarding these events on for further processing. Many of the standard IOS events are tracked natively, but the developer can also send arbitrary JSON data in the form of custom events. The workflow is something like this:

1. Create an IOS data source in the Datagran dashboard (app.datagran.io)
2. Developer is issued an APP key(separate key for each IOS data source)
3. Download and install our framework
4. Create a client application and specify the key in during app initialization (did Finish Launching With Options method)
5. From there on, certain standard events (see sections below) are captured automatically and sent to our backend along with the APP key. This is done transparently within our framework, which makes POST calls to a pre-defined endpoint on our tracking server
6. Our tracking server authenticates the APP key and if successful, passes the message on for forward processing
7. Once the event has been received in our backend, it is processed in near real-time and the developer can visit the data source analytics section to review the standard reports.

1.1 Batch based processing architecture

While the event processing is near real-time once an event reaches the Datagran backend, the dispatch of eventsfrom the developer app itself is implemented as a batch operation. In thisflow, events are batched in the developer app, rather than being sent outimmediately. The developer has an option to select the number of events to sendper batch and also how long to wait before processing the next batch. This architecture allows appdevelopers to fine tune the data collection environment based on theirindividual app needs and bandwidth constraints. These configuration options areprovided when initializing the Datagran tracker using one of the supportedsignatures. Please see sections below for further details.

2. Framework installation

The Framework installation process is a two-step method which involves

1. Registering a data source and generating an APP key from within the Datagran customer dashboard
2. Downloading the Framework, embedding it in the client app and then initializing it with the APP key

2.1 Register an IOS Data Source

For Step 1, go to the Integrations section from within your Datagran customer dashboard

Click on “Create Integration”

Scroll down and locate the Behavioural Analytics section and click on IOS

Next, give your data source a name and a descriptive text

Clicking on Next should take you to a screen where you can see your newly generated APP key

Use this key in Step 2 when initializing the Client application after downloading and embedding our framework. Click on Finalize to save your data source

2.2 Install the framework and initialize client application

1.  In order to use the framework, you will need the AP key generated in Step 1. This APP key must be specified in the app initialization section and passed to the main Track method as a parameter.

2. Once the key has been generated, download the framework and It can be integrated by below method,  
        
   A. Integrating the framework
·  Drag the framework to the framework folder in x code

·  Select the project file from the project navigator on the left side of the project window.
·  Select the target for where you want to add frameworks in the project settings editor.
·  Select the “Build Phases” tab, and click the small triangle next to “Link Binary With Libraries” to view all of the frameworks in your application.
·  To Add frameworks, click the “+”below the list of frameworks.o Select Tracker_iOS.framework from the list

3.  Once the setup has been completed, you can begin making code changes to your client application. The code below shows a sample call made inside the did Finish Launching With Options method of a App delegate class.

func application(_ application:UIApplication, didFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey: Any]?) -> Bool {    Tracker.shared.initialize
(sdk_api_key,showLog: true, addGeo: true, sendBatch: 20, waitForResponse: 30,workSpaceId: workSpaceId)}


In this snippet, we are initializing the Tracker and passing it the APP key along with a couple of other parameters. The Tracker class provides a versatile implementation allowing developers a number of configuration options as discussed in section below.  From now on, the framework automatically listens to standard IOS events (see list below) and transmits them to Datagran in a batch mode.

3. Standard Events

Once the tracker has been initialized, it will start collecting data automatically. The current version of Datagran IOS framework automatically tracks the following standard events

  • Event
  • onClick
  • onLongClick
  • onFocusChange
  • onOptions
    ItemSelected
  • onKeyPress
  • firstOpen
  • referrer
  • Trigger
  • An onscreen element is clicked
  • An onscreen element is long pressed
  • Focus changes from EditText
  • When an options menu is selected
  • When a key on keyboard is pressed
  • When a user opens the app at first time
  • It will be triggered when the user comes to a deep link from some ad after he has opened the app.

5. User Identification

In order to identify users with a known attribute such as an email, the framework provides a method called identify. This method accepts three parameters including

·  id (String)- A string containing the user identifier to be associated with the current deviceId
·  type (String)-The type of id. Datagran supports the following values for id_type- “email”, “phone”, “crm”,”other”. Trying to use any other value for id_type will result in an error being thrown back to the client application
·  controller-The current activity context
·  addGeo (Boolean)-This flag can be used to turn getting location data on/off

The flexibility provided by this method allows developers to associate their users with multiple ID types. For example, an app may allow users to login using their phone number rather than email. In this case, the type could be set to ‘phone’ with the id being the phone number itself. In another example, an app developer might want to use a deep link containing a unique code to identify the user. In this case, the type could be ‘other’ and the id the value of the code field itself. In the backend, each user record maintains a list of all id types ever used to identify the user against a given device Id. If more than one call is made for a given user against the same type, then we store the latest value of id against that type. For example,Suppose that the first time an identify call is issued, the developer passes type=email and id=abc@email.com. If another call is later issued with type=email and id = def@email.com, then the user record will show this instead of abc@email.com

4. Custom Events

The framework provides an ability for customers to be able to send custom events carrying arbitrary payload. For this, developers can use the APP method trackCustom which accepts the following parameters.

·  viewName– This is the name of the custom event
·  action– This is a JSON formatted arbitrary payload. For Customers using our raw data export feature, this payload will be available against the event name, along with the user device Id
·  controller-The application context provided by invoking method
·  addGeo- A Boolean flag which indicates whether to override the default location tracking functionality.

6.2 Event Specific Parameters

The data points below are specific to individual events and are present inside the payload node of the parent event (inside node event.payload)

  • Event name
  • onClick, onLongClick
  • onFocus
    Change
  • onKeyPress
  • onOptionsItem
    Selected
  • Payload parameters
  • ·  elementType – type of the UI element which triggered event (e.g. a button)

    ·  elementName – name of the UI element
  • elementName – contains the name of the element from which focus was changed
  • elementName – contains the value code of key pressed
  • elementName – Value of the selected menu item

6. Event Structure and Parameters

Each individual event, whether standard or custom, that is generated by the framework follows the same basic structure. There are some parameters that are common to all events while others are event specific. The tables below provide an overview of event structure.

6.1 COMMON PARAMETERS

  • appKey
  • version
  • latitude
  • longitude
  • deviceInfo
  • deviceInfo.
    currentDate
  • deviceInfo.
    deviceId
  • deviceInfo.
    deviceModel
  • deviceInfo.
    SystemVersion
  • deviceInfo.
    deviceName
  • event.type
  • event.name
  • event.time
  • event.payload
  • event.
    ActivityName
  • event.ViewName
  • os
  • Workspace_id
  • App specific APP key. Notice that if a developer has multiple apps (data sources in Datagran jargon), then each app will have its own key
  • Framework version
  • Latitude of the location where event was generated
  • Longitude of location where event was generated
  • A parent node containing all device specific information
  • Timestamp in Unix Epoch
  • IOS device Id (IOS, shared only  subject to user having granted permissions to the app)
  • Device Model
  • IOS OS Version running on device
  • Device name
  • This can be one of the following
    · onClick
    · onLongClick
    · onKeyPress
    · onFocusChange
    ·onOptionsItem
    Selected
    · customEvent
    · referrer
    · firstOpenNotice that the identify method actually generates a custom event with type = ‘ce’. The name of the event in this case is always ‘identify’
  • Descriptive name of the event
  • Event timestamp in Unix Epoch format
  • The actual event data. This is standardized in case of built-in events but can be completely arbitrary for custom events
  • Name of the Activity on which  the event was triggered
  • Specific view within the  activity
  • Track iPhone or iPad
  • Send workspace id