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.
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.
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, didFinishLaunching
WithOptions 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.
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
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
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)
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
Need help? Send us a message. If you have suggestions, please send them our way
For any request related to your personal information, please contact us here: legal@datagran.io. 44 Montgomery St. 3rd Floor, San Francisco CA 94104