ANDROID SDK Download and Integration Steps

Follow the steps below to get started with the Quick Start Sample App and Android SDK.

Step 1: Download Quick Start App and SDK

---> Click HERE to download the Xtify SDK package. (Register first if you haven't done so yet)

The Xtify SDK contains four main components:

A sample app that demonstrates how to integrate the Xtify SDK
The SDK code packaged as a .JAR file
JavaDoc API documentation.
'Integration Steps' document - a copy of this document.

Step 2: Get an Application Key

To get started with the Xtify SDK, you need to create an Application key. When creating an Application Key, you will be asked to create an intent Filter Name. The intent name you provide on this page must match the intent filter defined in your application's manifest file. This will enable your users to open your application from the notificaiton itself.

Step 3: Modify the 'AndroidManifest.xml' file

Android Version

Set the minimum Android SDK version to '3' (Android 1.5) or higher. The Xtify SDK will not work with the two previous versions, Android 1.0 and 1.1.

Permissions

The following permissions are needed for the SDK to work properly:

android.permission.ACCESS_FINE_LOCATION

android.permission.ACCESS_COARSE_LOCATION

android.permission.RECEIVE_BOOT_COMPLETED

android.permission.READ_PHONE_STATE

android.permission.ACCESS_NETWORK_STATE

android.permission.INTERNET

android.permission.ACCESS_WIFI_STATE

android.permission.CHANGE_WIFI_STATE

android.permission.VIBRATE

These are positioned as children of the <manifest> node and have the format

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

Service, Activity, and Receiver components

Add the following xml to the <application> node:

<activity

android:name="com.xtify.android.sdk.SettingsActivity"

android:label="Settings"

</activity>

<activity

android:name="com.xtify.android.sdk.NotificationDetailsActivity"

android:label="Notification Details"

</activity>

<activity

android:name="com.xtify.android.sdk.NotificationSettingsActivity"

android:label="Notification Settings"

</activity>

<service

android:name="com.xtify.android.sdk.MainService"

android:label="Notifications Service"

<intent-filter>

</intent-filter>

</service>

<intent-filter>

</intent-filter>

<intent-filter>

</intent-filter>

<intent-filter>

</intent-filter>

</receiver>

Replace the two occurrences of 'YOUR_API_KEY_GOES_HERE' with the API key you registered earlier. Note that one of these has a preceding forward slash that must be present!

Change the line that reads "<category android:name="com.xtify.android.sdk.IMainService.Vxxxx" />" to have the sdk version number of the jar file you are using (for example com.xtify.android.sdk.IMainService.V1021). The sdk version number can be found in the jar's manifest file as the 'sdk-version' attribute.

Step 4: Main Activity Java File

Add the following code to the onCreate() method. This code starts and/or ensures that the Xtify SDK is running:

Context context = this;

persistentLocationManager = new PersistentLocationManager(context);

Thread xtifyThread = new Thread(new Runnable() {

@Override

public void run() {

persistentLocationManager.setNotificationIcon(R.drawable.notification);

persistentLocationManager.setNotificationDetailsIcon(R.drawable.icon);

boolean trackLocation = persistentLocationManager.isTrackingLocation();

boolean deliverNotifications = persistentLocationManager.isDeliveringNotifications();

if (trackLocation || deliverNotifications) {

persistentLocationManager.startService();

}

});

xtifyThread.start(); // to avoid Android's application-not-responding dialog box, do non-essential work in another thread

This code also defines the notification icon and the logo that appears on the notification details screen, though that is not mandatory. The image specifications are described in the javadoc documentation.

The main Activity also contains a menu that allows the user to modify the SDK settings. This screen is displayed from the menu item using:

persistentLocationManager.showSettingsActivity(context, false);

Step 5: Include Jar file

The 'XtifyAndroidSDK.jar' file is placed in the 'jar/' directory and added to the classpath. In Eclipse, this can be accomplished by clicking Project Properties > Java Build path > Libraries > Add JARs.

Step 6: Emulator Configuration

If using the emulator, enable cell tower-based locations in the settings, otherwise the emulator will show a 'Force close' dialog box whenever an app is run that uses the Xtify SDK. It is not the app that crashes; the Android OS crashes internally. To avoid this problem, check the 'Use wireless networks' checkbox in Settings > Security & location.

Step 7: Custom Intents and Data

The AcmeLabs sample application demonstrates the use of custom intents and data, how to define them, and how to handle them. If you are using custom intents and data, have a look at the sample application to get started.

Step 8: Internationalization

You can internationalize the SDK GUI by providing some or all of the following values in your 'strings.xml' file and translating them for each language that your app supports:

<string name="enableNotificationsTitle">Enable notifications</string>

<string name="enableNotificationsSummary">Enables or disables notifications notifications</string>

<string name="locationTrackingCategoryTitle">Location Updates</string>

<string name="locationTrackingTitle">Enable location updates</string>

<string name="locationTrackingSummary">Sends location updates to the server for more relevant notifications</string>

<string name="locationTrackingFrequencyTitle">Usage frequency</string>

<string name="locationTrackingFrequencySummary">Specify the number of minutes</string>

<string name="gpsUsageTitle">Use GPS when available</string>

<string name="gpsUsageSummary">Uses GPS when more accurate location updates are necessary</string>

<string name="gpsUsageFrequencyTitle">Usage frequency</string>

<string name="gpsUsageFrequencySummary">Specify the number of minutes</string>

<string name="settingsButtonLabel">Settings</string>

<string name="shareButtonLabel">Share / Save</string>

<string name="shareNotificationDialogTitle">Share notification via</string>

There's no need to call any api in the SDK. These values will be read from your app's R file using Java's reflection mechanism. Please refer to the Android developer documentation at http://developer.android.com/guide/topics/resources/resources-i18n.html for details on how internationalization works on Android.

The following items are not yet internationalized:

the title, message, and ticker of the notification displayed in the notification bar
the title and content in the notification details screen
the label for the main action button in the notification details screen

If you are using the webservice API to send messages to individual users, and you know the locale of each user, you can determine the right message language (title, message, action button, etc) to send.

Step 9: Processing Notifications Internally or Conditionally Displaying Them to the User

This section applies as of version 1035 of the SDK.

In the manifest, add your own BroadcastReceiver that looks like this:

You've now added your own BroadcastReceiver that has a higher priority than the one in the SDK. The SDK uses ordered broadcasts, so your receiver will handle the message first. If you want to block a particular message from being displayed to the user, call BroadCastReceiver's abortBroadcast() function in your receiver.

The intent you'll receive in your BroadcastReceiver contains some combination of the following fields depending on what data you placed in your notification:

string: NOTIFICATION_TITLE
string: NOTIFICATION_DETAILS
string: NOTIFICATION_URL
string: NOTIFICATION_CP_ID (the api key)
string: NOTIFICATION_TICKER
string: NOTIFICATION_ACTION_COMPONENT
string: NOTIFICATION_ACTION_LABEL
string: NOTIFICATION_GROUP_ID
string: NOTIFICATION_ACTION_NAME
string: NOTIFICATION_ACTION_CATEGORIES
string: NOTIFICATION_ACTION_DATA
boolean: NOTIFICATION_SHOW_THUMBS
double: NOTIFICATION_LOCATION_LATITUDE
double: NOTIFICATION_LOCATION_LONGITUDE

See Xtify Push Demo!!!

A (relatively) short demonstration of the Xtify platform from the Motodev booth at CTIA.

Click HERE FOR VIDEO now!