For those of you building on the PhoneGap platform, we've created these instructions enabling your app for Xtify simple push notifications.  These instructions were created using PhoneGap Cordova version 2.7 for Android. 

Table of Contents

Create a New Google API Project with GCM

1. Open the Google APIs Console page.
    

2. If you haven't created an API project yet, this page will prompt you to do so:
   
   
   
   Note: If you already have existing projects, the first page you see will be the Dashboard page. From there you can create a new project by opening the project drop-down menu (upper left corner) and choosing Other projects > Create.
    

3.  Click Create project. Click Create project. Google will create a Project Number for you. This Project Number is what you will include in your application. 
    
4. Click on the Services tap and enable Google Cloud Messaging for Android: 
   
    
    
5. Click on the API Access tab and take a note of the API Key. This will be used later when you register your Android application with Xtify.
   
   

Register your Android App with Xtify

1. Select "Add New Application" on the Create/Manage Application Keys page.
     
2. Complete top section of form by filling in the Name and choosing an Application Type and Application Category.  
    
3. Select GCM as the Application OS. Add your API key to the Google API key filed. 
   
4. Click Submit.
    
5. Copy your Application Key and Secret from the page.
   

Implement the Xtify PhoneGap/Cordova plugin within your App

If you already have a working PhoneGap app and just want to add Xtify, skip down to step 3.

1. Download PhoneGap 2.1 for Android.
    
2. Create a new Android PhoneGap project. Check out PhoneGap's start page for a primer.
    
3. Download Xtify Android SDK version 2.x.
    
4. Add Xtify Android GCM SDK to your project path
   1. Create new folder in your project called libs.
   2. Move the Xtify SDK jar file to it (you could find the SDK jar file in the root directory after you unzip the SDK package).
       
5. Modify your project 'AndroidManifest.xml' file:

   1. Android Version: Set the minimum Android SDK version to '8' (Android 2.2) or higher. The Xtify GCM SDK will not work with previous versions. 
      

      
      

   2. Permissions: The following permissions are needed for the SDK to work properly (These are positioned as children of the <manifest> node). Replace the two occurrences of YOUR_APP_PACKAGE_NAME with your application package name.

      1. If you'd like to implement the optional Xtify Location features, insert the following: 

      2. If you want to use the optional Dial Action in the notification details screen, add this:

   3. Application Components: Add the following xml to the <application> node. Replace the occurrence of YOUR_APP_PACKAGE_NAME with your application package name:
6. Download the latest Xtify Cordova 2.1 SDK for Android Plugin (this also contains a sample Cordova/Xtify fully-integrated app for your reference)
    

7. After you unzip the Xtify PhoneGap plugin package, you will find a folder that contains the following files: 

   1. xtify.properties
   2. XtifyCordovaPlugin.js
   3.  xtify-cordova-plugin-x.x.jar  
       
8. Add the following files to your project:
   1. Add the xtify-cordova-plugin-x.x.jar to the libs folder that you created in your project. 
   2. Add the file xtify.properties to the "assets" directory in your project, edit the file and change YOUR_XTIFY_APP_KEY with your Xtify appKey and YOUR_SENDER_ID with the Google APIs Console Project Number.  Do not place quotes neither for the appKey nor for Google API.

   3. Add the file XtifyCordovaPlugin.js to the "assets/www" directory in your project. 
       

9. Edit (or Create if it doesn't exist) a file called "config.xml" in the "res/xml/" directory with the following content:

10. In your main activity that extends DroidGap, you need to replace extends DroidGap with extends com.xtify.cordova.XtifyDroidGap . Example:

11. Add the xtify-cordova-plugin-x.x to your index.html webpage by including the follwing line in the head declaration (remember to replace x.x with the version number):

12. Start Xtify SDK from javascript (within the head tags of index.html) and pass the failureCallback and notificationCallBack functions (it should not be an anonymous function) that will be called on receiving notifications: 

After following these instructions, you should be able to sent and receive push notifications using our Target console tool and via our Push API. If you run into any issues, please post a comment or contact us for help.

Advanced Integration Topics

Follow these instructions to extend your basic PhoneGap / Xtify integration.

To Check if User Registration is Successful

Call XtifySDK.isRegistered to check if the device is registered or if an error occurred: 

Error Types

Xtify errors:

GCM errors:

To Retrieve the XID

The XID is the unique identifier that Xtify assigns to users of your app. If you'd like to send messages to individual users via the Xtify Push API service, you'll need to store this value within your user database. The following code retrieves the XID: 

Note: You should try to retrieve the XID only when the device has registered, otherwise you will get an error message.

To Retrieve Custom Data

You can send custom data to your app through the Xtify APIs or through our push console, such as: { myKey : myValue }.  Please note that for custom keys (not Xtify keys) the key is prepended with "data.". You can retrieve this data using our PhoneGap plugin in JavaScript. Here's an example:

The following Keys are Available:

To customize the notification icon

Copy the notification icon to your drawable folder and then call XtifySDK.setNotifIcon function with your icon name: 

Frequently Asked Questions

1. I've built the sample app included in the plugin zip, but after I build it, registration keeps stating "In progress"
   1. This is likely due to your GCM/Google API credentials.  The sample app has been thoroughly tested using our own Google API / GCM sender/project ID. Please verify that this ID is correctly in your assets/xtify.properties file.
       
2. I've built the sample app, and get an XID, but I can't receive a push on my device.
   1. This is likely due to an incorrect Google API Key entered into the Xtify Console. Please verify that you have an active Google API key with GCM permissions and that it is entered properly within the Xtify Console AppKey Manager.