Articles in this section

Mobile App Intelligence User Guide

Avatar
Shantanu Bhalerao
  • Updated
Follow

 

Mobile Application Intelligence (MAI) User Guide

Draft: June 1, 2020

1. Introduction:

Mobile App Intelligence (MAI) product consists of two parts: a. Mobile App SDK that is installed in connected product mobile apps, and b. Cirrent console that displays the analytics data collected from the app. By including Mobile App SDK in their apps, customers get access to dashboards and analytics in the Cirrent Console.

MAI helps product companies understand the Wi-Fi onboarding experience for their users and the problems app users are facing in the field. Connected product companies can use this data to understand onboarding issues with their apps, fix these issues and measure the impact. By iterating through this process, connected product companies can improve Wi-Fi onboarding success rate for their products, reduce customer call volumes and improve app ratings.

 

2. Benefits of using MAI:

The Analytics in Cirrent Console enable connected product companies to:

  1. Get quick time to value
  2. Measure the onboarding duration and success rate for onboarding
  3. Capture data on Attributes such as router type, ISP, phone OS / model. Ability to add Custom Attributes (eg: App Version)
  4. Aggregate views of all the apps in the fleet showing the sensitivity of onboarding issues with various Attributes
  5. Ability to drill down from aggregate view to a single onboarding instance to find issues related to Wi-Fi onboarding
  6. Solve issues reported through Customer Support calls

 

3. Terms:

AppID: Each app instance has unique AppID that is provided by customer

OnboardingID: Each onboarding attempt is assigned unique OnboardingID by Cirrent SDK

DeviceID: unique ID for each connected product

 

4. Sample App and SDK repos

App repos :

Android https://github.com/Cirrent/ZipKey-Android-App

iOS https://github.com/Cirrent/ZipKey-iOS-App

 

SDK(binaries) repos:

Android https://github.com/Cirrent/ZipKey-Android-SDK

iOS https://github.com/Cirrent/ZipKey-iOS-SDK

 

5. App permissions

You will need to ask the user for the following App permissions for Cirrent SDK to be able to collect the data needed for Mobile App Intelligence:
 
iOS:
  1. Location;
  2. Local Network(iOS 14).
Android:
         Location
 
 

6. Using Cirrent MAI within your app

6a. Create Analytics JWT

The connected product  mobile app will use a JSON web token (JWT) to confirm its scope of control when it calls the Cirrent cloud.  The App API Key and Secret are generated using Cirrent Console using link https://console.cirrent.com/api-keys. Please click “Create API Key” button and choose key type as “app” as shown below.

 

 

Using the App API Key and Secret, you will need to generate Analytics token.

 

Please use one of these options to generate analytics JWT token:

1. Generate the token using your cloud and sign with App API Secret.

OR

2. Generate the analytics JWT token using the SDK.

 

Function

Description

createToken(int expiresIn,

                     String accountId,

                     String appId,

                     String appKey,

                     String appSecret)

@param expiresIn Token lifetime in seconds.

@param accountId Account Id.

@param appId App Id.

@param appKey App API key.

@param appSecret App API secret.

 

@return The output of this method will be “{appKey}::{JwtToken}”.

 

 

6b. Add SDK Functions to the app

It is useful to look at the SDK functions as two separate categories:

 

I. Init Function

It is possible to get started within minutes by using only the Init Function.  Using just the Init function provides a way to get quick time to value from Cirrent Mobile SDK. Note that any communication between the app and Cirrent cloud needs an analytics JWT token.

Android:

Function

Description

init(Context appContext,

      String analyticsToken,

      MAICallback callback)

 

Starts the SDK

Captures and sends the phone information (phone model, OS), and the Wi-Fi information used to identify router, ISP, SSID for the network, etc

 

@param appContext     Application Context

@param analyticsToken Analytics token.

@param callback       MAICallback

 

iOS:

Function

Description

initialize(analyticsToken: String,

              delegate: MAICallback)

 

 

Starts the SDK

Captures and sends the phone information (phone model, OS), and the Wi-Fi information used to identify router, ISP, SSID for the network, etc

 

@param analyticsToken Analytics token.

@param delegate       MAICallback

 

Information about MAICallback:

Init and onboarding related functions have a MAICallback parameter.

MAI Callback is an interface which you can implement once(e.g in your base class) and just reuse. It has the following methods:

Function

Description

onTokenInvalid(Retrier retrier)

This function is called when token is invalid.

 

@param retrier Allows you to pass a new token and resend collected data using Retrier.retry(String token).

In case of Retrier.retry(String) failure MAICallback.onFailed(OnboardingAnalyticsError) will be called.

onFailed(OnboardingAnalyticsError e)

 

Will be called when:

- Retrier.retry(String) is failed to resend data using a new token;

