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:
- Get quick time to value
- Measure the onboarding duration and success rate for onboarding
- Capture data on Attributes such as router type, ISP, phone OS / model. Ability to add Custom Attributes (eg: App Version)
- Aggregate views of all the apps in the fleet showing the sensitivity of onboarding issues with various Attributes
- Ability to drill down from aggregate view to a single onboarding instance to find issues related to Wi-Fi onboarding
- 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
- Location;
- Local Network(iOS 14).
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.
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 |
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.
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. |
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
- 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)
- 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.
- 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);
- 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.