farwayer / XtremePush_Android

Android library for Xtremepush.com system

XtremePush Android integration guide

Version with runtime R ids

About

Integrating

1. Download Library
2. Add XtremePush to your Project
3. Connect your App to the XtremePush Platform
4. Sending your first Push
5. Tagging your app to enable deeper audience analysis and segmentation
6. Turning off location or adjusting location settings
7. Setting custom behaviour on push notification arrival

Appendix A: Getting an API Key for Google Cloud Messaging

About

This document should provide all the info you need to integrate your Android app with the XtremePush platform and send your first push via the platform.

Integrating

1. Download Library

1. Download the latest library version here.

2. Extract the archive, it contains the folder XtremePush_Android-master/ with the following folders and files:

2. Add Xtreme Push to your Project

1. Import XtremePush_Android-master/ into your IDE. Add it as a library to your project as per your IDE for example on eclipse adding the library looks like this:

   

2. Next add the following permissions to your Android Manifest

   <!-- GCM requires a Google account. -->
   <uses-permission android:name="android.permission.GET_ACCOUNTS" />
   
   <!-- Keeps the processor from sleeping when a message is received. -->
   <uses-permission android:name="android.permission.WAKE_LOCK" />
   
   <!-- Other -->
   <uses-permission android:name="android.permission.READ_PHONE_STATE" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

   You must also add a custom permission to your app so only this app can receive messages. NOTE: the permission must be called YOUR_PACKAGE.permission.C2D_MESSAGE, where YOUR_PACKAGE is the application's package name.

   <!--Creates a custom permission so only this app can receive its messages.-->
   <permission
       android:name="YOUR_PACAKAGE.permission.C2D_MESSAGE"
       android:protectionLevel="signature" />
   
   <uses-permission android:name="com.example.xtremepushtestapp.permission.C2D_MESSAGE" />
   
   <!-- This app has permission to register and receive data message. -->
   <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

3. Inside the application element in you android manifest add the following:

   <receiver
       android:name="ie.imobile.extremepush.GCMReceiver"
       android:permission="com.google.android.c2dm.permission.SEND" >
       <intent-filter>
           <action android:name="com.google.android.c2dm.intent.RECEIVE"/>
           <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
           <category android:name="YOUR_PACKAGE" />
       </intent-filter>
   </receiver>
   
   <service android:name="ie.imobile.extremepush.GCMIntentService" />
   <receiver android:name="ie.imobile.extremepush.location.ProxymityAlertReceiver" />
   <activity
       android:name="ie.imobile.extremepush.ui.WebViewActivity"
       android:exported="false" />

Note: in <category android:name="YOUR_PACKAGE" make sure you replace YOUR_PACKAGE with the application's package name

3. Connect your App to the XtremePush Platform

1. Add your App on the platform by clicking "Integrate Push Features" on your XtremePush Dashboard at xtremepush.com

   

2. Enter the App Name, upload the App icon, and give a short description of the app. An App key and token have been automatically generated. The App key is used in your Android project to connect the app and platform. The app token will only be used if you use the external API. Save your settings and copy the app key. Your saved settings should be similar to the following.

   

3. Still in your App Home on xtremepush.com go to Settings > Application Keys and copy your API Key for Google Cloud Messaging into Android Application Key and click save. If you don't now where to get this key please read our documentation on Getting an API Key for Google Cloud Messaging here

   

4. Next you will use your app key from the Settings > General Settings section of your app home on xtremepush.com and your project number from the google developer console to connect your app to the platform. If you don't know where to get the project number please refer to our documentation on Getting an API Key for Google Cloud Messaging here

5. Return to your project in your IDE. In your Main Activity import the library:

import ie.imobile.extremepush.*;

Next you must add a line above the onCreate method and one inside the onCreate method in your main activity like this:

// declare the xtremepush connector here
private PushConnector pushConnector;

        @Override
        protected void onCreate(Bundle savedInstanceState) {
           super.onCreate(savedInstanceState);
           setContentView(R.layout.activity_main); 
           
	     // and initialise the xtremepush connector here
           pushConnector = PushConnector.init(getSupportFragmentManager(), XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER);
        }