- the conditions for calling the method are not met (e.g. attempt to call enterStep(String, Context, MAICallback) before startOnboarding(Context, int, MAICallback) etc.);

- data hasn't been sent due to some issues on the cloud side.

 

@param e An object that contains information about failure causes.

 

 II. Onboarding related functions

These functions help capture data related to particular onboarding. A single try of one app instance onboarding one Wi-Fi connected device is considered to be a unique OnboardingID. It is essential to use start_onboarding and end_onboarding functions to identify the start and end of a unique OnboardingID.  

The SDK gives the app developers flexibility to decide on which steps in the app to collect data. App developers can also annotate moving from one step to the next with reason codes.

Android:

Function

Description

startOnboarding(Context appContext,

                           MAICallback callback)

 

Required method that tells the cloud that onboarding has been started. Also creates a unique onboarding id and stores it for subsequent calls.

 

@param appContext Application Context.

@param callback   MAICallback

startOnboarding(Context appContext,

                           int onboardingSessionTimeout,

                           MAICallback callback)

Same as the function above, but in this case it has an additional “onboardingSessionTimeout” parameter.

 

@param appContext    Application Context.

@param onboardingSessionTimeout (in seconds)  if the time gap between onboarding steps > this value then onboarding duration timers will be paused till the next step is performed.

By default this value = 15 minutes.

@param callback   MAICallback

enterStep(String thisStepName,

                 Context appContext,

                 MAICallback callback)

Sends to the cloud information about previous(if it occurred) and current step.

 

@param thisStepName  Current step name.

@param appContext    Application Context.

@param callback      MAICallback

enterStep(String thisStepName,

                 String reason,

                 Context appContext,

                 MAICallback callback)

 

Sends to the cloud information about previous(if it occurred), current step.

 and the reason for why user moved from previous step to current step.

 

@param thisStepName Current step name.

@param reason Will be added to the previous step name(e.g. “{previousStepName}_{reason}”).

@param appContext Application Context.

@param callback  MAICallback

endOnboarding(Context appContext,

                          MAICallback callback)

 

Close out the onboarding id. Tells the cloud that onboarding has been ended.

 

@param appContext Application Context.

@param callback   MAICallback

endOnboarding(String reason,

                          Context appContext,

                          MAICallback callback)

 

Same as the function above, but in this case it has an additional “reason” parameter. Can be used to report a "reason" of an unsuccessful on-boarding.

Also you can call this method to "end" a failed onboarding without setting an onboarding type.

In this case MAICallback.onFailed(OnboardingAnalyticsError) will not be called.

 

@param reason Will be added to the previous step name(e.g. “{previousStepName}_{reason}”).

@param appContext Application Context.

@param callback MAICallback

setOnboardingDeviceInfo(String deviceId,

                                          Context appContext,

                                          MAICallback  callback)

 

Optional method that allows you to send a Device ID to the cloud.

 

@param deviceId  Currently on-boarding Device ID.

@param appContext   Application Context.

@param callback     MAICallback

setOnboardingDeviceInfo(String deviceId,

                                          Map<String, String> additionalAttributes,

                                          Context appContext,

                                          MAICallback callback)

Same as the function above, but it also allows to add  additional device attributes that will be sent along with the Device ID.

 

@param deviceId  Currently on-boarding Device ID.

@param additionalAttributes Additional attributes.

@param appContext   Application Context.

@param callback     MAICallback

setOnboardingType(OnboardingType type,

                                 Context appContext,

                                 MAICallback callback)

 

Required method that allows you to set an onboarding type.

Onboarding type should be set until endOnboarding(Context, MAICallback) is called. Types are SoftAP, BLE, ZipKey.

 

@param type       OnboardingType

@param appContext    Application Context.

@param callback    MAICallback

setOnboardingType(String customType,

                                 Context appContext,

                                 MAICallback callback)

 

Same as the function above, but in this case you can define a custom type.

For example, if you are using variants of SoftAP, you can compare performance between these variants using custom type.

 

@param customType    Custom on-boarding type.

@param appContext    Application Context.

@param callback    MAICallback

cancel()

Cancels all tasks.

removeAllCollectedData(Context appContext)

Removes all cached collected data.

 

iOS:

Function

Description

startOnboarding(onboardingSessionTimeout: Int? = nil,

                           delegate: MAICallback)

 

Creates a unique OnboardingID and records the onboarding id and start time. Sends an event to the cloud.

 

@param  onboardingSessionTimeout (optional) (in seconds)  if the time gap between onboarding steps > this value then onboarding duration timers will be paused till the next step is performed.

By default this value = 15 minutes.

@param delegate   MAICallback

enterStep(thisStepName: String,

                 reason: String? = nil,

                 delegate: MAICallback)

 

Sends to the cloud information about previous(if it occurred), current step and the reason for why user moved from previous step to current step.

 

@param thisStepName  Current step name.

