Getting Started with Android SDK 1.1.x

Method References

http://public.innomdc.com/android-library/method-references-1.1/

Requirements

  • Android 2.2 (API 8) and above
  • Permissions in the AndroidManifest.xml 

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Include library

You can do it in two ways:

  1. Download it directly from a link (add jar in Eclipse, Intellij Idea/AndroidStudio). This build contains all required libraries:
    1. Innometrics library
    2. com.google.code.gson 2.2.4
  2. Include maven dependencies into pom.xml:

    ...
    <repositories>
    	<repository>
    		...
    		<id>innometrics</id>
    		<url>http://nexus.innomdc.com/nexus/content/groups/public/</url>
    	</repository>
    	...
    </repositories>
    ...
    <dependencies>
    	...
    	<dependency>
    		<groupId>com.innometrics.android</groupId>
    		<artifactId>Innometrics</artifactId>
    		<version>1.1.1</version>
    	</dependency>
    	...
    </dependencies>

Configure parameters

Static config

Create config file innometrics.xml and place it in res/value folder.

Values for config you can find in the GUI: Install "Android Data Collection" app, create first section (name of your android app), go to Settings tab.

<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="innometrics_company_id">1</string>
<string name="innometrics_app_key">appkey</string>
<string name="innometrics_bucket">bucketname</string>
<string name="innometrics_section">sectionname</string>
<bool name="innometrics_debug">false</bool>
<string name="innometrics_cached_request_limit">300</string>
</resources>

"innometrics_cached_request_limit" - is not mandatory, but it's important setting that specifies the maximum number of requests that will be stored in internal cache and controls RAM occupied by the library.

Run-time config

In case you want to separate tracked data to different section, for example based on user's country set in app settings, you can init library with dynamic config (only once during initialization), see reference for available methods.

Create instance of library

In code, before using InnometricsAPI you need to get instance of InnometricsAPI class. It could be done in few ways:

Method returns instance of the class:

InnometricsAPI innometricsAPI = InnometricsAPI.getInstance(context);
Method sets "userProfileID" (by default profileId is hashed ANDROID_ID) as current userprofile ID and returns instance of InnometricsAPI:
InnometricsAPI innometricsAPI = InnometricsAPI.getInstance(context,"userProfileID");
 
//Equal to
InnometricsAPI innometricsAPI = InnometricsAPI.getInstance(context);
innometricsAPI.setCanonicalProfileId(userProfileID)

Example of usage:

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
innometricsAPI = InnometricsAPI.getInstance(this);
}}

Send data to profile

Track user events 

Call trackEvent(). It takes two arguments: eventDefinition - string codename of the event, event - hash containing parameters of this event. For instance to collect data about searches done by user you can use this code: 

btnSearch.setOnClickListener(new View.OnClickListener() {
	@Override
	public void onClick(View view) {
		HashMap<String, Object> event = new HashMap<String, Object>();
		event.put("search type", searchType.isChecked() ? "advanced" : "Normal");
		event.put("search string", searchString.getText().toString());
		innometricsAPI.trackEvent("eventSearch", event);
	}
});
Track exceptions

Use trackError(Throwable throwable):

try {
	// Some code
} catch (Exception e ){
	InnometricsAPI.getInstance(context).trackError(e);
	// Your exception handling
}

Store profile attributes

To set profile attribute use setAttribute(String key, String value). This command will create new attribute in current collect application and section, or override it if attribute with the same key already exists. 


Set session data

Default session data

These session data are set by default to each session:

  • "device-model" 

  • "display-density"

  • "phone-type"

  • "display-height"

  • "display-width"

  • "network-operator-name"

  • "app-version-code"

  • "app-version-name"

  • "version-os"

  • "android-device-id"

You can change default set of session data with setDefaultSessionData(int[] dataFlags), argument is array of constants:

  • APP_CODE - app-version-code, app-version-name
  • DISPLAY - display-heightdisplay-width
  • DEVICE_ID - android-device-id
  • DEVICE_MODEL - device-model
  • VERSION_OS - version-os
  • NETWORK_OPERATOR_NAME -network-operator-name
  • PHONE_TYPE -phone-type


In this example is default session data will be only "display-height", "display-width" and "phone-type"

innometricsAPI.setDefaultSessionData(new int []{InnoNames.PHONE_TYPE,InnoNames.DISPLAY});

Custom session data

You can add your custom session data with setSessionData(String key, Object value):

innometricsAPI.setSessionData("key","valueObject");

Profiles identification and merging

Terms:

  • temporary profile ID used in case user isn't authenticated
  • canonical profile ID - user is authenticated in your system.

By default, when you init library (first time get instance of InnometricsAPI) it generates temporary profile ID with hashed from ANDROID_ID.


Once your user is authenticated, you need to set canonical id with mergeProfile(String canonicalProfileID) and then merge data of temporary profile into canonical with mergeProfile():

InnometricsAPI innometrics;
@Override
public void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	setContentView(R.layout.main);
	Button btnLogin = (Button) findViewById(R.id.buttonLogIn);
	innometricsAPI = InnometricsAPI.getInstance(this);
 
	// All events are collected in temporary profile now.
 
	// You can set temporary ID with your own algorithm with this method:
    // innometricsAPI.setTempProfileID(generateTempId());
 
	btnLogin.setOnClickListener(new View.OnClickListener() {
		@Override
		public void onClick(View view) {
 
			// After user have passed authorization you can set his login as profile ID and make it canonical
			name = textLogin.getText().toString();
			innometricsAPI.setCanonicalProfileId(name); //profileId will be hashed name
			innometricsAPI.mergeProfile(); 
			//Now all events from temporary profile will be merged to canonical one
		}
});

Tracking state of the App

There are periodical network synchronization process work in the library. You should suspend them when your app minimizes, goes to sleep or display turns off and resume it when application is active again. In order to do that use methods innometricsAPI.suspendBackgroundSync() andinnometricsAPI.resumeBackgroundSync():

abstract public class AbstractMyActivity extends Activity {
    InnometricsAPI innometricsAPI;
    Random r = new Random();
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        innometricsAPI = InnometricsAPI.getInstance(this);
    }
    @Override
    protected void onStart() {
        super.onStart();
        innometricsAPI.resumeBackgroundSync();
    }
    @Override
    protected void onStop() {
        super.onStop();
        innometricsAPI.suspendBackgroundSync();
    }
}

In this example defined abstract class extends Activity class and inherits all other Activity classes. By doing this you able to override methods onCreateonStart and onStop.

onCreate - contains initialization of the library. Since this is singleton initialization it will be called only once during first Activity creation.

onStart and onStop - contain sleep and wake up methods of - this allows to reduce energy consumption in minimized application.

Debug

Debug messages can be enabled in innometrics.xml with  

<bool name="innometrics_debug">true</bool>

Now you can see in console log what data is sent to Profile Cloud, what profile ID is used and API URLs:

05-27 08:42:50.169    1320-1357/? D/Inno﹕Send Url https://api.innomdc.com/v1/companies/<companyID>/buckets/<bucketName>/profiles/<profileID>?app_key=<appKey>&max_return_events=1000