Finally further down in the main activity add the following two methods:

       @Override
        protected void onActivityResult(int requestCode, int resultCode, Intent data) {
            super.onActivityResult(requestCode, resultCode, data);
            pushConnector.onActivityResult(requestCode, resultCode, data);
        }

        @Override
        protected void onNewIntent(Intent intent) {
            super.onNewIntent(intent);
            pushConnector.onNewIntent(intent);
        }

You are now ready to send your first push.

4. Sending your first Push

1. To send a basic push go to your app home and select create campaign. The first step is to name your campaign and add some content for the push. In this section you can also link to app pages, urls, or a custom html page for a richer push but for now we will just add text for a simple push.

   

2. Click next and you will be taken to the segments section. For your first push select broadcast to all users and refresh the number of addressable devices if you are using one development device this value should be one.

   

3. Click next and you will be taken to location, for your first push you will not be tying it to a location so click next and you are taken to schedule. In schedule the default selection is Send Now and to test your first push you will want to keep it that way.

   

4. Click next and you will be taken to platform. Select Android as your platform.

   

5. You are almost ready to send your first push. Click preview, review your text and then hit send push. Your Android device will receive the push:

   

5. Tagging your app to enable deeper audience analysis and segmentation

XtremePush has two methods for tagging activity in your app one for tagging page impressions and one for tagging any other activity.

To tag page impression call the pushConnector.hitImpression(String tag) method where your page loads:

pushConnector.hitImpression("your_impression_name");

To tag any other events call the pushConnector.hitTag(String tag) method where that event occurs:

    pushConnector.hitTag("your_tag_name");

6. Turning off location or adjusting location settings

Turn off Location

To turn off the location features set locationEnabled false before you initialise XtremePush in the onCreate method of your main activity as follows:

	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_main);
		
		// Turn off location
		PushConnector.locationEnabled(getApplicationContext(), false);

		// initialise the xtremepush connector here        
		pushConnector = PushConnector.init(getSupportFragmentManager(), XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER);    

Adjust Location

If you need to keep the location features but want to manage the trade off between the sensitivity of location detection and the impact on battery life then you have the option to set the frequency of location updates. This can be done by setting an additional two values when initialising XtremePush in the onCreate method of your main activity. These are locationCheckTimeout and locationDistance :

init(FragmentManager fm, String appKey, String projectNumber, int locationCheckTimeout, float locationDistance).

Set locationCheckTimeout to your desired location update frequency in minutes and locationDistance to desired updates frequency in meters. If you set locationCheckTimeout to 30 and locationDistance to 500 then location will be updated every 30 minutes or if the device moves 500 meters depending on which occurs first. You would initialise this setup as follows:

@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_item_list);
	
		pushConnector = PushConnector.init(getSupportFragmentManager(), "XPUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER", 30, 50 );

7. Setting custom behaviour on push notification arrival

If you want to control when a push notification arrives and what it contains you can create a class that implements the PushListener interface and pass it to PushConnector using the method:

PushConnector.setPushListener(PushListener pl).

The PushListener interface has one method to implement:

PushListener.onPushMessage(PushMessage pm).

This method will be called every time a new Push Message arrives. You can add your own code to this method to handle the PushMessage in a custom way.

Appendix A: Getting an API Key for Google Cloud Messaging

To integrate XtremePush with an Android app you need to upload your GCM API key to your app dashboard on xtremepush.com. This is because to send push notifications to Android devices, you need to set up a Google API Project, enable the GCM service and obtain an API key for it. In this section we will summarise the main steps involved. You can also find Google's own guide to setting up a Google API Project and obtaining an API key for the GCM service here.

The first step is to:

• Go to: https://console.developers.google.com/
• Log in
• Create a project for your app if you don't already have one

Next click on your project and you will be taken to your project home. Your project Number is diplayed on top of this page you will need that later to integrate your app with XtremePush but first you must select APIs & auth to enable GCM.

In APIs & auth > API scroll down until you find Google Cloud Messaging for Android and switch it on:

In the sidebar on the left, select APIs & auth > Credentials. On the right under Public API access , click Create New Key and select Server Key. Do not specify any ip address and click Create.

Copy the new API Key you are given under Public API Access > Key for server applications in. Log in to your XtremePush dashboard on xtremepush.com. Go to your app home and navigate to Settings > Application Keys and select Android App. Paste the key into Android Application Key and click save.