ANDROID ANALYTICS SDK - Quick Start Guide

Summary

This document describes how to integrate the Quixxi Analytics SDK into an Android application. The implementation of Quixxi Analytics will allow you to have custom Events and Diagnostics. Please check out our API Reference for more detailed information about this SDK.

Creating the Analytics SDK on Quixxi Portal

  1. If you don’t have yet created the container for your app in Quixxi Portal create one using the “Add New” button, otherwise go directly to point 3.
  2. In the “Create your app” dialog give a name to your application and click “Continue”
  3. Click on the newly created app,choose “Control” in the header tab and then “Package” in left side menu.
  4. Click “Add Platform” and choose Android as platform. Analytics framework in the "Select modules" section should already come preselected.
  5. Give the same package name you used for this app in Android Studio and click “Start Packaging”.
  6. Now Quixxi will pack Analytics framework and notify you once it gets completed.
  7. Click “Download Library” to get the file to integrate in your project. Details for this point will be fully covered in the next section. The package received contains three files: a) a “Readme.txt” file containing the instructions and the AppGUID b) the “QuixxiLibrary.aar” c)the Android Studio plugin “QuixxiPlugin.jar” for Linux-based operative systems. It will be needed only for Quixxi Injected Events [and Patch]

For first-time users

In order to show you since the beginning the potential of Quixxi Analytics we created a sample Demo App

  • click on the “Download Demo” tab to download this apk. After installing it you will see a menu button in the top left corner of the app featuring two tabs: “Quixxi Analytics” and “Quixxi TroubleShooting”. Tapping the “Mock Event” button will generate an “App Started” event that you can see selecting the “Events” entry in the left-side menu while clicking on the “Mock Error” one will raise a crash that will be reported in the “Diagnostics” section of the same menu
  • the same Demo App can be executed within the browser - without the need to install it on a real device - clicking on “Launch Demo App”

Steps to integrate Quixxi Analytics SDK into an Android app

After downloading the Analytics SDK for the app let’s see how to integrate it into the Android Studio project and have custom Events and Diagnostics as in the sample app
IMPORTANT - each app must integrate a specific “QuixxiLibrary.aar” file. Please don’t use the same aar file for different apps because in this case all the data posted from these apps would be sent to the same app container
  1. In Android Studio go to "File" -> "Project Structure..." -> click the "+" in the top left corner -> "Import .JAR/.AAR Package" -> "Next" -> select “QuixxiLibrary.aar” -> "Finish". Please double-check that this step was correctly performed controlling that the “settings.gradle” file of your app shows a line like the following or add it to fix this step:
  2. include ':app', ':QuixxiLibrary'
  3. After importing the QuixxiAnalytics SDK, click on "File" -> "Project Structure…" -> select "Dependencies" tab-> click the "+" in the top right corner -> "Module Dependency" -> select “:QuixxiLibrary”. Again, please double-check that this step too was correctly performed opening your ”build.gradle (Module: app)” file. You should already find [only] one of the following lines in the list of “dependencies”, else please add the one corresponding to your Gradle version:
  4. compile project(':QuixxiLibrary') // deprecated since gradle:3.0
    implementation project(':QuixxiLibrary')
  5. AThese are the permissions to be requested in your Android Manifest:
  6. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />

Initialising the Quixxi Analytics SDK

First of all add the following import to your project:
import com.quixxi.analytics.QuixxiAnalytics;
Now let's focus on the onCreate() method of your launcher activity. Debug Logs from Quixxi Analytics SDK can be optionally activated inserting the following line:
QuixxiAnalytics.isDebug = true;
Let’s initialise the Quixxi Analytics SDK by adding:
QuixxiAnalytics.start(getApplicationContext());
If you want to store the user position you can retrieve latitude and longitude coordinates on your own and then call:
QuixxiAnalytics.setLocation(String latitude, String longitude);
The location data provided with the preceding API will be displayed on the map in Quixxi portal. To access it click on your app container -> “Control” -> “Devices/Users” and scroll down till the end of the page  

Sending events

