BlackBerry Integration Guide

Introduction

These instructions assume you are using the Eclipse JDE Plugin. However the same steps will work if you are working with the RIM JDE.

There are several reasons we prefer to offer the BlackBerry client as source only:

1) The process for importing a jar into a BlackBerry project differs with every version of Eclipse.
2) Using external jar files in the BlackBerry JDE requires creating a second project which complicates the build cycle.
3) It is easy to cause the app not to launch because of a ‘verification error’ when working with external jars.

If you have different requirements please contact us and we will try to accommodate you.

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 appropriate library:
- If your project is targeting BlackBerry OS version 4.2.0 to 4.5 use the 4.2.0 Client Library.
- If your project is targeting BlackBerry OS version 4.5 and above use the 4.5 Client Library.
- * If you are unsure, use the 4.2.0 library.

4) Add the source code to an existing project by copying the Localytics’ ‘com’ folder into your project’s ‘src’ folder, such that the Localytics libraries are located at ‘%lt;project>\src\com\Localytics\LocalyticsSession’.

5) Import the library by adding to the top of your main activity:
```
import com.Localytics.LocalyticsSession.*;
```

It is recommended to maintain the LocalyticsSession object in your Application’s class, so that it can easily be accessed from any screen in your application. So create the object by adding the following to your application class (this is the class which calls .enterEventDispatcher().
```
private final static String APPLICATION_KEY = "Key generated in step 2";
private LocalyticsSession _session = new LocalyticsSession(APPLICATION_KEY);
```

7) Add an accessor function to your main application class so this object may be accessed from anywhere in your code:
```
public LocalyticsSession getLocalyticsSession().
{
    return this._session;
}
```

8) Open the session and begin uploading. Uploading should happen at the beginning of the app, and not the end because this shows the ‘would you like to allow access to analytics.localytics.com’ dialog which the user will see before they have a chance to begin an activity. This also provides the uploader the maximum amount of time to complete if the wireless network is slow. This is best done in the constructor of your application:
```
LocalyticsSkeletonApp()
{
    // open the session and begin uploading.
    _session.open();
    _session.upload();
    pushScreen(new LocalyticsSkeletonAppScreen());
}
```

9) Finally, for every exit path in your application, you must close the session. If you exit from within a screen, do this by calling the accessor created in step 7: ((appClassName)UiApplication.getUiApplication()).getLocalyticsSession().close(); However, the recommended way is to maintain a single exit point, inside the application class which gets called anywhere the app terminates.:
```
public void exit()
{
    this._session.close();
    System.exit(0);
}
```
Regardless of which method you choose, remember to overload any onClose() methods which could lead to an exit.

10) Test your app. Launch the simulator (or even better, compile, sign, and run on a real device), let the data upload, and view it on the webservice” to make sure it is there. Remember that the upload only happens when the session is started so any events you tag will not get seen until you upload data a second time.

11) One thing to note, the uploader code assumes the simulator will be able to make a connection with deviceSide=true; set. If you are testing in an MDS-only environment, simply change USE_MDS_IN_SIMULATOR to true in UploaderThread.java. This variable has no impact on how the library behaves on an actual device.

TIP: Once data is uploaded it cannot be deleted. Therefore it is recommended to create a test app in Localytics and use that while you perfect your instrumentation and then switch the app key for the production app.

Events (Optional)

public static final String USER_CHOICE_YES = "CHOICE_YES";
public static final String USER_CHOICE_NO = "CHOICE_NO";
public void someFunctionInsideAScreen()
{
    boolean result = ProvideUserWithChoice();
    if(result == true)
        ((AppClassName)UiApplication.getUiApplication()).
            getLocalyticsSession().tagEvent(USER_CHOICE_YES);
    else
        ((AppClassName)UiApplication.getUiApplication()).
            getLocalyticsSession().tagEvent(USER_CHOICE_NO);
}

It is highly recommended that you read the Tagging section in the Developer’s Integration Guide in order to get the most value out of your tags.

13) Add Attributes to tags. 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";
  HashTable values = new HashTable ();
  values.put(PLAYER_LEVEL, String.valueOf(this.playerLevel));
  localyticsSession.tagEvent(MyApp.TAG_RESET_GAME, values);

blog post

Developer’s Integration Guide

Sample Application Skeleton

LoclayticsSkeletonApp.java
package com.Localytics.SkeletonApp;

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

// Import the localytics Library
import com.Localytics.LocalyticsSession.*;

/**
 * A very simple application used to demonstrate a Localytics integration.  In this
 * case the application is only tracking two things:
 * 1) Session open and close
 * 2) What method the user used to exit the application.
 */
public class LocalyticsSkeletonApp extends UiApplication
{
	public static void main(String[] args)
	{
		LocalyticsSkeletonApp theApp = new LocalyticsSkeletonApp();
		theApp.enterEventDispatcher();
	}

	LocalyticsSkeletonApp()
	{
		// open the session and begin uploading.
		_session.open();
		_session.upload();
		pushScreen(new LocalyticsSkeletonAppScreen());
	}

	// All exit points for the application come here.  This is not required, but
	// it is a good practice because it keeps from having to add exit-time code
	// (such as closing the Localytics session) to every exit path.
	public void exit()
	{
		this._session.close();
		System.exit(0);
	}

	// Exposes the LocalyticsSession to all future screens.  This is not necessary
	// for this sample.  Instead, this object could be created in the MainScreen
	// and referred to from there.  However, it is a good practice to make the
	// object globally accessible so that if screens are added in the future it is
	// easy to tagEvents, or even close the session from those screens.
	public LocalyticsSession getLocalyticsSession()
	{
		return this._session;
	}

	// Create the Localytics Object.
	private final static String APPLICATION_KEY = "application_key_from_webservice";
	private LocalyticsSession _session = new LocalyticsSession(APPLICATION_KEY);
}

final class LocalyticsSkeletonAppScreen extends MainScreen
{
	// For this application, track the two ways users can exit.  This is done
	// by writing one of these events when a user exits.
	private final static String EVENT_BTN_EXIT = "EXIT_FROM_BUTTON";
	private final static String EVENT_CLOSE_APP = "EXIT_BY_CLOSING";

	public LocalyticsSkeletonAppScreen()
	{
		setTitle("Localytics Skeleton App");

		// Add an exit button to the application to demonstrate a second exit point.
		ButtonField exitButton = new ButtonField("Exit");
		exitButton.setChangeListener(new FieldChangeListener()
		{
			public void fieldChanged(Field field, int context)
			{
				// Fire the Button exit event
				((LocalyticsSkeletonApp)UiApplication.getUiApplication()).
					getLocalyticsSession().tagEvent(LocalyticsSkeletonAppScreen.EVENT_BTN_EXIT);

				// Call the global exit.  This isn't necessary, but if it isn't done
				// LocalyticsSession.close() must be invoked here.
				setDirty(false);
				((LocalyticsSkeletonApp)UiApplication.getUiApplication()).exit();
			}
		});
		add(exitButton);
	}

	// The other exit point for this application.
	public boolean onClose()
	{
		// Fire the 'exit by closing' event
		((LocalyticsSkeletonApp)UiApplication.getUiApplication()).
			getLocalyticsSession().tagEvent(LocalyticsSkeletonAppScreen.EVENT_CLOSE_APP);

		// Call the global exit.  This isn't necessary, but if it isn't done
		// LocalyticsSession.close() must be invoked here.
		setDirty(false);
		((LocalyticsSkeletonApp)UiApplication.getUiApplication()).exit();
		return true;
	}
}