usergrid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sfeld...@apache.org
Subject [28/36] usergrid git commit: Update generated website content.
Date Wed, 26 Aug 2015 15:40:39 GMT
http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/adding-push-support.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/adding-push-support.txt b/content/docs/_sources/push-notifications/adding-push-support.txt
new file mode 100644
index 0000000..956ac86
--- /dev/null
+++ b/content/docs/_sources/push-notifications/adding-push-support.txt
@@ -0,0 +1,158 @@
+# Adding push notifications support
+You add push notification support by configuring services, then adding app code to receive messages. You'll set up an account with a notification service (such as Apple's APNs or Google's GCM). Then you'll configure your App Services application to send notifications to the service. Then you'll add code to receive messages.
+
+## Setting up push notification support
+The following steps get you set up so that your app can receive push notifications. Keep in mind that these steps build on one another. In other words, you'll need values generated in step 1 in order to complete step 2, and so on.
+
+For a walkthrough of these steps using a push sample app, see [Tutorial: Push notifications sample app].
+
+1. __Register your app__ with push notification services.
+Your notification messages will be forwarded to devices by Apple and/or Google. So you'll need to register with Apple APNs and/or Google's GCM. For more information, see Registering with a notification service.
+
+2. __Create a notifier__ to send notification messages from App Services to notification services.
+App Services will use your notifier to send your messages to a notification service. For details, see Creating notifiers. To create a notifier, you'll need information generated by registering with a push notification service. You'll need a separate notifier for each app/platform combination.
+
+3. __Register devices__ at run time.
+At run time, your code will register to receive notifications. To do this, your code uses information from the notification service and App Services notifier. For more, see Managing users and devices.
+
+4. __Send and manage push notifications__
+You use App Service API notification endpoints to target devices, users, or groups with your messages. To learn more, see Creating and managing notifications.
+
+### How the pieces connect
+Click a tab below to view more information about how the pieces connect once you've got it set up.
+
+### Apple APNs
+
+The diagram below illustrates what things should look like once you've gotten set up to send notifications that are received by your app.
+
+A. At configuration time, you create an App ID, then create an App Services notifier with a .p12 certificate you generate on your Mac. The .p12 certificate correlates the notifier (which you will use to send notification messages from App Services) with the App ID (so that APNs will forward your notifications to devices).
+
+B. A run time, your app's code registers with Apple for notifications by invoking the registerForRemoteNotificationTypes method to receive a token it can send to App Services.
+
+C. At run time, your app's code registers with App Services for notifications by sending the name of the App Services notifier you created. This ensure's that there's a device entity in your App Service application. That way, you can address the device with notification messages.
+
+For information on troubleshooting push notifications on iOS devices, see Troubleshooting Push Notifications
+
+### Google GCM
+
+Google GCM
+The diagram below illustrates what things should look like once you've gotten set up to send notifications that are received by your app.
+
+A. At configuration time, you create a Google API project, then create an App Services notifier with an API key from the project. The API key correlates the notifier (which you will use to send notification messages from App Services) with the API project (which will forward your notifications to devices).
+
+B. At run time, your app's code registers with App Services for notifications by sending the name of the App Services notifier you created. This ensure's that there's a device entity in your App Service application. That way, you can address the device with notification messages.
+
+C. A run time, your app's code registers with Google for notifications by sending the number of your API project as a "sender ID". The project is the actual notification "sender" that will forward notifications to your app. In other words, the app is telling Google that it wants to receive notifications from that sender.
+
+
+
+## Requirements
+Before you start adding support for push notifications, be sure you've got the following:
+
+An Apigee account (it’s free). If you don't yet have an Apigee account, you can create one. 
+An App Services organization. Organizations are top-level containers for your APIs and other resources. By default, your Apigee account will include one organization that has the same name as your username. You can view your current organizations or create a new one by visiting your account dashboard.
+An App Services application. An App Services application is where you store you App Services data and where you schedule notifications. Data in the application represents devices, notifiers, notifications, users, and groups. For information on creating an app, see Registering apps.
+You will need to test with a mobile device running the platform you're developer for. In the case of Android, you might be able to use an emulator. It is not possible to test push notifications from a web browser.
+
+### iOS
+To develop push notifications for an iOS app, you'll need:
+
+A Mac to generate the necessary SSL certificate.
+An iOS developer account. You'll need this to register for an App ID and get a provisioning profile. To get an account, visit the iOS Dev Center.
+An actual iOS device to test push notifications. It's not yet possible to develop push notifications with an emulator.
+An iOS provisioning profile
+For iOS app testing, you need a provisioning profile that's associated with an Apple ID. You set up the provisioning profile in the Apple developer portal, download the profile, and import it into Xcode.
+
+To set up a provisioning profile, you need to create an "iOS App Development" certificate in the Apple developer portal. For example, in the Apple APNs setup earlier in this tutorial, you created a certificate in the Apple developer portal to be used for push notifications. However, you won't be able to create a provisioning portal with just that certificate. You also need to create an "iOS App Development" certificate (the configuration settings don't matter), as shown in the following image.
+
+ios dev certificate
+
+After you create an iOS App Development certificate, you can create a provisioning profile that includes your App ID/certificate for push notifications.
+
+### Android
+
+It's generally a best practice to develop Android apps by testing and debugging with an Android device. It's also possible to use an emulator.
+
+Before testing and debugging with an Android device, you'll need to set up your device for development. Be sure to see the Android documentation on using hardware devices.
+
+To test with an emulator, you will need to follow these steps:
+
+Ensure that you have Google API 8 (or above) and Android 2.2 (or above).
+Using the Android SDK Manager, install Google Cloud Messaging for Android Library.
+Using the Android Virtual Device Manager, create an emulator whose target is Google APIs.
+Ensure that the emulator you're using includes a Google account.
+Launch the emulator.
+In the emulator, click the Menu button, then go to Settings > Accounts & Sync.
+Add a Google account.
+Once you've finished these steps, you should have an emulator that can receive push notification messages.
+
+### PhoneGap
+
+You'll need to test with a device or emulator. It is not possible to test push notifications with a browser alone.
+PhoneGap Push plug-in. Developers using PhoneGap to develop their apps with HTML5 and Javascript will need to install the Apigee push notification PhoneGap plug-in to enable push notifications. Installation instructions are available in the plug-in Readme.md file, as well as in Tutorial: Push notifications sample app. The plug-in is already included in the above PhoneGap sample apps.
+
+## Tutorials
+Written tutorial
+For a full step-by-step tutorial using iOS, Android, or JavaScript, see Tutorial: Push notifications sample app.
+
+Video tutorial
+Click the tab for your preferred development platform to watch a full walkthrough video about how to integrate the App Services push notifications feature into your app.
+
+### iOS
+
+### Android
+
+## Sample Apps
+
+You'll find samples in SDKs that are specific to three mobile platforms: iOS, Android, and JavaScript. These show a simple implementation of push notifications in action. After you perform a few setup steps, running the sample app on your connected device or emulator, you will be able to send a push notification to it by clicking a button in the app's UI. You will also be able to send more pushes to it from the App Services console.
+
+To download the sample app and view the tutorial, see Tutorial: Push notifications sample app.
+
+When you create notifiers to run the samples, creating them in the default "sandbox" app in your Usergrid organization will make it easier to try out the feature. The sandbox app doesn't require authentication.
+
+## Troubleshooting
+
+### Android / PhoneGap
+
+App fails to install on the emulator
+When using the emulator, be sure to note the setup steps in the requirements section.
+
+Sometimes installation fails while the emulator is still being launched. Wait until the emulator is up and running (so that you can unlock and interact with the UI), then run the project again.
+
+Make sure that the order of your Java Build Path matches the order shown in Tutorial: Push notifications sample app.
+
+#### Push errors
+If pressing the button to send yourself a push throws an exception or doesn't respond:
+
+Make sure the emulator's target matches the Google API version used in the project.
+
+In the IDE log, wait until you see that the device has been registered before sending yourself a push.
+Sometimes waiting for the code to run and trying another click gets the push message to you.
+
+If you successfully send yourself a push message once but fail to again, try one of the following:
+
+Go to the apps list on the device and launch the app from there.
+
+Uninstall the app from the device, delete the device in the App Services console, and run the project again.
+
+#### MismatchSenderId error message from the server when it tries to send a message to your app.
+
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The error might be occurring because the sender ID with which your app is registering at GCM for notifications does not correlate to the API project whose API key was used to create your App Services notifier. First, confirm the following:
+
+* The sender ID in your app code (used when registering with GCM) is the same as your Goole API project number.
+
+* The API key used to create your App Services notifier is the same as the API key in your Google API project.
+
+* The notifier name used in your app code is the same as for the notifier you created in App Services.
+
+It can be possible to make a fix (such as by correcting the sender ID in your app code) and still see this error. If you're still seeing the error, consider create a new API project and App Services notifier, then use their new values in your code:
+
+1. Recreate (or create anew) the Google API project. This will generate a new API key and project number. See Registering with a notification service.
+
+2. Create a new App Services notifier for GCM using the API key you generated with the new API project. See Creating notifiers.
+
+3. Use the new notifier name in your code, along with a new sender ID that is that same value as the Google API project number.
+
+#### INVALID_SENDER error message
+
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The "sender" in this case is the Google API project you created to send notification messages. Confirm that the sender ID you're using in code is the same value as the API project number generated when you created your Google API project. See Registering with a notification service.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/creating-and-managing-notifications.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/creating-and-managing-notifications.txt b/content/docs/_sources/push-notifications/creating-and-managing-notifications.txt
new file mode 100644
index 0000000..72a2021
--- /dev/null
+++ b/content/docs/_sources/push-notifications/creating-and-managing-notifications.txt
@@ -0,0 +1,269 @@
+# Creating and managing notifications
+This topic provides information on setting up and sending push notifications with the Usergrid API backend as a service (BaaS). For high-level information, prerequisites, and tutorials, see [Push notifications overview](overview.html).
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+Although not shown in many of the API examples below, you need to provide a valid access token with each API call. See [Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details.
+</p></div>
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For an overview of how to set up push notifications, including troubleshooting tips, see [Adding push notifications support](adding-push-support.html).
+</p></div>
+
+## Creating notifications
+When you create a notification, it is scheduled to be delivered to all applicable devices immediately unless the deliver property has been set. A notification may contain multiple messages (payloads), and each payload must be associated with a notifier in order to deliver that message to the associated app. This allows a single notification to be delivered to multiple apps across various services, and is useful if you want to send messages to multiple notifiers, such as development and production versions of both Apple and Google simultaneously.
+
+Notification can be created via POST request to the BaaS API, or in the admin portal:
+
+### Creating notificastions with cURL
+
+#### Targeting a single device
+This request will target a specific device entity.
+
+Request Syntax
+
+    curl -X POST https://api.usergrid.com/<org>/<app>/devices/<device_ID>/notifications -d '{"payloads":{<notifier>:<message>}}'
+		
+#### Targeting all devices
+This request will target all device entities.
+
+Request Syntax
+
+    curl -X POST https://api.usergrid.com/<org>/<app>/devices/*/notifications -d '{"payloads":{<notifier>:<message>}}'
+		
+#### Targeting a single user
+This request will target a specific user entity.
+
+Request Syntax
+
+    curl -X POST https://api.usergrid.com/<org>/<app>/users/<username>/notifications -d '{"payloads":{<notifier>:<message>}}'
+		
+#### Targeting a group
+This request will target all users associated with a specific group entity.
+
+Request Syntax
+
+    curl -X POST https://api.usergrid.com/<org>/<app>/groups/<group_path>/notifications -d '{"payloads":{<notifier>:<message>}}'
+		
+#### Targeting users by location
+This request will target all device entities that are within a set radius of a latitude/longitude coordinate.
+
+Request Syntax
+
+    curl -X POST https://api.usergrid.com/<org>/<app>/devices;ql=location within <radius> of <lat>,<long>/notifications -d '{"payloads":{<notifier>:<message>}}'
+		
+#### Request Parameters
+
+The following parameters can be specified when targeting push notifications.
+
+Base URL
+
+These parameters are used in forming the base URL of the request:
+
+Parameter	Description
+---------   -----------
+org	        Organization UUID or organization name
+app	        Application UUID or application name
+
+Notification
+
+These parameters are used when forming the notification portion of the request:
+
+Parameter	Description
+---------   -----------
+notifier	The ``notifier`` entity you wish to associate with the notification (see [Creating notifiers](creating-notifiers.html) for information on creating notifiers)
+message	    The push notification message that will be delivered to the user
+
+__Note__: If your message contains double-quotes ("") you must escape them with a backslash
+
+Targets
+
+These parameters are used when specifying the notification target in the request.
+
+Parameter	                    Description
+---------                       -----------
+device	                        UUID of a device entity.
+user	                        UUID or username of a user entity.
+phone_type	                    Specified in a appended query string. The type property of a device entity.
+group	                        UUID or name of the group entity.
+latitude, longitude, radius 	Specified in a appended query string. The radius in meters of a user device from a latitude/longitude coordinate.
+
+
+### Creating notificastions with Admin portal
+
+To create the new notification with the admin portal, do the following:
+
+1. Log in to the admin portal.
+2. In the left nav, click __Push > Send Notification__.
+3. From the __Notifier__ drop-down, select the appropriate notifier.
+4. Under the notifier name, select one of the following to specify where your notification message should go:
+
+* __All Devices__ to have the message sent to all devices.
+* __Devices__ to have the message sent to a particular subset of devices. Enter a comma-separated list of device UUIDs in the box provided.
+* __Users__ to have the message sent to a particular subset of users. Enter a comma-separated list of username values in the box provided.
+* __Groups__ to have the message sent to a particular subset of user groups. Enter a comma-separated list of group paths in the box provided.
+
+5. In the __Notifier Message__ field, enter the message (payload) you want delivered.
+6. If double-quotes are included in your message, you must escape them with a backslash.
+7, Under __Delivery__, select one of the following to specify when the notification should be delivered:
+
+* __Now__ to have the message delivered immediately.
+* Schedule for later to choose a date and time at which the message should be delivered.
+
+7. Click __Submit__.
+
+To create a notification to send multiple messages or target multiple platforms, see the cURL syntax for creating notifications.
+
+### Creating notificastions with iOS
+
+To send notifications from iOS app code, you use the 11ApigeeAPSDestination11 and ``ApigeeAPSPayload`` classes.
+
+With ``ApigeeAPSDestination``, you specify where the notification should go (a particular user or device or user group, for example). With ``ApigeeAPSPayload``, you specify the contents of the message, including any alert text, sound, or badge (items specified by Apple as allowable notification content types). You then use ``ApigeeDataClient`` to send the message via Apigee and Apple APNs.
+
+The following code illustrates how to send a notification to a single user. Though this is the device on which the app itself is installed, you can imagine how you might send a notification to another device, such as one belonging to someone "following" this user. For more, see the iOS push sample application included with the [Apigee iOS SDK](../sdks/tbd.html).
+
+    - (void)sendMyselfAPushNotification:(NSString *)message
+    completionHandler:(ApigeeDataClientCompletionHandler)completionHandler
+    {
+        // send to a single device -- our own device
+        NSString *deviceId = [ApigeeDataClient getUniqueDeviceID];
+        ApigeeAPSDestination* destination =
+            [ApigeeAPSDestination destinationSingleDevice:deviceId];
+        
+        // set our APS payload
+        ApigeeAPSPayload* apsPayload = [[ApigeeAPSPayload alloc] init];
+        apsPayload.sound = kBundledSoundNameWithExt;
+        apsPayload.alertText = message;
+        
+        // Example of what a custom payload might look like -- remember that
+        // APNS payloads are limited to a maximum of 256 bytes (for the entire
+        // payload -- including the 'aps' part)
+        NSMutableDictionary* customPayload = [[NSMutableDictionary alloc] init];
+        [customPayload setValue:@"72" forKey:@"degrees"];
+        [customPayload setValue:@"3" forKey:@"newOrders"];
+        
+        __weak AppDelegate* weakSelf = self;
+        
+        // send the push notification
+        [dataClient pushAlert:apsPayload
+                customPayload:customPayload
+                  destination:destination
+                usingNotifier:notifier
+            completionHandler:^(ApigeeClientResponse *response) {
+                if ( ! [response completedSuccessfully]) {
+                    [weakSelf alert:response.rawResponse
+                              title: @"Error"];
+                }
+                
+                if (completionHandler) {
+                    completionHandler(response);
+                }
+            }];
+    }
+
+## Scheduling notifications
+
+### cURL
+
+To schedule a notification for a later time, add the deliver parameter with a UNIX timestamp to the body of your request.
+
+Request body syntax
+
+    '{"deliver":<unix_timestamp>,"payloads":{<notifier>:<message>}}'
+
+## Targeting multiple notifiers or messages
+To send multiple messages or target multiple platforms with a single notification entity, include multiple notifier-message pairs as a comma-separated list in the payloads object of the request body:
+
+Request body syntax
+
+    '{"payloads":{<notifier>:<message>, <notifier>:<message>, ...}}'
+		
+## Setting a notification expiration
+If a push service can't deliver a message to a device and needs to resend it (for example, if the device is turned off), you can set a notification to expire after a certain date/time.
+
+To do this, adding the expire parameter with a UNIX timestamp to your request body. This specifies when the service should stop trying to send the notification.
+
+<div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">

+Please note that if the expire property is not set and Apple APNS or Google GCM are not able to immediately deliver your push notification, delivery will not be retried. This means your notification will not be delivered. As a best practice, you should always set an expire timestamp to ensure your notification is delivered in the event the delivery initially fails.
+</p></div>
+
+Request body syntax
+
+    '{"expire":<unix_timestamp>,"payloads":{"<notifier_name>":"<message>"}}'
+
+
+## Getting notifications
+
+### cURL
+
+The following are endpoints can be used to get notifications. For details on the notification properties you can get, see Notifier, Receipt, and Notification.
+
+Getting one or more notifications:
+
+    /notifications
+    
+Getting notifications associated with one or more receipts:
+
+    /receipts/*/notification
+    
+Getting the list of devices associated with one or more notifications before the notifications are sent:
+
+    /notifications/*/queue
+    
+## Canceling sent notifications
+
+You can cancel a notification that's already in progress by doing the following:
+
+    curl -X PUT "https://api.usergrid.com/my-org/sandbox/notifications/<notification-uuid>" -d '{"canceled": true}'
+
+### Admin portal
+
+You can view JSON for notifications by viewing their entity entries in the Data section of your application.
+
+In the admin portal, click Data, then click the __/notifications__ collection.
+You can also view notification data in the message history.
+
+In the admin portal, click Push, then click Message History.
+Locate the notification for which you want to view data, then click its view details link.
+
+## Deleting unsent notifications
+
+### Deleting unsent notifications with cURL
+
+    curl -X DELETE "https://api.usergrid.com/<you-org>/<app>/notifications/<notification-uuid>"  
+
+### Deleting unsent notifications with Admin Portal
+
+1. In the admin portal, click Push, then Message History.
+2. On the Message History page, click Scheduled.
+3. In the list of scheduled messages, locate the message you want to delete.
+4. In the top area of the message item, click the delete link.
+
+## Getting receipts
+After sending a notification, the BaaS generates a receipt entity that contains details about the notification. Receipts show details such as timestamps, payloads sent, and the receipt endpoints.
+
+For information about what's contained in a receipt, see [Notifier](..//rest-endpoints/api-docs.html#notifier), [Receipt](..//rest-endpoints/api-docs.html#receipt), and [Notification](..//rest-endpoints/api-docs.html#notification). Use the following endpoints to get receipts.
+
+To get one or more receipts:
+
+    /receipts
+    
+To get receipts associated with one or more devices:
+
+    /devices/*/receipts
+    
+To get receipts for one or more notifications. For example, get receipts for notifications that had errors.
+
+    /notifications/*/receipts
+
+## Notification endpoints
+The ``/notifications`` endpoints let you create, schedule, cancel, and delete notifications. You can also use the following endpoints to accomplish the same actions for specific groups, users, devices, or any combination thereof.
+
+Base URL: ``https://api.usergrid.com/my-org/my-app``
+
+    /groups/*/notifications
+    /groups/*/users/*/notifications
+    /groups/*/users/*/devices/*/notifications
+    /users/*/notifications
+    /users/*/devices/*/notifications
+    /devices/*/notifications
+    
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/creating-notifiers.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/creating-notifiers.txt b/content/docs/_sources/push-notifications/creating-notifiers.txt
new file mode 100644
index 0000000..9e07176
--- /dev/null
+++ b/content/docs/_sources/push-notifications/creating-notifiers.txt
@@ -0,0 +1,69 @@
+# Creating notifiers
+When you request that a push notification be sent to your app on devices, an Usergrid notifier carries the request to the notification service (Google GCM or Apple APNs).
+
+A notifier is represented by an entity in your Usergrid application (see the [API Docs](../rest-endpoints/api-docs.html) for reference information). It carries the credentials that authorize your request. Once a notification service has verified that your notifier contains valid credentials, it will forward your push notification to your app on devices.
+
+You can create a notifier in two ways: using the admin portal and programmatically.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For an overview of how to set up push notifications, including troubleshooting tips, see [Adding push notifications support](adding-push-support.html).
+</p></div>
+
+## Requirements
+To create a notifier, you must first register your app with the appropriate notification service, as described in [Registering with a notification service](registration.html).
+
+## Creating notifiers with the admin portal
+To create a notifier with the admin portal, do the following:
+
+1. Log in to the admin portal.
+2. In the left nav, select __Push > Configuration__.
+3. Click the __Apple__ or __Android__ tab.
+4. If you have not already done so, retrieve your .p12 certificate (iOS apps) or API key (Android apps) by following the steps in the [Registering with a notification service](registration.html).
+5. In the admin portal's Configuration page, enter values for the platform on which your mobile app will be installed.
+
+The fields are different depending on whether you are on the Apple or Android tab:
+
+__Fields for Apple__
+
+<table class="usergrid-table">
+<tr><td>Name this notifier</td>	<td>Enter a unique name that can be used to identify this notifiers.</td></tr>
+<tr><td>Certificate</td>	<td>Click __Choose File__ to select the .p12 certificate you generated and saved to your desktop earlier in this tutorial.</td></tr>
+<tr><td>Environment</td>	<td>Select the environment appropriate to your app. You may select development or production. Note that for the environment you select, you should have a separate .p12 certificate -- different certificates for development and production.</td></tr>
+<tr><td>Certificate Password</td>	
+<td>Enter a certificate password if one was specified when you created your .p12 certificate.</td></tr>
+</table>
+
+__Fields for Android__  
+
+<table class="usergrid-table">
+<tr><td>Name this notifier</td>	<td>Enter a unique name that can be used to identify this notifiers.</td></tr>
+<tr><td>API Key</td>	
+<td>Enter the API key that was generated when you registered your app with GCM. To retrieve your API key, go to the [Google API developer web site](https://code.google.com/apis/console/), then select __APIs & Auth > Credentials__.</td></tr>
+</table>
+
+6. Click __Create Notifier__. The Usergrid will create a notifier entity in the /notifiers collection. The notifier will also appear in the list of notifiers in the notifications console. 
+
+## Creating notifiers programmatically
+You can create an App BaaS notifier programmatically by sending requests to the Usergrid API.
+
+### For Apple
+
+    curl -X POST -i -H "Accept: application/json" -H "Accept-Encoding: gzip, deflate" -H "Authorization: Bearer YWMtFeeWEMyNEeKtbNX3o4PU0QAAAT8vzK3xz3utVZat0CosiYm75C2qpiGT79c" -F "name=applenotifier" -F "provider=apple" -F "environment=development" -F "p12Certificate=@/Users/me/dev/pushtest_dev.p12" 'https://api.usergrid.com/my-org/my-app/notifiers'
+
+### For Google
+
+    curl -X POST "https://api.usergrid.com/my-org/my-app/notifiers" -d '{"name":"androiddev", "provider":"google", "apiKey":"AIzaSyCkXOtBQ7A9GoJsSLqZlod_YjEfxxxxxxx"}'
+
+## Notifier endpoints
+
+The following are the available notifier endpoints. For details on notifier properties, see the [API Docs](../rest-endpoints/api-docs.html). 
+
+Base URL: ``https://api.usergrid.com/my-org/my-app/``
+
+Working with one or more notifiers:
+
+    /notifiers
+    
+Working with notifiers associated with specific devices:
+
+    /devices/{device-id}/notifier

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/getting-started.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/getting-started.txt b/content/docs/_sources/push-notifications/getting-started.txt
new file mode 100644
index 0000000..6f1b80f
--- /dev/null
+++ b/content/docs/_sources/push-notifications/getting-started.txt
@@ -0,0 +1,102 @@
+# Getting started with push notifications
+
+## What are push notifications?
+Usergrid provides a RESTful framework for sending push notifications to your apps, giving you full control over which app users you target, as well as when you send notifications. You can send messages to devices, users, or groups that have specific characteristics and locations. (To receive push notifications, users must be using devices that can connect to the Usergrid). Here are just a couple reasons for enabling push notification support in your app with Usergrid:
+
+* __Reach your app's users__ with messages they care about. This could be a flash sale happening near them right now (use [geolocation](../geolocation/geolocation.html)!) or a lunch special at a favorite restaurant. You could even let a user know it's her turn in a game she's playing with a friend.
+* __Keep your app footprint low__ while communicating in a high-value way with your app's users. Compare pushing data with CPU- and memory-heavy pull processes. In those, an app actively listens on an endpoint, regularly pulling data (such as news feeds, new emails, or stock market updates) to the device.
+
+<center>
+<iframe allowfullscreen="" frameborder="0" height="315" src="http://www.youtube.com/embed/W560tZ5fSIc" width="560"></iframe>
+</center>
+
+<p></p>
+
+## Prerequisites
+You will need to test with a mobile device running the platform you're developer for. In the case of Android, you might be able to use an emulator. It is not possible to test push notifications from a web browser.
+
+### iOS Prerequisites
+To develop push notifications for an iOS app, you'll need:
+
+* A Mac to generate the necessary SSL certificate.
+* An iOS developer account. You'll need this to register for an App ID and get a provisioning profile. To get an account, visit the [iOS Dev Center](https://developer.apple.com/ios/download/).
+* An actual iOS device to test push notifications. It's not yet possible to develop push notifications with an emulator.
+* An iOS provisioning profile
+For iOS app testing, you need a provisioning profile that's associated with an Apple ID. You set up the provisioning profile in the Apple developer portal, download the profile, and import it into Xcode.
+
+To set up a provisioning profile, you need to create an "iOS App Development" certificate in the Apple developer portal. For example, in the Apple APNs setup earlier in this tutorial, you created a certificate in the Apple developer portal to be used for push notifications. However, you won't be able to create a provisioning portal with just that certificate. You also need to create an "iOS App Development" certificate (the configuration settings don't matter), as shown in the following image.
+
+.. image:: ios-cert.png 
+
+After you create an iOS App Development certificate, you can create a provisioning profile that includes your App ID/certificate for push notifications.
+
+### Android Prerequisites
+
+It's generally a best practice to develop Android apps by testing and debugging with an Android device. It's also possible to use an emulator.
+
+Before testing and debugging with an Android device, you'll need to set up your device for development. Be sure to see the Android documentation on [using hardware devices](http://developer.android.com/tools/device.html).
+
+To test with an emulator, you will need to follow these steps:
+
+1. Ensure that you have Google API 8 (or above) and Android 2.2 (or above).
+2. Using the Android SDK Manager, install Google Cloud Messaging for Android Library.
+3. Using the Android Virtual Device Manager, create an emulator whose target is Google APIs.
+4. Ensure that the emulator you're using includes a Google account.
+
+Next:
+
+* Launch the emulator.
+* In the emulator, click the Menu button, then go to Settings > Accounts & Sync.
+* Add a Google account.
+* Once you've finished these steps, you should have an emulator that can receive push notification messages.
+
+### PhoneGap Prerequisites
+
+You'll need to test with a device or emulator. It is not possible to test push notifications with a browser alone.
+
+## Setup overview
+The following steps get you set up so that your app can receive push notifications. Keep in mind that these steps build on one another. In other words, you'll need values generated in step 1 in order to complete step 2, and so on.
+
+For a walkthrough of these steps using a push sample app, see Tutorial: Push notifications sample app.
+
+1. __Register__ your app with push notification services. Your notification messages will be forwarded to devices by Apple and/or Google. So you'll need to register with Apple APNs and/or Google's GCM. For more information, see Registering with a notification service.
+
+2. __Create a notifier__ to send notification messages from the Usergrid to notification services.
+The Usergrid will use your notifier to send your messages to a notification service. For details, see Creating notifiers. To create a notifier, you'll need information generated by registering with a push notification service. You'll need a separate notifier for each app/platform combination.
+
+3. __Register devices at run time__.
+At run time, your code will register to receive notifications. To do this, your code uses information from the notification service and your notifier. For more, see Managing users and devices.
+
+4. __Send and manage push notifications__.
+You use Usergrid API notification endpoints to target devices, users, or groups with your messages. To learn more, see Creating and managing notifications.
+
+
+## How it works
+Click a tab below to view more information about how the pieces connect once you've got it set up.
+
+### Apple APNs
+
+The diagram below illustrates what things should look like once you've gotten set up to send notifications that are received by your app.
+
+__A.__ At configuration time, you [create an App ID](registering.html), then [create a notifier](creating-notifiers.html) with a .p12 certificate you generate on your Mac. The .p12 certificate correlates the notifier (which you will use to send notification messages) with the App ID (so that APNs will forward your notifications to devices).
+
+__B.__ A run time, your app's code [registers with Apple for notifications](managing-users-and-devices.html) by invoking the ``registerForRemoteNotificationTypes`` method to receive a token it can send to Usergrid.
+
+__C.__ At run time, your app's code [registers with the Usergrid for notifications](managing-users-and-devices.html) by sending the name of the notifier you created. This ensure's that there's a device entity in your Usergrid application. That way, you can address the device with notification messages.
+
+.. image:: pushmiddleios0.png
+
+__Note__: For information on troubleshooting push notifications on iOS devices, see [Troubleshooting Push Notifications](troubleshooting.html)
+
+### Google GCM
+
+The diagram below illustrates what things should look like once you've gotten set up to send notifications that are received by your app.
+
+__A.__ At configuration time, you [create a Google API project](registering.html)), then [create an Usergrid notifier](creating-notifiers.html) with an API key from the project. The API key correlates the notifier (which you will use to send notification messages from the Usergrid) with the API project (which will forward your notifications to devices).
+
+__B.__ At run time, your app's code [registers with the Usergrid](managing-users-and-devices.html)) for notifications by sending the name of the notifier you created. This ensure's that there's a device entity in your Usergrid application. That way, you can address the device with notification messages.
+
+__C.__ A run time, your app's code [registers with Google for notifications](managing-users-and-devices.html)) by sending the number of your API project as a "sender ID". The project is the actual notification "sender" that will forward notifications to your app. In other words, the app is telling Google that it wants to receive notifications from that sender.
+
+.. image:: pushmiddleandroid0.png
+ 
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/managing-users-and-devices.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/managing-users-and-devices.txt b/content/docs/_sources/push-notifications/managing-users-and-devices.txt
new file mode 100644
index 0000000..4f04f9a
--- /dev/null
+++ b/content/docs/_sources/push-notifications/managing-users-and-devices.txt
@@ -0,0 +1,313 @@
+# Managing users and devices
+Before your app can receive notifications on a user's device, the app's code will need to register the device with both the Usergrid and the appropriate push notification service (Apple APNs or Google GCM).
+
+By registering with the Usergrid, your app adds the device on which it is installed to your data store. The device is represented as a Device entity. This makes it possible for you to target that device when sending notifications. (For more on the Device entity, see the [API Docs](../rest-endpoints/api-docs.html).) Any devices, users, and groups that have been registered in this way may be targeted with push notifications.
+
+By registering with the notification service, you make the device known to the service. This way, the service can forward your notifications to the device.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For an overview of how to set up push notifications, including troubleshooting tips, see [Adding push notifications support](adding-push-support.html).
+</p></div>
+
+## Registering devices
+The following samples illustrate how to register a device with a notification service and with the Usergrid. At a high level, your code will send a registration request to the notification service, then use information in the service's response to send a separate request to the Usergrid. The two requests correlate the notification service, Usergrid, and your mobile app.
+
+You can also create device entities separately by using the /devices endpoint. For more information on using the ``/devices`` endpoint in the Usergrid, see the [API Docs](../rest-endpoints/api-docs.html).
+
+Registering a device with a notification service is a standard coding activity for implementing push notifications. This is not specific to the Usergrid.
+
+
+### Registering for iOS
+
+The following code illustrates how you can use the iOS SDK to register a device with both the Usergrid server and with the APNs, the Apple push notification service. This example assumes that your code has already property initialized the SDK. For more information, see [Installing the Apigee SDK for iOS](../sdks/tbd.html).
+
+    // Register with Apple to receive notifications.
+
+    // Invoked when the application moves from an inactive to active state. Use this
+    // method to register with Apple for notifications.
+    - (void)applicationDidBecomeActive:(UIApplication *)application
+    {
+        // Find out what notification types the user has enabled.
+        UIRemoteNotificationType enabledTypes =
+            [application enabledRemoteNotificationTypes];
+
+        // If the user has enabled alert or sound notifications, then
+        // register for those notification types from Apple.
+        if (enabledTypes & (UIRemoteNotificationTypeAlert|UIRemoteNotificationTypeSound)) {
+            
+            // Register for push notifications with Apple
+            NSLog(@"registering for remote notifications");
+            [application registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert |
+             UIRemoteNotificationTypeSound];
+        }
+    }
+
+    // Invoked as a callback from calling registerForRemoteNotificationTypes. 
+    // newDeviceToken is a token received from registering with Apple APNs.
+    // Use this method to register with Apigee.
+    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)newDeviceToken
+    {
+        // Register device token with the Usergrid (will create the Device entity if it doesn't exist)
+        // Sends the name of the notifier you created with Apigee, along with the token your code
+        // received from Apple.
+        ApigeeClientResponse *response = [dataClient setDevicePushToken: newDeviceToken
+                                                            forNotifier: notifier];
+        
+        if ( ! [response completedSuccessfully]) {
+            [self alert: response.rawResponse title: @"Error"];
+        }
+    }
+
+    // Invoked as a callback from calling registerForRemoteNotificationTypes if registration 
+    // failed.
+    - (void)application:(UIApplication*)application didFailToRegisterForRemoteNotificationsWithError:(NSError*)error
+    {
+        [self alert: error.localizedDescription title: @"Error"];
+    }
+
+Initialize the Apigee client and check for notifications that might have been sent while the app was off.
+
+    // Invoked as a callback after the application launches.
+    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+    {
+        // Connect and login
+        ApigeeClient *apigeeClient =
+            [[ApigeeClient alloc] initWithOrganizationId:orgName
+                                           applicationId:appName
+                                                 baseURL:baseURL];
+        dataClient = [apigeeClient dataClient];
+        [dataClient setLogging:true]; //comment out to remove debug output from the console window
+
+        // Find out if there's a notification waiting to be handled after the
+        // app launches.
+        if (launchOptions != nil) {
+            NSDictionary* userInfo =
+                [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
+            
+            // If there's notification data waiting, send it to be processed.
+            if (userInfo) {
+                [self handlePushNotification:userInfo
+                              forApplication:application];
+            }
+        }
+        
+        // It's not necessary to explicitly login if the Guest role allows access.
+        // But this is how you can do it.
+    //    [apigeeClient logInUser: userName password: password];
+
+        NSLog(@"done launching");
+        return YES;
+    }
+
+### Registering for Android
+
+The following code illustrates how to register a client device with GCM, register the device with Apigee, and associate the device with the user. Methods used in this code are defined in the Apigee Android SDK. For more information on downloading and installing the SDK, see Installing the Apigee SDK for Android.
+
+    import android.content.Context;
+    import com.google.android.gcm.GCMRegistrar;
+    import com.apigee.sdk.ApigeeClient;
+    import com.apigee.sdk.data.client.entities.Device;
+
+    /**
+     * Registers this device with GCM, Google's messaging 
+     * service.
+     *
+     * @param context An Android context with information specific to this 
+     * application's context on the device.
+     */
+    static void registerPush(Context context) {
+        
+        //Get an instance of the Apigee DataClient class from the ApigeeClient object
+        dataClient = getClient().getDataClient();
+        
+        // Get the registration ID (GCM API key) for this application.
+        final String regId = GCMRegistrar.getRegistrationId(context);
+
+        // If this device isn't already registered with GCM, register it
+        // using the the application context and an ID for the Google account
+        // authorized to send messages to this application. This is the 
+        // Google Client ID from Google API Console.
+        if ("".equals(regId)) {
+          GCMRegistrar.register(context, gcmSenderId);
+        } else {
+            if (GCMRegistrar.isRegisteredOnServer(context)) {
+                Log.i(TAG, "Already registered with GCM");
+            } else {
+            
+            // Use an instance of the Client class (SDK for Android) 
+            // to register this device with the Usergrid. Pass as arguments
+            // the device unique identifier, the unique name of the notifier you
+            // created in the Usergrid, the GCM API key, and a callback that will
+            // receive an instance of a Device class representing the registered
+            // device on the system.
+            dataClient.registerDeviceForPushAsync(dataClient.getUniqueDeviceID(), notifierName, regId, null, 
+                new DeviceRegistrationCallback() {        
+                    @Override
+                    public void onResponse(Device device) {                
+                        AppServices.device = device;
+
+                        // Associate the logged in user with this device.
+                        if (dataClient.getLoggedInUser() != null) {
+                            dataClient.connectEntitiesAsync("users", 
+                                dataClient.getLoggedInUser().getUuid().toString(),
+                                "devices", device.getUuid().toString(),
+                                new ApiResponseCallback() {
+                                    @Override
+                                    public void onResponse(ApiResponse apiResponse) {
+                                      Log.i(TAG, "connect response: " + apiResponse);
+                                    }
+                        
+                                    @Override
+                                    public void onException(Exception e) {
+                                      displayMessage(context, "Connect Exception: " + e);
+                                      Log.i(TAG, "connect exception: " + e);
+                                    }
+                            });
+                        }
+                    }
+            
+                });
+            }
+        }
+    }
+
+    /**
+     * Create an instance of the SDK ApigeeClient class, setting
+     * values from your Apigee registration.
+     */
+    static synchronized ApigeeClient getClient() {
+        if (client == null) {
+            client = new ApigeeClient();
+            client.setApiUrl("https://api.usergrid.com");
+            client.setOrganizationId("your-org");
+            client.setApplicationId("your-app");
+        }
+        return client;
+    }
+
+
+### Registering for HTML5/PhoneGap
+
+The following code illustrates how you can use the JavaScript functions included with the PhoneGap plugin to register a device with both the Apigee server and with the APNs, the Apple push notification service.
+
+    // Declare a variable for calling push notification APIs.
+    var pushNotification = window.plugins.pushNotification;
+    // Collect configuration options to specify that this device accepts
+    // an alert message, an application badge, and a sound.
+    var appleOptions = {
+        alert:true, badge:true, sound:true
+    };
+    // Register the device with the Usergrid, passing options for configuration 
+    // along with a callback from which you can retrieve the device token
+    // sent by Apigee.
+    pushNotification.registerDevice(appleOptions, function(status) {
+        console.log(status);
+        // If a token was received, bundle options to pass when registering the device 
+        // with the push notification service. The provider value must be "apigee" to
+        // support push notification through Apigee. orgName and appName should be 
+        // values corresponding to those used in your Apigee account.
+        // notifier is the unique name you associated with the Apigee notifier you created.
+        // token is the device token this code received from Apigee after registering the 
+        // device.
+        if(status.deviceToken) {
+            var options = {
+                "provider":"apigee",
+                "orgName":"YOUR APIGEE.COM USERNAME",
+                "appName":"sandbox",
+                "notifier":"YOUR NOTIFIER",
+                "token":status.deviceToken
+            };
+
+            // Use the device token and other options to register this device with the 
+            // push notification provider.
+            pushNotification.registerWithPushProvider(options, function(status){
+                console.log(status);
+            });
+        }
+    });
+    
+The functions used in this code are defined in the PhoneGap plugin. JavaScript functions invoke underlying Objective-C or Java code (depending on platform). You'll find that code in these files, included in the Apigee PhoneGap push notification plug-in.
+
+Information about installing the plugin is available in its Readme file. For more complete examples, see [Tutorial: Push notifications sample app](tutorial.html).
+
+
+## Connecting devices to users
+You can associate user entities with device entities in the Usergrid. Doing so allows you to target your push notifications at users with specific characteristics. The following describes how to connect a user to a specific device in the Usergrid.
+
+For more information on creating a device in your Usergrid data store, see "Registering Devices" above.
+
+For more information on creating a user in your Usergrid data store, see [User](../rest-endpoints/api-docs.html#user).
+
+The following code examples all use the same basic endpoint pattern for connecting devices with users:
+
+    POST /users/{userUUID or name}/devices/{deviceUUID}
+    
+### Connecting with curl
+The following call connects user "joex" with device 7a0a1cba-9a18-3bee-8ae3-4f511f12a386 (the device UUID). After this connection, you can send a push notification to joex rather than the device. Further, if joex has specific properties set--such as {"favoritecolor": "blue"}--you can send a push notification to all users whose favorite color is blue (assuming they're connected to devices in the Usergrid).
+
+    curl -X POST "https://api.usergrid.com/my-org/sandbox/users/joex/devices/7a0a1cba-9a18-3bee-8ae3-4f511f12a386"
+
+### Connecting with iOS
+
+The following sample code, taken from AppDelegate.m in the native iOS push sample, uses the connectEntities method from the iOS SDK to connect a device to a user.
+
+    ApigeeClientResponse *response = [dataClient setDevicePushToken: newDeviceToken forNotifier: notifier];
+
+    // You could use this if you log in as an Usergrid user to associate the Device to your User
+    if (response.transactionState == kUGClientResponseSuccess) {
+        response = [self connectEntities: @"users" connectorID: @"me" type: @"devices" connecteeID: deviceId];
+    }
+
+### Connecting with Android
+
+The following sample code, taken from [AppServices.java](https://github.com/apigee/appservices-android-push-example/blob/master/src/com/ganyo/pushtest/AppServices.java) in the native Android push sample, uses the connectEntitiesAsync method from the Android SDK to connect a device to an authenticated user.
+
+    // connect Device to current User - if there is one
+    if (dataClient.getLoggedInUser() != null) {
+      dataClient.connectEntitiesAsync("users", dataClient.getLoggedInUser().getUuid().toString(),
+                                       "devices", device.getUuid().toString(),
+                                       new ApiResponseCallback() {...
+                                       
+### Connecting with HTML5/JavaScript
+
+The following code illlustrates how to associate the currently logged in user with their device.
+
+    // You'll need a client from the JavaScript SDK.
+    var client = new Apigee.Client({
+        // Initialize client.
+    });
+
+    // Get information about the current user so you can use
+    // it to connect them with their device.
+    client.getLoggedInUser(function(err, data, user) {
+        if(err) {
+            // Could not get the logged in user.
+        } else {
+            if (client.isLoggedIn()) {
+                // Using a PushNotification function to get the device ID as
+                // it is known to the Apigee system.
+                pushNotification.getApigeeDeviceId(function(results) {
+                    if (results.deviceId) {
+                        // Use the JavaScript SDK connect function to register
+                        // a connection between the current user and their device.
+                        user.connect('devices', results.deviceId, function (err, data) {
+                            if (err) {
+                                // Could not make the connection.
+                            } else {
+                                // Call succeeded, so pull the connections back down.
+                                user.getConnections('devices', function (err, data) {
+                                if (err) {
+                                    // Couldn't get the connections.
+                                } else {
+                                    // Connection exists.
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+You can also connect users with groups so that you can send push notifications to groups of users (and their associated devices), see [Working with group data](../user-management/group.html).
+

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/overview.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/overview.txt b/content/docs/_sources/push-notifications/overview.txt
new file mode 100644
index 0000000..32fb451
--- /dev/null
+++ b/content/docs/_sources/push-notifications/overview.txt
@@ -0,0 +1,58 @@
+# Push notifications overview
+
+<table style="border: solid 1px grey">
+<tr>
+<td width="40%" style="padding:1em">
+
+.. image:: iphonemessage.png 
+
+</td>
+<td>
+
+## Reach your users with push
+With the new push notifications feature in the Usergrid, you can send announcements to your app's users.
+
+* __Reach your app's users__ with messages they care about.
+* __Keep your app footprint low__ while communicating in a high-value way with your app's users. 
+
+[Read more](getting-started.html)
+
+</td>
+</tr>
+</table>
+
+<p></p>
+
+## Get started
+
+#### [Get started with a tutorial](tutorial.html)
+Build your first push-enabled app using an Apigee sample.
+
+#### [Find what you can do with it](getting-started.html)
+A video and introduction.
+
+#### [See the prerequisites](getting-started.html#prerequisites)
+Depending on your supported app platforms, you'll need just a few things.
+
+ 
+## Build push support
+
+#### [Setting up push notifications support](getting-started.html)
+Connect Apple or Google with Usergrid and your app.
+
+#### [Register your app](registering.html)
+Register with Apple or Google.
+
+#### [Create a notifier](creating-notifiers.html)
+Your application uses this to send messages.
+
+#### [Register client devices](managing-users-and-devices.html)
+Your app code registers to receive notifications.
+
+#### [Send and manage notifications](creating-and-managing-notifications.html)
+You can do this from app code or the admin portal.
+
+## Learn more
+
+#### [Troubleshoot your push support](troubleshooting.html)
+Things don't work as you expect?
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/registering.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/registering.txt b/content/docs/_sources/push-notifications/registering.txt
new file mode 100644
index 0000000..8930583
--- /dev/null
+++ b/content/docs/_sources/push-notifications/registering.txt
@@ -0,0 +1,102 @@
+# Registering with a notification service
+To send push notifications, you will need to first register your app with the push notification service (Apple APNs or Google GCM) that corresponds to your app's platform. Once you've registered, the service will provide you with a certificate or key that you will need when you create an Usergrid notifier. (See [Creating notifiers](creating-notifiers.html) for more information.)
+
+Push notification services are gateways controlled by platform services (such as Apple and Google). These gateways ensure that push notifications are delivered securely and originate from trusted apps.
+
+To send push notifications to your app on iOS devices, you’ll register the the Apple Push Notification service (APNs). For app on Android, you’ll register with Google Cloud Messaging for Android (GCM).
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For an overview of how to set up push notifications, see [Setting up push notification support](adding-push-support.html).
+</p></div>
+
+## Registering with Apple APNs
+Before you can send push notifications to your app on iOS devices, you'll need to get set up so that Apple knows you'll be sending notifications. To do that, you'll need to do the following:
+
+* Generate an SSL signing certificate you can use to generate a .p12 certificate.
+* Create an Apple App ID through which you can associate push notifications support with your app.
+* Generate a .p12 certificate you can use to create an Usergrid notifier. The certificate will be sent to APNs with push notification requests.
+
+For more information see "How the pieces connect" in [Setting up push notification support](getting-started.html).
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+You'll need a Mac to generate a .p12 certificate and work with APNs.
+</p></div>
+
+### Generating an SSL signing certificate
+First, you'll create an SSL signing certificate that you can use to generate a .p12 certificate. To generate an SSL signing certificate, do the following:
+
+1. On your development machine, launch the Keychain Access application.
+2. From the Keychain Access menu, select __Certificate Assistant > Request a Certificate From a Certificate Authority__.
+3. Enter a contact email address and a name you will use to sign your apps.
+4. Select __Saved to disk__, then click __Continue__.
+5. Select __Desktop__ from the Where drop-down, then click __Save__ to download the .certSigningRequest file.
+6. Click __Done__ once the download has completed.
+
+### Creating an App ID
+
+Next, you must create an App ID for your app. The App ID uniquely identifies your app and provides a way for you to configure the app for push notification support. (For more on App IDs, see [Creating and Configuring App IDs](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html).)
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+An iOS developer account is required to complete these steps. To register for an iOS developer account, visit the [Apple Developer site](https://developer.apple.com/).
+</p></div>
+
+1. Log in to [Apple's iOS developer portal](https://developer.apple.com/ios/manage/overview/index.action).
+2. In the iOS Apps section, click __Identifiers__, then select __App IDs__.
+3. Click the + icon to create a new App ID, and enter the following:
+
+* __App ID Description - Name__: A unique name that identifies your app.
+* __App BaaS__: Select Push Notifications.
+* __App ID Suffix__: Select Explicit App ID, and enter your desired App ID in reverse-domain format. For example, com.apigee.pushapp.
+
+4. Click __Submit__ to create the App ID, then click __Done__. You will be returned to the App IDs page.
+
+### Generating a .p12 certificate
+
+Finally, you will generate the .p12 certificate using the App ID and signing certificate you created in the previous steps. The .p12 certificate will be sent by Apigee to Apple APNs with all push notification requests. A unique .p12 certificate is required for each app. In addition, you should create separate .p12 certificates for development and production versions of your app.
+
+1. On the App IDs page, click your new App ID, then click Edit.
+2. In the Push Notifications section, under Development SSL Certificate, click Create Certificate.
+
+.. image:: pushsslcertificate.png
+
+3. Click __Choose File__, select the .certSigningRequest file you saved to your Desktop in the previous section, then click __Generate__.
+4. Click __Done__. You will be returned to the App ID settings window.
+5. In the Push Notifications section, click __Download__ to save the certificate (aps_development.cer file) to your Desktop.
+6. Double-click the .cer file to install it in your keychain. The newly installed certificate will appear in your Keychain Access application under My Certificates with a name similar to "Apple Development iOS Push Services: <bundle identifier>".
+7. Control-click the certificate and select __Export__.
+8. Save the certificate to your Desktop as a 'Personal Information Exchange (.p12)' file. (You'll need this file when you create a notifier. For more information, see [Creating notifiers](creating-notifiers.html).
+9. In the password dialog, leave the password field blank, then click __OK__.
+10. In the next dialog, enter your system password, then click __Allow__.
+
+
+## Registering with Google GCM
+To create a notifier for sending notifications, you'll need a Google API project and register your app as part of that project. The project's identifier (project number) will become the sender ID your client code will send when registering. Registering your app will give you an API key you'll use to create a notifier. (For more information see "How the pieces connect" in [Adding push notifications support](adding-push-support.html).)
+
+The following is an abbreviated version of the steps described in the Google documentation on [getting started with Google Cloud Messaging](http://developer.android.com/google/gcm/gs.html). 
+
+To generate a project number and API key, do the following:
+
+1. Go to the [Google API developer web site](https://code.google.com/apis/console/) and log in with your Google ID.
+
+2. Click __Create Project__, enter a project name and ID, then follow the steps required to verify.
+
+3. In the left nav, click __Overview__ to view the project number. Note this number for later use in client code.
+
+.. image:: googleproj0.png
+
+4. Click __APIs__ in the left nav area, then click the button to enable __Google Cloud Messaging for Android__.
+
+.. image:: gcmsetting.png
+
+5. In the left nav, under __APIs and auth__, click __Credentials__.
+
+6. Under __Public API access__, click __Create New Key__.
+
+7. In the __Create a new key__ dialog, click __Server key__. Take care not to choose "Android key," though you might be tempted to. Remember that your push notification requests will be received by Google from Apigee's server (via the notifier your code sends to Apigee), rather than directly from the device your app is installed on.
+
+8. On the __Create a server key...__ dialog, enter the IP address of the server that will be sending the notification request to Google.
+
+9. Click __Create__.
+
+10. On the Credentials page, under __Key for server applications__, copy the __API key__ value for use when creating a notifier to request push notifications from GCM. (For more information, see [Creating notifiers](creating-notifiers.html).)
+

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/troubleshooting.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/troubleshooting.txt b/content/docs/_sources/push-notifications/troubleshooting.txt
new file mode 100644
index 0000000..15cab02
--- /dev/null
+++ b/content/docs/_sources/push-notifications/troubleshooting.txt
@@ -0,0 +1,93 @@
+# Troubleshooting 
+
+## Working with Android
+
+### App fails to install on the emulator
+
+* When using the emulator, be sure to note the setup steps in [Push notifications prerequisites](getting-started.html#prerequisites).
+
+* Sometimes installation fails while the emulator is still being launched. Wait until the emulator is up and running (so that you can unlock and interact with the UI), then run the project again.
+
+* Make sure that the order of your Java Build Path matches the order shown in [Tutorial: Push notifications sample app](tutorial.html).
+
+### Push errors
+If pressing the button to send yourself a push throws an exception or doesn't respond:
+
+* Make sure the emulator's target matches the Google API version used in the project.
+
+* In the IDE log, wait until you see that the device has been registered before sending yourself a push.
+Sometimes waiting for the code to run and trying another click gets the push message to you.
+
+* If you successfully send yourself a push message once but fail to again, try one of the following:
+
+Go to the apps list on the device and launch the app from there.
+
+OR 
+
+Uninstall the app from the device, delete the device in the admin portal, and run the project again.
+
+### MismatchSenderId error message from the server when it tries to send a message to your app.
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The error might be occurring because the sender ID with which your app is registering at GCM for notifications does not correlate to the API project whose API key was used to create your notifier. First, confirm the following:
+
+* The sender ID in your app code (used when registering with GCM) is the same as your Goole API project number.
+
+* The API key used to create your notifier is the same as the API key in your Google API project.
+
+* The notifier name used in your app code is the same as for the notifier you created in the Usergrid.
+
+It can be possible to make a fix (such as by correcting the sender ID in your app code) and still see this error. If you're still seeing the error, consider create a new API project and notifier, then use their new values in your code:
+
+1. Recreate (or create anew) the Google API project. This will generate a new API key and project number. See Registering with a notification service.
+
+2. Create a new notifier for GCM using the API key you generated with the new API project. See Creating notifiers.
+
+3. Use the new notifier name in your code, along with a new sender ID that is that same value as the Google API project number.
+
+### INVALID_SENDER error message
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The "sender" in this case is the Google API project you created to send notification messages. Confirm that the sender ID you're using in code is the same value as the API project number generated when you created your Google API project. See Registering with a notification service.
+
+## Working with PhoneGap Android 
+
+### App fails to install on the emulator
+
+* When using the emulator, be sure to note the setup steps in [Tutorial: Push notifications sample app](tutorial.html).
+
+* Sometimes installation fails while the emulator is still being launched. Wait until the emulator is up and running (so that you can unlock and interact with the UI), then run the project again.
+
+* Make sure that the order of your Java Build Path matches the order shown in [Tutorial: Push notifications sample app](tutorial.html).
+
+### Push errors
+If pressing the button to send yourself a push throws an exception or doesn't respond:
+
+* Make sure the emulator's target matches the Google API version used in the project.
+
+* In the IDE log, wait until you see that the device has been registered before sending yourself a push.
+Sometimes waiting for the code to run and trying another click gets the push message to you.
+
+* If you successfully send yourself a push message once but fail to again, try one of the following:
+
+Go to the apps list on the device and launch the app from there.
+
+OR 
+
+Uninstall the app from the device, delete the device using the admin portal, then run the project again.
+
+### MismatchSenderId error message from the server when it tries to send a message to your app.
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The error might be occurring because the sender ID with which your app is registering at GCM for notifications does not correlate to the API project whose API key was used to create your notifier. First, confirm the following:
+
+* The sender ID in your app code (used when registering with GCM) is the same as your Google API project number.
+
+* The API key used to create your notifier is the same as the API key in your Google API project.
+
+* The notifier name used in your app code is the same as for the notifier you created in the Usergrid.
+
+It can be possible to make a fix (such as by correcting the sender ID in your app code) and still see this error. If you're still seeing the error, consider create a new API project and notifier, then use their new values in your code:
+
+1. Recreate (or create anew) the Google API project. This will generate a new API key and project number. See [Registering with a notification service](registration.html).
+
+2. Create a new notifier for GCM using the API key you generated with the new API project. See [Creating notifiers](creating-notifiers.html).
+
+3. Use the new notifier name in your code, along with a new sender ID that is that same value as the Google API project number.
+
+### INVALID_SENDER error message
+The sender ID is a number you send to GCM from app code when registering with GCM for notifications. The "sender" in this case is the Google API project you created to send notification messages. Confirm that the sender ID you're using in code is the same value as the API project number generated when you created your Google API project. See [Registering with a notification service](registration.html).

http://git-wip-us.apache.org/repos/asf/usergrid/blob/73186077/content/docs/_sources/push-notifications/tutorial.txt
----------------------------------------------------------------------
diff --git a/content/docs/_sources/push-notifications/tutorial.txt b/content/docs/_sources/push-notifications/tutorial.txt
new file mode 100644
index 0000000..8ebecfe
--- /dev/null
+++ b/content/docs/_sources/push-notifications/tutorial.txt
@@ -0,0 +1,251 @@
+# Tutorial: Push notifications sample app
+In this tutorial, you'll use a sample app (iOS, Android, or PhoneGap) to send yourself a push notification with the Usergrid push notification API. You'll register with a push notification services (Apple APNs or Google GCM) to create the required security certificate or key, create the required Usergrid notifier to send a message, then modify, compile and run the sample app to see push notifications in action.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For an overview of how to set up push notifications, including troubleshooting tips, see [Adding push notifications support](adding-push-support.html).
+</p></div>
+
+## Before you begin
+Before you can add support for push notifications, be sure that you're set up for the requirements described in Adding push notifications support.
+
+## Step 1: Download a sample app
+Sample push notification apps are included in the /samples directory of the following platform SDKs and plugins:
+
+* Native iOS [Download the SDK](http://www.apigee.com/docs/content/ios-sdk-redirect)
+
+* Native Android [Download the SDK](http://www.apigee.com/docs/content/android-sdk-redirect)
+
+* PhoneGap iOS & Android (HTML5) [Download the SDK](http://www.apigee.com/docs/content/javascript-sdk-redirect
+
+To begin this tutorial, download the sample app for the platform of your choice.
+
+__A note to PhoneGap developers__: PhoneGap requires a plugin to enable push notifications. The plugin is included in the sample apps in the JavaScript SDK. For new PhoneGap applications, [download the PhoneGap push plugin](https://github.com/phonegap-build/PushPlugin).
+
+## Step 2: Register with a notification service and generate a certificate/key
+To send push notifications you must register your app with the push notification service that corresponds to your app's platform. Once registered, the service will provide you with a certificate or key that you will provide when creating an Usergrid notifier.
+
+For a full walkthrough of how to register an app with a notification service and generate the necessary certificate/key, see [Registering with a notification service](registration.html).
+
+## Step 3: Create a notifier
+Notifiers are entities that carry your push notifications to a notification service. Once a notification service has verified that your notifier contains valid credentials, it will deliver your push notification to the devices of your app's users.
+
+For information on how to use the admin portal to create a notifier, see [Creating notifiers](creating-notifiers.html).
+
+## Step 4: Configure and run the sample app
+In this step, you'll open your sample app of choice in your IDE and configure it. The Android sample app can be run with an emulator, included in the Android Developer Tools. The iOS sample app must be run on an actual iOS device.
+
+The following sections provide platform-specific guidance for setting up and running the samples. However, this content assumes that you understand your development environment well enough to configure and work with projects.
+
+### iOS Dev Setup
+
+To configure and run the Native iOS push notification sample app, do the following:
+
+1. Open the iOS sample app with XCode by opening its .xcodeproj file.
+
+2. Make the following changes to __/Push Test/AppDelegate.m__:
+
+* __orgName__: Your Apigee organization.
+
+* __appName__: The app in your organization where you created the notifier. (For the sample, make sure it's "sandbox".)
+
+* __notifier__: Name of the notifier you created. (For the sample, make sure it's "appledev".).
+
+3. Plug your iOS device into your development machine.
+
+4. In Xcode, select __Window > Organizer__ to open the Xcode Organizer.
+
+5. Under __Devices__, select the device you plugged in, then click __Add to Member Center__. You may be prompted to log in with the Apple ID associated with your Apple Developer account.
+
+6. If prompted, select a Development Team to use for provisioning. This will be a team you've registered at the Apple developer portal.
+
+7. Log in to the [Apple Developer portal](https://developer.apple.com/) and create a provisioning profile that includes the App ID you chose when you registered the sample app with Apple APNs. For more information on how to create a provisioning profile, see "About provisioning profiles" below.
+
+8. Download the profile and add it into Xcode Organizer, in the Provisioning Profiles group under your plugged-in device.
+
+9. Close the Organizer.
+
+10. In Xcode, select the Project Navigator, then select the project root folder.
+
+11. In the __General__ tab, in the __Bundle Identifer__ box, enter the App ID associated with your provisioning profile.
+
+12. In the __Build Settings__ tab, under __Deployment__, for the __iOS Deployment Target__ select the iOS version on your connected device. The version is displayed in the Xcode Organizer.
+
+13. In the __Build Settings__ tab, under __Code Signing__, under __Code Signing Identity > Debug__, select the Apple signing certificate corresponding to your developer identity.
+
+.. image:: iospushsettings.png
+
+14. Click __Run__ to launch the sample on your iOS device.
+
+15. When the "codesign wants to sign using key <Your Name> in your keychain." dialog is displayed, click __Allow__.
+
+16. The project is now built, and the app is installed on your device. The first time you run the push sample app, your device will ask permission to allow push notifications. Tap __OK__.
+
+.. image:: iospushauth.png
+
+17. In the app, tap the __push to this device__ button to send yourself a push notification. If you have configured your notification to go to multiple devices, tap the __push to all devices__ button to send the push notification to all devices.
+
+.. image:: iospushfinal.png
+
+### PhoneGap iOS Dev Setup
+
+To configure and run the PhoneGap iOS push notification sample app, do the following:
+
+1. Open the iOS PhoneGap sample app with Xcode by opening its .xcodeproj file.
+
+2. Make the following changes in __/www/js/index.js__:
+
+* __orgName__: Your Apigee organization.
+
+* __appName__: The app in your organization where you created the notifier. (For the sample, make sure it's "sandbox".)
+
+* __notifier__: Name of the notifier you created.
+
+3. Plug your iOS device into your development machine.
+
+4. In Xcode, select __Window > Organizer__ to open the Xcode Organizer.
+
+5. Under __Devices__, select the device you plugged in, then click __Add to Member Center__. You may be prompted to log in with the Apple ID associated with your Apple Developer account.
+
+6. If prompted, select a Development Team to use for provisioning. This will be a team you've registered at the Apple developer portal.
+
+7. Log in to the [Apple Developer portal](https://developer.apple.com/) and create a provisioning profile that includes the App ID you chose when you registered the sample app with Apple APNs. For more information on how to create a provisioning profile, see "About provisioning profiles" below.
+
+8. Download the profile and add it into Xcode Organizer, in the Provisioning Profiles group under your plugged-in device.
+
+9. Close the Organizer.
+
+10. In Xcode, select the Project Navigator, then select the project root folder.
+
+11. In the __General__ tab, in the __Bundle Identifer__ box, enter the App ID associated with your provisioning profile.
+
+12. In the __Build Settings__ tab, under __Deployment__, for the __iOS Deployment Target__ select the iOS version on your connected device. The version is displayed in the Xcode Organizer.
+
+13. In the __Build Settings__ tab, under __Code Signing__, under __Code Signing Identity > Debug__, select the Apple signing certificate corresponding to your developer identity.
+
+.. image:: iospgsettings.png
+
+14. At the top of the IDE, ensure that the name for your plugged in device is displayed next to the target name, then click the Run button to launch the sample on your iOS device.
+
+15. If the "codesign wants to sign using key <your name> in your keychain" dialog is displayed, click __Allow__.
+
+16. The project is now built, and the app is installed on your device. The first time you run the push sample app, your device will ask permission to allow push notifications. Tap OK.
+
+17. In the app, tap the __Send a push with Phonegap!__ button to send yourself a push notification.
+
+.. image:: iospgapp.png
+
+### About iOS provisioning profiles
+For iOS app testing, you need a provisioning profile that's associated with an Apple ID. You set up the provisioning profile in the Apple developer portal, download the profile, and import it into Xcode.
+
+To set up a provisioning profile, you need to create an "iOS App Development" certificate in the Apple developer portal. For example, in the Apple APNs setup earlier in this tutorial, you created a certificate in the Apple developer portal to be used for push notifications. However, you won't be able to create a provisioning portal with just that certificate. You also need to create an "iOS App Development" certificate (the configuration settings don't matter), as shown in the following image.
+
+.. image:: iospgcert.png
+
+After you create an iOS App Development certificate, you can create a provisioning profile that includes your App ID/certificate for push notifications.
+
+### Android Dev Setup
+
+To configure and run the native Android push notification sample app, do the following:
+
+1. Make sure you have the latest Android SDK installed in your IDE, and that Android APIs have been installed via the Android SDK Manager.
+
+2. Import the native Android sample app project into your IDE
+
+3. Modify the following in __/src/com.ganyo.pushtest/Settings.java__:
+
+* __GCM_SENDER_ID__: Your Google Cloud Messaging (GCM) project number, as described in the Tutorial: Push notifications sample app.
+
+* __NOTIFIER__: Name of your notifier. (For the sample, make sure it's the name of the notifier you created.)
+
+* __ORG__: Your Apigee organization.
+
+* __APP__: The app in your organization where you created the notifier. (For the sample, make sure it's "sandbox".)
+
+* __USER__ and __PASSWORD__: Optional. If you created your notifier in an app other than "sandbox" (which doesn't require authentication), enter the username and password of one of your Usergrid admin users.
+
+4. In AndroidManifest.xml, be sure the proper Android permissions are included, such as READ_PHONE_STATE and VIBRATE.
+
+5. In your project properties, go to __Java Build Path > Libraries__ and add all the JAR files from the project's /libs directory.
+
+6. In the __Order and Export__ tab, move the JARs to the top of the list and select all the check boxes. Make sure the order and selections match the following image:
+
+.. image:: assettings.png
+
+7. If you're using an emulator, configure the emulator to use the Google APIs Level 16 target.
+
+.. image:: asemu.png
+ 
+8. Run the project as an Android Application. The IDE should compile the project and install the app on your device.
+
+9. Press the button on the app to send yourself a push notification.
+
+.. image:: asapp.png
+
+### PhoneGap Android Dev Setup
+
+To configure and run the PhoneGap Android push notification sample app, do the following:
+
+1. Make sure you have the latest Android SDK installed in your IDE, and that Android APIs have been installed via the Android SDK Manager.
+
+2. Import the PhoneGap Android sample app project into your IDE.
+
+3. Modify the following in __/assets/www/js/index.js__:
+
+* __orgName__: Your apigee organization.
+
+* __appName__: The app in your organization where you created the notifier. (For the sample, make sure it's "sandbox".)
+
+* __notifier__: Name of your notifier.
+
+* __senderID__: Your API project number (the project must support Google Cloud Messaging for Android (GCM)), as described in the [Registering with a notification service](registration.html).
+
+4. In __AndroidManifest.xml__, be sure the proper Android permissions are included. This includes READ_PHONE_STATE and VIBRATE.
+
+5. In your project properties, go to __Java Build Path > Libraries__ and add all the JAR files from the project's /libs directory.
+
+6. In the __Order and Export__ tab, move the JARs to the top of the list and select all the check boxes. Make sure the order and selections match the following image:
+
+.. image:: pgasettings.png
+
+7. If you're using an emulator, configure the emulator to use the Google APIs Level 16 target or above. Also, be sure to see the Android requirements in [Adding push notifications support](adding-push-supprt.html) for steps on setting up the emulator to support push notifications.
+
+.. image:: pgaspath.png
+
+8. Run the project as an Android Application. The IDE should compile the project and install the app on your device.
+
+9. Press the button on the app to send yourself a push notification.
+
+.. image:: pgaapp.png
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">

+For troubleshooting tips, see [Adding push notifications support](adding-push-supprt.html.
+</p></div>
+
+### More about PhoneGap
+The [PhoneGap](http://phonegap.com/) iOS push notification sample was created using standard web technologies such as HTML5, JavaScript, and CSS. You build the app with those technologies, and PhoneGap provides project templates for iOS, Android, and other platforms. For example, atop platform-specific PhoneGap code, core app code between the iOS and Android samples is essentially the same.
+
+When using PhoneGap to develop push notification apps, you use a PhoneGap plugin designed to support push notifications. That plugin is included in the Apigee samples. For more about the plugin, see the [plugin's GitHub project](https://github.com/phonegap-build/PushPlugin/blob/master/README.md).
+
+## Step 5: Review the data entities created by the sample app
+
+1. Log in to the admin portal, and select Data in the left navigation pane.
+
+2. Select any of the following collections to view the entities that were created in them by the push notification sample app:
+
+* ``/devices`` - To see the device that was added.
+
+* ``/notifications`` - To see the notification that was sent.
+
+* ``/receipts`` - To see the receipt generated from the successful push.
+
+## Step 6: Send additional push notifications using other Usergrid tools
+Send a push notification from the Usergrid Notifications console
+On the Send Notification screen. Select your notifier, select All Devices, enter a message, select Now, and click to send it.
+
+.. image:: sendnotification.png
+
+### Send a push notification directly via the push notifications API
+Use the following curl command in a terminal window, replacing your-org, your-app and notifier-name.
+
+    curl -X POST "https://api.usergrid.com/your-org/your-app/devices/*/notifications" -d '{"payloads":{"notifier-name":"I just sent another notification! Yea, me!"}}'
+    
\ No newline at end of file


Mime
View raw message