Once the Quixxi Analytics library is fully initialized you can push events to the Quixxi portal with one of the following methods:
QuixxiAnalytics.sendEvent(title, description);
QuixxiAnalytics.sendEvent(title, description, additionalDescription);
QuixxiAnalytics.sendEvent(title, description, additionalDescription, customMapObject);
where:
title - the title of the event
description - the description of the event
additionalDescription - an additional string describing the event
customMapObject- a custom map Object from Developer
 

Example


Map <String, Object> customMapObject = new HashMap <String, Object>();
customMapObject.put("sku_id", 123456);
customMapObject.put("sku_price", "$70.50");
customMapObject.put("sku_brand", "Nike");
customMapObject.put("sku_size", 10);
customMapObject.put("sku_model", "DownShifter Running Shoes");
QuixxiAnalytics.sendEvent("Purchase", "Running shoes", "Amazon", customMapObject);

Sending crash reports

Quixxi Analytics SDK integration will automatically file on the portal all the exceptions happening in your code. This will happen without adding any API to your code. Moreover you will be able to access the debugging files that will help you troubleshooting the issue – e.g. Stack Trace, Logcat, etc. - exactly as you would be able to do with your test device If you prefer to explicitly catch the exception and avoid your app to crash - while still preserving the possibility to collect the diagnostics files on the portal - then you can use this scheme and this explicit API:
try
{
// your code here
}
catch (Exception e)
{
QuixxiAnalytics.sendException(e, Thread.currentThread());
}

Sending and checking Shared Preferences

You can push the shared preferences stored by the app to Quixxi with the following method:
QuixxiAnalytics.sendSharedPreferences();
In oder to check them:
  1. Click on your app box -> “Control” -> “Devices/Users” -> choose the user -> go at the end of the line and click on “View Details”
  2. In the next screen scroll the page till the end and click on “Show Preferences” button
  3. Updating the user email

    Quixxi basic functionality is in general already able to automatically retrieve the user’s email. This API comes to cover the following scenarios:
    • you need to update the user email with a newer one
    • you may not want to retrieve the user email via Quixxi but with your own procedure
    • you want to change the user’s email ”unknownuser@unknown.com” which is the default value shown on Quixxi portal when the user denies the Contacts (android.permission.GET_ACCOUNTS) permission required by Quixxi Analytics [actually by Android] to perform this action. This is particularly true if your app doesn’t really need it to perform its tasks
    For all the preceding reasons we strongly recommend to directly ask your audience to provide the email, avoiding the request for an additional permission. It is not so hard as it seems. This already happens to all the new users which are subject to a registration in order to be able to receive login credentials. Or to all those ones that have to leave an email to be contacted for customer support purposes.
    Once you have the email you can update the user profile calling the following API:
    QuixxiAnalytics.sendUserEmail(String newProvidedEmail);

    Runtime Permissions

    If your app is targeting Android Marshmallow [targetSdkVersion: 23] or higher then you need to request some permissions at runtime. Quixxi Analytics needs Contacts (android.permission.GET_ACCOUNTS) permission. We recommend showing the user an explanation before presenting the permission prompt.

    Following is the sample of requesting CONTACTS permissions at runtime:
    1. Create a unique code for the permission in the Activity:
    2. private static final int REQUEST_CONTACT_PERMISSION = 100;
    3. Check for the permission if granted already or request for the permission
    4. @Override
      public void onRequestPermissionsResult(
      int requestCode,
      @NonNull String[] permissions,
      @NonNull int[] grantResults) {
      super.onRequestPermissionsResult(requestCode, permissions,grantResults);
      switch (requestCode) {
      case REQUEST_CONTACT_PERMISSION:
      if (permissions.length > 0 && permissions[0].equals(Manifest.permission.GET_ACCOUNTS)
      && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
      QuixxiAnalytics.isDebug = true;
      QuixxiAnaltyics.start(getApplicationContext());
      } else {
      // Show an explanation toast
      Toast.makeText(this, "The app needs contacts permissions to continue.", Toast.LENGTH_LONG).show();
      }
      break;
      }
      }
    If you are not familiar with "Runtime Permissions" then please refer to Android Development documentation or to EasyPermissions, a simplified wrapper library.

    Injected Events

    Injected Events allows developers to add Quixxi Events and Log events dynamically in their live applications. Injected Events come in-built with Quixxi Analytics SDK. We already included this SDK in the project at the beginning of this section and then we are good to go. Otherwise please refer to the related paragraph. Now let's see how to use them.
    1. We already saw that the Library previously downloaded from the portal contained an Android studio plugin “QuixxiPlugin.jar" and a "Readme.txt" file.
    2. Open Android Studio and select File ->Settings ->Plugins->Install plugin from disk...  and choose “QuixxiPlugin.jar”. After clicking on "OK" please restart Android Studio as suggested.
    3. Now you can see a Quixxi icon in the toolbar which means that the Quixxi plugin was successfully installed.
    4. Generate your APK by Build -> Build APK and click on Quixxi plugin in Toolbar.
    5. Copy and paste your AppGuid (as already said it is available in "Readme.txt" file or - more quickly - from the final part of the portal webaddress for the specific app), fill the Package name, app version, choose Product flavor (if any) and finally select build type (debug or release). Once done click "Upload".
    6. Quixxi plugin will extract the APK methods and push them to Quixxi Cloud

    Steps to push Injected Events:

    1. In the Quixxi portal choose "Control" in the header tab and select  "Injected Events" in the left side menu.
    2. Click "Add New" button and choose your target app version.Now select either "Debug Log" for log event or "Quixxi Event" for pushing a Quixxi Event from your live application.
    3. If you want to inject a Quixxi Event in any of your application's method then choose "Quixxi Event" in "Type" dropdown and provide appropriate "Event title" and "Event Description".
    4. Provide a unique name for the event in "Name" and choose your exact audience based on filtering "OS Version","Country","Brand","Model".
    5. Also, you have options for injecting event on start or end of your target method and for this option check either "Start of method" or "Before end of method".
    6. Check "Extend to further version" option if you want to inject events in further released app versions.
    7. Choose "Sandbox" to test inject events in debug mode or "Production" to inject events in the live application.
    8. Now click "Generate" button to generate a Injected Event for your application's method and click "Submit" to push it to your application.
    9. You can see the history of injected events in Injected Events list.

