ANDROID ANALYTICS SDK – Quick Start Guide

Summary

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]

Steps to integrate Quixxi Analytics SDK into an Android app

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:

include ':app', ':QuixxiLibrary'

2. 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:

compile project(':QuixxiLibrary') // deprecated since gradle:3.0
implementation project(':QuixxiLibrary')

3. AThese are the permissions to be requested in your Android Manifest:

<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

import com.quixxi.analytics.QuixxiAnalytics;

QuixxiAnalytics.isDebug = true;

QuixxiAnalytics.start(getApplicationContext());

QuixxiAnalytics.setLocation(String latitude, String longitude);

Sending events

QuixxiAnalytics.sendEvent(title, description);

QuixxiAnalytics.sendEvent(title, description, additionalDescription); 

QuixxiAnalytics.sendEvent(title, description, additionalDescription, customMapObject);

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

try

{

// your code here

}

catch (Exception e)

{

QuixxiAnalytics.sendException(e, Thread.currentThread());

}

Sending and checking Shared Preferences

QuixxiAnalytics.sendSharedPreferences();

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

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:

private static final int REQUEST_CONTACT_PERMISSION = 100;

2. Check for the permission if granted already or request for the permission

@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.