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.