ANDROID ANALYTICS SDK - Quick Start Guide

Summary

This document describes how to integrate the Quixxi Analytics SDK into an Android application. The implementation of Quixxi Analytics will allow you to have custom Events and Diagnostics. Please check out our API Reference for more detailed information about this SDK.

Creating the Analytics SDK on Quixxi Portal

  1. If you don’t have yet created the container for your app in Quixxi Portal create one using the “Add New” button, otherwise go directly to point 3.
  2. In the “Create your app” dialog give a name to your application and click “Continue”
  3. Click on the newly created app,choose “Control” in the header tab and then “Package” in left side menu.
  4. Click “Add Platform” and choose Android as platform. Analytics framework in the "Select modules" section should already come preselected.
  5. Give the same package name you used for this app in Android Studio and click “Start Packaging”.
  6. Now Quixxi will pack Analytics framework and notify you once it gets completed.
  7. Click “Download Library” to get the file to integrate in your project. Details for this point will be fully covered in the next section. The package received contains three files: a) a “Readme.txt” file containing the instructions and the AppGUID b) the “QuixxiLibrary.aar” c)the Android Studio plugin “QuixxiPlugin.jar” for Linux-based operative systems. It will be needed only for Quixxi Injected Events [and Patch]

For first-time users

In order to show you since the beginning the potential of Quixxi Analytics we created a sample Demo App

  • click on the “Download Demo” tab to download this apk. After installing it you will see a menu button in the top left corner of the app featuring two tabs: “Quixxi Analytics” and “Quixxi TroubleShooting”. Tapping the “Mock Event” button will generate an “App Started” event that you can see selecting the “Events” entry in the left-side menu while clicking on the “Mock Error” one will raise a crash that will be reported in the “Diagnostics” section of the same menu
  • the same Demo App can be executed within the browser - without the need to install it on a real device - clicking on “Launch Demo App”

Steps to integrate Quixxi Analytics SDK into an Android app

