DATAGRAN

ANDROID SDK

For mobile app developers, looking to track application usage.

Introduction

For mobile app developers, looking to track their application usage, Datagran provides an Android SDK. When embedded, this SDK automatically collects data about a number of standard Android events and sends them to Datagran servers. Additionally, the SDK exposes key API 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 SDK to collect arbitrary interaction data.

App Architecture and Workflow

The Datagran Android SDK is written in JAVA and internally uses Google BigQuery to log and process all user interaction data. All data collected by an app using our SDK 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 Android 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 Android data source in the Datagran dashboard (app.datagran.io)

2. Developer is issued an API key (separate key for each Android data source)

3. Download and install our SDK

4. Create a client application and specify the key in during app initialization (onCreate
method)

5. From there on, certain standard events (see sections below) are captured
automatically and sent to our backend along with the API key. This is done
transparently within our SDK, which makes POST calls to a pre-defined endpoint on
our tracking server

6. Our tracking server authenticates the API 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

Batch based processing architecture


While the event processing is near real-time once an event reaches the Datagran backend, the dispatch of events from the developer app itself is implemented as a batch operation. In this flow, events are batched in the developer app, rather than being sent out immediately. The developer has an option to select the number of events to send per batch and also how long to wait before processing the next batch. This architecture allows app developers to fine tune the data collection environment based on their individual app needs and bandwidth constraints. These configuration options are provided when initializing the Datagran tracker using one of the supported signatures. Please see sections below for further details.

SDK installation

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


1. Registering a data source and generating an API key from within the Datagran
customer dashboard


2. Downloading the SDK, embedding it in the client app and then initializing it with the
API key

3.1 Register an Android Data Source

Connect a Data Source or head over to the Integrations section.

Scroll down and locate Android SDK to begin integration.


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 API key.

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

3.2 Install the SDK and initialize client application
  1. In order to use the SDK, you will need the API key generated in Step 1. This API 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 SDK and It can be integrated in either of below two methods such as, 
  • Integrating the SDK directly from the android studio 
  • Go to file -> new module then select Import .JAR/.AAR package then click “Next”

  • Include the file path and name of the SDK in the respective fields then click finish.

  • Include the implementation(path:'sdk' ) in app level gradle file
  • Include the “include ‘:sdk’”  in settings.gradle
  • Creating a libs directory and integrate SDK.
  • Create “libs” folder under src -> main

    

  • Paste the sdk.aar file in the libs directory which has been created in previous steps.
  • Include the implementation(name:'sdk',ext:'aar') in app level gradle file
  • Include the following code in project level gradle file inside the repositories in “allprojects”:

flatDir {

dirs 'src/main/libs' 

}

  1. After Completing any one of the above methods, Include the following code in the Gradle file.
  • Include the following code in app level gradle file:
  • implementation 'com.google.code.gson:gson:2.8.6'
  • implementation 'com.squareup.okhttp3:okhttp:4.3.1'
  • implementation 'com.google.android.gms:play-services-location:17.0.0'
  • Add the following permission in Manifest file
  • <uses-permission android:name="android.permission.INTERNET"/>
  1. 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 onCreate() method of a MainActivity class

………….

@Override

protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

setContentView(R.layout.activity_main);

Toolbar toolbar = findViewById(R.id.toolbar);

setSupportActionBar(toolbar);


apiKey = "33e2c368-7dfd-4c29-9861-02942ae1ff13";

Tracker.init(this, true, apiKey);

……………….

In this snippet, we are initializing the Tracker and passing it the API 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 SDK automatically listens to standard Android events (see list below) and transmits them to Datagran in a batch mode.

Standard Events

4. Standard Events

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

Custom Events

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

  • eventName – This is the name of the custom event
  • payload – 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
  • context-The application context provided by invoking method
  • addGeo- A Boolean flag which indicates whether to override the default location tracking functionality. 

User Identification

In order to identify users with a known attribute such as an email, the SDK 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
  • id_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
  • context-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 id_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 id_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 id_type, then we store the latest value of id against that id_type. For example,

Suppose that the first time an identify call is issued, the developer passes id_type=email and id=abc@email.com. If another call is later issued with id_type=email and id = def@email.com, then the user record will show this instead of abc@email.com.

Event Structure and Parameters

Each individual event, whether standard or custom, that is generated by the SDK 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. (See Common Parameters table below)

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). (See Event Specific Parameters table below)


Common Parameters

appKey
App specific API key. Notice that if a developer has multiple apps (data sources in Datagran jargon), then each app will have its own key
deviceInfo
A parent node containing all device specific information
deviceInfo.currentDate
Timestap in Unix Epoch
deviceInfo.deviceId
Android device Id (Android ID, shared only subject to user having granted permissions to the app)
deviceInfo.deviceModel
Device Model
deviceInfo.SystemVersion
Android OD Version running on device
deviceInfo.deviceName
Device brand (e.g. Xiaomi)
event.type
This can be one of the following
onClick
onLongClick
onKeyPress
onFocusChange
onOptionsItemSelected
customEvent
referrer
firstOpen
Notice that the identify method actually generates a custom event with type = ‘ce’. The name of the event in this case is always ‘identify’
event.name
Descriptive name of the event
event.time
Event timestamp in Unix Epoch format
event.payload
The actual event data. This is standardized in case of built-in events but can be completely arbitrary for custom events
event.latitude
Latitude of the location where event was generated
event.longitude
Longitude of location where event was generated

Event Specific Parameters

Event name
Payload parameters
onClick, onLongClick, onKeyPress
- elementType – type of the UI element which triggered event (e.g. a button)
- elementName – name of the UI element
onFocusChange
- elementName – contains the name of the element from which focus was changed
onKeyPress
- elementName – contains the value code of key pressed
onOptionsItemSelected
- elementName – Value of the selected menu item
Made with LOVE in San Francisco

For any request related to your personal information, please contact us here: legal@datagran.io

156 2nd St, San Francisco, CA 94105