Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/farwayer/xtremepush_android
Android library for Xtremepush.com system
https://github.com/farwayer/xtremepush_android
Last synced: 23 days ago
JSON representation
Android library for Xtremepush.com system
- Host: GitHub
- URL: https://github.com/farwayer/xtremepush_android
- Owner: farwayer
- Created: 2014-08-30T14:57:23.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2014-09-02T12:55:38.000Z (over 10 years ago)
- Last Synced: 2024-10-15T15:33:07.638Z (2 months ago)
- Language: Java
- Size: 1.48 MB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
XtremePush Android integration guide
==================
Version with runtime R ids
[About](#about)
[Integrating](#integrating)
1. [Download Library](#download)
2. [Add XtremePush to your Project](#add_xtreme)
3. [Connect your App to the XtremePush Platform](#connect_xtreme)
4. [Sending your first Push](#first_push)
5. [Tagging your app to enable deeper audience analysis and segmentation](#tagging)
6. [Turning off location or adjusting location settings](#location_off)
7. [Setting custom behaviour on push notification arrival](#push_listener)
[Appendix A: Getting an API Key for Google Cloud Messaging](#keys)
## 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 the latest library version [here](https://github.com/xtremepush/XtremePush_Android/archive/master.zip).
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
```xml
```
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.**
```xml
```
3. Inside the application element in you android manifest add the following:
```xml
```
**Note: in
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](#keys)
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](#keys)
5. Return to your project in your IDE. In your Main Activity import the library:
```java
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:
```java
// 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:
```java
@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:
```java
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:
```objc
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:
```java
@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](http://developer.android.com/google/gcm/gs.html).
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*.