After downloading the Analytics SDK for the app let’s see how to integrate it into the Android Studio project and have custom Events and Diagnostics as in the sample app
IMPORTANT - each app must integrate a specific “QuixxiLibrary.aar” file. Please don’t use the same aar file for different apps because in this case all the data posted from these apps would be sent to the same app container
  1. In Android Studio go to "File" -> "Project Structure..." -> click the "+" in the top left corner -> "Import .JAR/.AAR Package" -> "Next" -> select “QuixxiLibrary.aar” -> "Finish". Please double-check that this step was correctly performed controlling that the “settings.gradle” file of your app shows a line like the following or add it to fix this step:
  2. include ':app', ':QuixxiLibrary'
  3. After importing the QuixxiAnalytics SDK, click on "File" -> "Project Structure…" -> select "Dependencies" tab-> click the "+" in the top right corner -> "Module Dependency" -> select “:QuixxiLibrary”. Again, please double-check that this step too was correctly performed opening your ”build.gradle (Module: app)” file. You should already find [only] one of the following lines in the list of “dependencies”, else please add the one corresponding to your Gradle version:
  4. compile project(':QuixxiLibrary') // deprecated since gradle:3.0
    implementation project(':QuixxiLibrary')
  5. AThese are the permissions to be requested in your Android Manifest:
  6. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />

Initialising the Quixxi Analytics SDK

First of all add the following import to your project:

import com.quixxi.analytics.QuixxiAnalytics;
Now let's focus on the onCreate() method of your launcher activity. Debug Logs from Quixxi Analytics SDK can be optionally activated inserting the following line:

QuixxiAnalytics.isDebug = true;
Let’s initialise the Quixxi Analytics SDK by adding:

QuixxiAnalytics.start(getApplicationContext());
If you want to store the user position you can retrieve latitude and longitude coordinates on your own and then call:

QuixxiAnalytics.setLocation(String latitude, String longitude);
The location data provided with the preceding API will be displayed on the map in Quixxi portal. To access it click on your app container -> “Control” -> “Devices/Users” and scroll down till the end of the page  

Sending events

Once the Quixxi Analytics library is fully initialized you can push events to the Quixxi portal with one of the following methods:
QuixxiAnalytics.sendEvent(title, description);
QuixxiAnalytics.sendEvent(title, description, additionalDescription);
QuixxiAnalytics.sendEvent(title, description, additionalDescription, customMapObject);
where:
title - the title of the event
description - the description of the event
additionalDescription - an additional string describing the event
customMapObject- a custom map Object from Developer
 

Example


Map <String, Object> customMapObject = new HashMap <String, Object>();
customMapObject.put("sku_id", 123456);
customMapObject.put("sku_price", "$70.50");
customMapObject.put("sku_brand", "Nike");
customMapObject.put("sku_size", 10);
customMapObject.put("sku_model", "DownShifter Running Shoes");
QuixxiAnalytics.sendEvent("Purchase", "Running shoes", "Amazon", customMapObject);

Sending crash reports

Quixxi Analytics SDK integration will automatically file on the portal all the exceptions happening in your code. This will happen without adding any API to your code. Moreover you will be able to access the debugging files that will help you troubleshooting the issue – e.g. Stack Trace, Logcat, etc. - exactly as you would be able to do with your test device If you prefer to explicitly catch the exception and avoid your app to crash - while still preserving the possibility to collect the diagnostics files on the portal - then you can use this scheme and this explicit API:
try
{
// your code here
}
catch (Exception e)
{
QuixxiAnalytics.sendException(e, Thread.currentThread());
}

Sending and checking Shared Preferences

You can push the shared preferences stored by the app to Quixxi with the following method:

QuixxiAnalytics.sendSharedPreferences();
In oder to check them:
  1. Click on your app box -> “Control” -> “Devices/Users” -> choose the user -> go at the end of the line and click on “View Details”
  2. In the next screen scroll the page till the end and click on “Show Preferences” button
  3. Updating the user email

    Quixxi basic functionality is in general already able to automatically retrieve the user’s email. This API comes to cover the following scenarios:
    • you need to update the user email with a newer one
    • you may not want to retrieve the user email via Quixxi but with your own procedure
    • you want to change the user’s email ”unknownuser@unknown.com” which is the default value shown on Quixxi portal when the user denies the Contacts (android.permission.GET_ACCOUNTS) permission required by Quixxi Analytics [actually by Android] to perform this action. This is particularly true if your app doesn’t really need it to perform its tasks
    For all the preceding reasons we strongly recommend to directly ask your audience to provide the email, avoiding the request for an additional permission. It is not so hard as it seems. This already happens to all the new users which are subject to a registration in order to be able to receive login credentials. Or to all those ones that have to leave an email to be contacted for customer support purposes.
    Once you have the email you can update the user profile calling the following API:
    
    QuixxiAnalytics.sendUserEmail(String newProvidedEmail);
    

    Runtime Permissions

    If your app is targeting Android Marshmallow [targetSdkVersion: 23] or higher then you need to request some permissions at runtime. Quixxi Analytics needs Contacts (android.permission.GET_ACCOUNTS) permission. We recommend showing the user an explanation before presenting the permission prompt.

    Following is the sample of requesting CONTACTS permissions at runtime:
    1. Create a unique code for the permission in the Activity:
    2. 
      private static final int REQUEST_CONTACT_PERMISSION = 100;
      
    3. Check for the permission if granted already or request for the permission
    4. @Override
      public void onRequestPermissionsResult(
      int requestCode,
      @NonNull String[] permissions,
      @NonNull int[] grantResults) {
      super.onRequestPermissionsResult(requestCode, permissions,grantResults);
      switch (requestCode) {
      case REQUEST_CONTACT_PERMISSION:
      if (permissions.length > 0 && permissions[0].equals(Manifest.permission.GET_ACCOUNTS)
      && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
      QuixxiAnalytics.isDebug = true;
      QuixxiAnaltyics.start(getApplicationContext());
      } else {
      // Show an explanation toast
      Toast.makeText(this, "The app needs contacts permissions to continue.", Toast.LENGTH_LONG).show();
      }
      break;
      }
      }
    If you are not familiar with "Runtime Permissions" then please refer to Android Development documentation or to EasyPermissions, a simplified wrapper library.

    Injected Events

    Injected Events allows developers to add Quixxi Events and Log events dynamically in their live applications. Injected Events come in-built with Quixxi Analytics SDK. We already included this SDK in the project at the beginning of this section and then we are good to go. Otherwise please refer to the related paragraph. Now let's see how to use them.
    1. We already saw that the Library previously downloaded from the portal contained an Android studio plugin “QuixxiPlugin.jar" and a "Readme.txt" file.
    2. Open Android Studio and select File ->Settings ->Plugins->Install plugin from disk...  and choose “QuixxiPlugin.jar”. After clicking on "OK" please restart Android Studio as suggested.
    3. Now you can see a Quixxi icon in the toolbar which means that the Quixxi plugin was successfully installed.
    4. Generate your APK by Build -> Build APK and click on Quixxi plugin in Toolbar.
    5. Copy and paste your AppGuid (as already said it is available in "Readme.txt" file or - more quickly - from the final part of the portal webaddress for the specific app), fill the Package name, app version, choose Product flavor (if any) and finally select build type (debug or release). Once done click "Upload".
    6. Quixxi plugin will extract the APK methods and push them to Quixxi Cloud

    Steps to push Injected Events:

    1. In the Quixxi portal choose "Control" in the header tab and select  "Injected Events" in the left side menu.
    2. Click "Add New" button and choose your target app version.Now select either "Debug Log" for log event or "Quixxi Event" for pushing a Quixxi Event from your live application.
    3. If you want to inject a Quixxi Event in any of your application's method then choose "Quixxi Event" in "Type" dropdown and provide appropriate "Event title" and "Event Description".
    4. Provide a unique name for the event in "Name" and choose your exact audience based on filtering "OS Version","Country","Brand","Model".
    5. Also, you have options for injecting event on start or end of your target method and for this option check either "Start of method" or "Before end of method".
    6. Check "Extend to further version" option if you want to inject events in further released app versions.
    7. Choose "Sandbox" to test inject events in debug mode or "Production" to inject events in the live application.
    8. Now click "Generate" button to generate a Injected Event for your application's method and click "Submit" to push it to your application.
    9. You can see the history of injected events in Injected Events list.