@param reason (optional)  Will be added to the previous step name(e.g. “{previousStepName}_{reason}”).

@param delegate      MAICallback

endOnboarding(reason: String? = nil,

                          delegate: MAICallback)

 

 

Close out the onboarding id. Tells the cloud that onboarding has been ended.

Can be used to report a "reason" of an unsuccessful on-boarding.

Also you can call this method to "end" a failed onboarding without setting an onboarding type.

In this case MAICallback.onFailed(OnboardingAnalyticsError) will not be called.

 

@param reason (optional) Will be added to the previous step name(e.g. “{previousStepName}_{reason}”).

@param delegate   MAICallback

setOnboardingDeviceInfo(deviceId: String,

                                         additionalAttributes: [String: String]? = nil,

                                         delegate: MAICallback)

 

 

Optional method that allows you to send a Device ID to the cloud.  It also allows to add  additional device attributes that will be sent along with the Device ID.

 

@param deviceId  Currently on-boarding Device ID.

@param additionalAttributes (optional) Additional attributes.

@param delegate     MAICallback

setOnboardingType(type: OnboardingType,

                                 delegate: MAICallback)

 

 

Required method that allows you to set an onboarding type.

Onboarding type should be set until endOnboarding(Context, MAICallback) is called.

Types are SoftAP, BLE, ZipKey.

 

@param type       OnboardingType

@param delegate    MAICallback

setOnboardingType(customType: String,

                                    delegate: MAICallback)

 

 

Same as the function above, but in this case you can define a custom type.

For example, if you are using variants of SoftAP, you can compare performance between these variants using custom type.

 

@param customType Custom on-boarding type.

@param delegate    MAICallback

removeAllCollectedData()

Removes all cached collected data.

cancelAllTasks()

Cancels all tasks.

 

7. Examples

  1. Single line of code to collect Phone and Wi-Fi Environment details

To get only environmental details such as Phone OS / model, app version and Wi-Fi environment details such as router, ISP, etc, you need to use only one function call

 

Android:

OnboardingAnalytics.init(applicationContext, analyticsToken, callback);

 

iOS:

OnboardingAnalytics.initialize(analyticsToken: token, delegate: callback)
  1. Getting success rates and onboarding durations

This example allows the app developers to understand how many onboarding attempts succeeded and what is the duration that a user spent to onboard a device to Wi-Fi. This allows developers to also see what was the last step that the user was on before abandoning in case of unsuccessful onboarding attempts.  

Java based example:

OnboardingAnalytics.init(applicationContext, analyticsToken, callback);

…

OnboardingAnalytics.startOnboarding(applicationContext, callback);

OnboardingAnalytics.setOnboardingType(OnboardingType.SOFTAP, applicationContext, callback);

…

OnboardingAnalytics.endOnboarding("SoftAP_web_Server_timeout_error", applicationContext, callback);

 

However, this example will not give details on what is the order of steps that the user takes before the end of onboarding.

  1. Understand which steps cause users to abandon onboarding and why

You will need to annotate the various onboarding steps with step names to understand where users abandon the process. Consider SoftAP onboarding process shown below where the user goes through a series of steps such as scanning for a device, connecting to SoftAP SSID, and then going to the step where the user enters private Wi-Fi network credentials. At this step, let’s say the user spent too much time entering his Wi-Fi password and gets a timeout error from the SoftAP connected device. As Cirrent SDK captures all steps and their duration all this information allows developers to understand the root cause of the issue. A similar approach can be used for onboarding steps for BLE.

 

Java based example:

OnboardingAnalytics.init(applicationContext, analyticsToken, callback);
…
OnboardingAnalytics.startOnboarding(applicationContext, callback);
OnboardingAnalytics.setOnboardingType(OnboardingType.SOFTAP, applicationContext, callback);
OnboardingAnalytics.enterStep("scanning_for_device", applicationContext, callback);
OnboardingAnalytics.enterStep("connecting_to_device", applicationContext, callback);
OnboardingAnalytics.enterStep("joined_soft_ap_ssid", applicationContext, callback);
…
OnboardingAnalytics.enterStep("enter_private_creds", applicationContext, callback);
… {stepDuration > maxDuration}
OnboardingAnalytics.endOnboarding("SoftAP_web_Server_timeout_error", applicationContext, callback);
  1. Adding App Version using Custom Attributes

 

Custom attributes enable an app developer to add specific pieces of data that might be relevant to understanding the onboarding performance. A typical example is App Version.

Java based example:

 

OnboardingAnalytics.setOnboardingDeviceInfo(
                                deviceId,
                                getAppVersion(),
                                applicationContext,
                                callback
                        );
Map<String, String> getAppVersion() {
        final Map<String, String> appVersion = new HashMap<>();
        appVersion.put("app_version", BuildConfig.VERSION_NAME);
        return appVersion;
    }

 

 

 

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk