Android Integration Guide for Phones & Tablets

Upgrading

If you are upgrading from an older version of the SDK, simply delete the old localytics directory with the old source and drop the new one in. You may have to change the package name on your import to: com.localytics.android.* if you were using an older library.

Ten Minute Instrumentation Instructions

1) Go to the Localytics Registration Page and create an account if you do not already have one.

2) In your account, create a new application and copy the application key.

3) Download the Android Client. It is distributed as source code. Please contact us if a binary is preferable.

4) Unzip this archive and drag the com folder into your project’s source to include the library.

5) Import the class by adding the following to the top of your main activity:
```
import com.localytics.android.*;
```

6) Add the session object as a private member variable inside your class:
```
private LocalyticsSession localyticsSession;
```

7) In OnCreate, instantiate the object, open the session, and upload any data:

public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    // Activity Creation Code

    // Instantiate the object
    this.localyticsSession = new LocalyticsSession(
                   this.getApplicationContext(),  // Context used to access device resources
                   "APP KEY FROM STEP 2");       // Key generated on the webservice

    this.localyticsSession.open();                // open the session
    this.localyticsSession.upload();      // upload any data

    // At this point, Localytics Initialization is done.  After uploads complete nothing
    // more will happen due to Localytics until the next time you call it.
}

8) in onResume, call open and upload again. In most cases, the session will be opened and data uploaded by the calls in onCreate. However activities may go from onPause to onResume without passing through onCreate and therefore, the open call needs to appear here as well. If it is called twice for an already open session it will be ignored.
```
public void onResume()
{
    super.onResume();
    this.localyticsSession.open();
}
```

9) in onPause, close the session and upload data.. onPause is the last state which is guaranteed to be called so it makes the most sense for the close call. This may cause multiple close events to occur but only the final close is honored.
```
public void onPause()
{
    this.localyticsSession.close();
    this.localyticsSession.upload();
    super.onPause();
}
```

10) Repeat the above steps for any other activities in your application. Calling open() in every activity’s onCreate and onResume will cause every activity to reconnect to the already opened session instead of creating a new one.

11) In your application’s manifest ‘AndroidManifest.xml’ make sure Internet permissions are available. (If your application already accesses the Internet, this will already be done.) In Eclipse: Select ‘AndroidManifest.xml’ from the Package Explorer. Select the ‘Permissions’ tab. Click ‘Add…’. Select ‘Uses Permission’ and hit ‘OK’. Under ‘Name’, enter android.permission.INTERNET This can also be done by editing the AndroidManifest.xml file manually. Simply add the following after the other ‘
‘ tags:
```
<uses-permission android:name="android.permission.INTERNET">
```
12) Congratulations! You have integrated your app! Run your application in the emulator (or on a real device if possible) and check your Localytics dashboard to see the data being reported.

Events (Optional)

Whenever an event happens in your application which you are interested in recording, you may tag it with a call to tagEvent:

  private final static String TAG_RESET_GAME = "reset game";
  public void resetGame()
  {
    this.localyticsSession.tagEvent(MyApp.TAG_RESET_GAME);
    // Perform game reset.
  }

When doing this it is best to predefine your events as final static Strings for performance reasons, data actionability, and to avoid collecting any personally identifiable information. It is also highly recommended that you avoid calling this function in a loop to avoid collection of too much data. Please refer to the TAGGING SECTION of the Developer’s Integration Guide for more information.

For some events, it may be interesting to collect additional data about the event. Such as how many lives the player has, or what the last action the user took was before clicking on an advertisement. This is accomplished with the second form of tagEvent, which takes a map of key/value pairs along with the event name:

  private final static String PLAYER_LEVEL = "Player Level";
  Map <string,String> values = new HashMap<string,String> ();
  values.put(PLAYER_LEVEL, String.valueOf(this.playerLevel));
  localyticsSession.tagEvent(MyApp.TAG_RESET_GAME, values);

See our introductory blog post for more information. It is recommended that you read the Event Attributes section in the Developer’s Integration Guide in order to get the most value out of your attributes.

Important Note: Make sure never to upload data from a continuous set. Consider tagging a file transfer event with the file size. If the file can be any size this will cause many buckets to be created on our server. When you look at the data in the charts, there will be many charts each with only a few results and the data will be in-actionable. Instead, it is necessary to bucket this data into groups such as “0 to 1K”, “1K to 50K”, etc. See our blogpost for an example.

Screen Flows (Premium)

When an activity is shown, it can be tagged so that all user flows through the application can be tracked.
To do this, add a tagScreen call in the onCreate call after the session open for each of your views.

public void onCreate(Bundle savedInstanceState) {

  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);
  // Activity Creation Code

  // Instantiate the object
  this.localyticsSession = new LocalyticsSession(
                 this.getApplicationContext(),  // Context used to access device resources
                 "A Unique Key");       // Key generated on the webservice
  this.localyticsSession.open();                // open the session
  this.localyticsSession.tagScreen("Splash");
  this.localyticsSession.upload();      // upload any data
  // At this point, Localytics Initialization is done.  After uploads complete nothing
  // more will happen due to Localytics until the next time you call it.
}

Sample Application Skeleton

To see it all at once, here is the skeleton of an instrumented Android application: (Note: this code assumes a button is created with an id named TestButton)

SkeletonView.java
package com.Localytics.SampleSkeleton;

import android.app.Activity;
import android.os.Bundle;
import android.widget.Button;
import android.view.View;
import android.view.View.OnClickListener;

import com.Localytics.android.*;

public class SkeletonView extends Activity
{
    private final static String LOCALYTICS_APP_KEY ="KEY_GENERATED_ONLINE";
    private final static String EVENT_TEST_BUTTON = "Test Button";
    private LocalyticsSession localyticsSession;


    private Button testButton;

    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        this.localyticsSession = new LocalyticsSession(
                       this.getApplicationContext(),
                       SkeletonView.LOCALYTICS_APP_KEY);
        this.localyticsSession.open();
        this.localyticsSession.upload();

        // This demo assumes a button called TestButton has been defined
        // in the main XML layout.
        this.testButton = (Button)findViewById(R.id.TestButton);
        this.testButton.setOnClickListener(new OnClickListener()
        {
            public void onClick(View v)
            {
		localyticsSession.tagEvent(SkeletonView.EVENT_TEST_BUTTON);
            }
        });
    }

     public void onResume()
    {
        super.onResume();
        this.localyticsSession.open();
    }

    public void onPause()
    {
        super.onPause();
        this.localyticsSession.close();
        this.localyticsSession.upload();
    }
}

Debugging No Data

Here are some common steps for debugging instrumentation which does not appear in the UI:
1) Double check the app key. Is it missing a first and last character or does it have an extra space somewhere?
2) Enable tracing. Debugging traces can be turned on by setting IS_LOGGABLE as defined in Constants.java to true. Then, send the log to us at support@localytics.com.

Library Support

As of March 31 2012 we will be limiting our support of all iOS and Android libraries before version 2.0. This will include no more event tracking, and possibly some limitations to session tracking. You can find our new libraries in the links to the left.