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.

Video tutorial

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.

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.

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.

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.

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.

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.

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.

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.

How the pieces connect

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).

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.

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.