Send Docs Feedback

Getting started with push notifications

What are push notifications?

Apigee API BaaS 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 API BaaS). Here are just a couple reasons for enabling push notification support in your app with API BaaS:

  • Reach your app's users with messages they care about. This could be a flash sale happening near them right now (use geolocation!) 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.

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 push notifications feature into your app.

Sample Apps

You'll find samples in SDKs that are specific to four mobile platforms: iOS, Android, Windows Phone 8, 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 admin portal.

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 Apigee organization will make it easier to try out the feature. The sandbox app doesn't require authentication.

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 API 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 API Services application. An API Services application is where you store your data and where you schedule notifications. Data in the application represents devices, notifiers, notifications, users, and groups. For information on creating an app, see Register apps and manage API keys.

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.

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.

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:

  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.
    1. Launch the emulator.
    2. In the emulator, click the Menu button, then go to Settings > Accounts & Sync.
    3. Add a Google account.

Once you've finished these steps, you should have an emulator that can receive push notification messages.

  • A mobile device running Windows Phone 8.

  • The Identity values, Package SID and Client Secret for your app. 

These are generated using your Microsoft Developer account. For more, see Registering with a notification service.
  • 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.

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 API BaaS to notification services.

    The API BaaS 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 API BaaS 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.

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 a notifier 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. At run time, your app's code registers with Apple for notifications by invoking the registerForRemoteNotificationTypes method to receive a token it can send to API BaaS.

C. At run time, your app's code registers with API BaaS for notifications by sending the name of the notifier you created. This ensures that there's a device entity in your API BaaS application. That way, you can address the device with notification messages.

For information on troubleshooting push notifications on iOS devices, see Troubleshooting Push Notifications

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 API BaaS notifier with an API key from the project. The API key correlates the notifier (which you will use to send notification messages from the API BaaS) with the API project (which will forward your notifications to devices).

B. At run time, your app's code registers with the API BaaS for notifications by sending the name of the notifier you created. This ensures that there's a device entity in your API BaaS 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.

A. At configuration time, you generate Identity values, an Sid and secret key for your app. Then you create a notifier with the Security Id (Sid) and secret key. This will correlate the notifier (which you will use to send notification messages) with the Identity values (so that WNS will forward your notifications to devices).

B. At run time, your app's code opens a notification channel to WNS on the user device.

C. At run time, your app's code registers with API BaaS for notifications by updating the device entity that corresponds to the user's device with an updated device ID. This ensures that the notification channel URI is properly updated.

 

Help or comments?