For those of you building on the PhoneGap platform, we've created these instructions enabling your app for Xtify simple push notifications. These instructions are based on the 2.1 Cordova version of PhoneGap. PLEASE NOTE: because Apple has decided not to support armv6 architecture starting with Xcode 4.5 (iOS 6), you must remove the armv6 architecture from your project as well as CordovaLib.

Table of Contents

Basic Integration

1. Download Apache Cordova 2.x and install the iOS plugin.
   
   
2. Download the latest Xtify iOS SDK v2.x.
    
3. Create your Apple provisioning profile and generate your Xtify AppKey.
    
4. Follow the instructions on how to build the sample Apache Cordova app.
   
   
5. Unzip the Xtify SDK and drag and drop the Xtify library (XtifyLib) folder only into the sample app, check the box to “Copy items into destinations group’s folder (if needed), select “Create groups for any added folders”.
    
6. Click on your project name in the left navigation pane, select your target application, then select Build Phases, Link Binary with Libraries, and click “+” to add any frameworks missing from the following list:
   1. Foundation.framework
   2. UIKit.framework
   3. CoreGraphics.framework
   4. SystemConfiguration.framework
   5. MapKit.framework
   6. CoreData.framework
   7. MessageUI.framework
   8. CoreLocation.framework
   9. CFNetwork.framework
   10. libxml2.2.dylib
   11. libz.1.1.3.dylib
   12. MobileCoreServices.framework
   13. CoreTelephony.framework
        
7. Edit XtifyGlobal.h in the XtifyLib folder and enter your AppKey.
    

8. Edit your app delegate files to include Xtify methods. Here is an example based on the sample PhoneGap app.

   AppDelegate.h
9. Add an entry under the "Plugins" section into the Cordova.plist file in the "Resources" folder with the following data:
1. Key: XtifyCordovaPlugin
2. Type: String
3. Value: XtifyCordovaPlugin
    
10. Download the latest Xtify Cordova 2.1 SDK for iOS Plugin and copy the included files, XtifyCordovaPlugin.h and XtifyCordovaPlugin.m, into your xCode project.
     
11. Add "#import "XtifyCordovaPlugin.h" to your main app delegate, e.g., "AppDelegate.m".
     

12. In the init method of your view controller, instantiate the XtifyCordovaPlugin as shown.

    MainViewController.m

13. In your MainViewController.h file specify the current webview and the XtifyCordovaPlugin instance as properties. For example -

    MainViewController.h

14. In your main view controller, implement the webViewDidFinishLoad callback. For example -

    MainViewController.m
15. When you're ready to build, make sure you're using the Apple LLVM Compiler 4.x.

With this basic implementation, you should now be able to build your app, load it on your iOS device and test sending/receiving a push message. After your app is running on your phone, check the testing console and send a test message to your device. The push action will open your app. 

Advanced Services

To enable advanced services within your html/javascript PhoneGap app such as passing custom data, retrieving the XID and to retrieve last known location, please follow the next steps:

To Retrieve Custom Data

1. Create a file named pn.js, and include it in your index.html file (we provide an example in our plugin pack). Add the following function to it:

2. Within the print method of XtifyCordovaPlugin.m, find the following line and optionally set "customKey" to a name that you'll use in your push notifications. The customKey is the key that you will use when sending a push to the device via our console and API services.

   
   

3. Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

4. When you send a push notification using our Target tool or through our Push API, add the custom data to your push like this:

5. To pass the custom data to your pn.js file when you receive a push and hit open, add the following function to your pn.js file:

   pn.js

To Retrieve 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.

1. Add the following JavaScript code to pn.js:

2. Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

To Retrieve Last Known Location

If your app needs to know the last known location of the user, follow these instructions.

1. Add the following JavaScript code to pn.js:

2. Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

3. For location to work you need to make sure the location option is set in the XtifyGlobal.h file:

To Manage the Badge Count

1. Add the following methods to pn.js to set the application badge count

   pn.js

   Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

   pn.js

2. Add the following methods to pn.js to retrieve the badge count

   pn.js

   Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

   pn.js

3. Add the following methods to pn.js to clear all notifications from the tray and clear the badge

   pn.js

   Execute the callback. For example, if you'd like to test using a button, you'd use the onClick method such as:

   pn.js

Frequently Asked Questions

1. Can I suppress the popup notification while the app is in the foreground?
   1. Yes, you can do this by modifying the app delegate where the dialog is spawned. The -(void) showAlert:(NSDictionary *) push method in the AppDelegate class is where the dialog is shown. You can comment out execution of this this method within the - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)pushMessage method.

If you run into any issues, please post a comment or contact us for help.