Android SDK

Releases
Setup
- Initializing with Development and Production keys
Example Calls
Optional Automated Tracking
Changes from v1
- Performance
- Android v2 SDK specs

We have built an official Android SDK that uses our API’s common methods, and some specific to the Android platform.

Releases

https://github.com/kissmetrics/KISSmetrics-Android-SDK/releases

Setup

Within your Application subclass or main activity’s onCreate method:

// Initialize the API
KISSmetricsAPI.sharedAPI(<API KEY>, <Application Context>);

Initializing with Development and Production keys

boolean isDebuggable =  ( 0 != ( getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE ) );
if (isDebuggable) {
	KISSmetricsAPI.sharedAPI("yourDevelopmentProductKeyHere", getApplicationContext());
}else{
	KISSmetricsAPI.sharedAPI("yourProductionProductKeyHere", getApplicationContext());
}

Example Calls

// Track Event
KISSmetricsAPI.sharedAPI().record("Activated");
KISSmetricsAPI.sharedAPI().recordEvent("Activated");	// recordEvent() is being deprecated

// Track Event with Properties
HashMap<String, String> properties = new HashMap<String, String>();
properties.put("Item", "Potion");
properties.put("Amount", "10");
KISSmetricsAPI.sharedAPI().record("Purchase", properties);

// Set Properties
HashMap<String, String> properties = new HashMap<String, String>();
properties.put("Item", "Potion");
properties.put("Amount", "10");
KISSmetricsAPI.sharedAPI().set(properties);
KISSmetricsAPI.sharedAPI().setProperty(properties);	// setProperty() is being deprecated

/* New Functions as of v2 */
// Track an event only once per set identity. After an identity is cleared or a new 
// identity is set, the condition will pass once again.
KISSmetricsAPI.sharedAPI().record("Viewed feature", KISSmetricsAPI.RecordCondition.RECORD_ONCE_PER_IDENTITY); 

// Track an event only once per install
KISSmetricsAPI.sharedAPI().record("Installed App", KISSmetricsAPI.RecordCondition.RECORD_ONCE_PER_INSTALL); 


// Set user properties only if they have changed on the device
HashMap<String, String> properties = new HashMap<String, String>();
properties.put("OS version", "7.1");
KISSmetricsAPI.sharedAPI().setDistinct(properties);

Optional Automated Tracking

`autoRecordInstalls()`

Calling this records two events:

Installed App
Updated App

`autoSetAppProperties()`

Calling this sets the following properties:

App Version : 1.0.0 (aka: versionName)
App Build : 1 (aka: versionCode)

`autoSetHardwareProperties()`

Calling this sets the following properties:

Device Manufacturer : asus
Device Model: Nexus 7 (but this may also just be a cryptic model #. This depends on the manufacturer.)
System Name : Android (hard-coded)
System Version : 4.2.2

Changes from v1

If you previously used 80steve’s Android library, there are some functional changes from his library:

Identities, Events and Properties are URL encoded for you. If you’re upgrading to this SDK, you should remove any URL encoding or URL encoded characters that may have been added as a workaround to the lack of encoding in the unoffical Android SDK.
The identify method now works the same as it does in our JavaScript library. That is, recording identities no longer aliases known identities to one another.
- For example, if a user has been given a known identity such as “user@example.com” and a second call is made to identify: “another@example.com”, the SDK no longer assumes that this a second known identity for the same user and these identities will no longer be aliased to one another automatically.
Now, if there are 2 or more known identities of a user, a call to alias these two identities must be made.
Previously, a call to clearIdentity() was required before a new users’s identity was set. Though, it’s still a good idea to call clearIdentity() when a user signs out.

Performance

In the new SDK, all calls to record events, properties, identities and aliases are immediately passed onto a background thread for processing and delivery.

In our unofficial SDK (v1), the processing of these calls was handled by the same thread that made the call to record before being delivered asynchronously. This wasn’t optimal as an application’s main thread is responsible for view updates and user interactions.

As a third party addition to our customers’ apps, we should use as little of the main thread as possible to ensure that our SDK doesn’t contribute to any lag in the users’ experience of their apps.

Android v2 SDK specs

Size (compiled): 41kb
Memory Overhead
- idle: 21kb
- per avg. event with properties: estimated at < 500 bytes (< 200 for required params plus assumed < 300 bytes for average event with properties). During archiving of each event with properties, approximately 6kb of memory is allocated.
Android version support: 2.2 (Froyo) (>99% of Android devices)

Kissmetrics