Sign up for a Parse account to implement this tutorial and more!

Sign Up

Icon_push_ios
iOS Push Notifications

This tutorial provides you with a step-by-step guide to configuring your iOS application for push.

iOS
PFPush
Push Notifications
Screencast

Download code for this tutorial:

.zip File GitHub

Using push notifications is a great way to add real-time messaging to your application. It allows you to stay in touch with your users and makes it possible for your users to communicate with each other. This tutorial will guide you through all the necessary steps required to add this feature to your Parse application.

We will begin on the Apple Developer website to create an SSL certificate associated to an App ID and a provisioning profile. Next we'll see how to configure a Parse app on the Parse website, and finally, we'll take a look at creating a push-enabled iOS application and sending notifications to users.

Before you begin, remember that push notifications are not available in the iOS Simulator. You will need an iOS device, as well as an Apple Developer license to complete this tutorial.

1. Creating the SSL certificate

The first step is to create an App ID and the associated SSL certificate on the Apple Developer website. This certificate will allow the Parse server to send push notifications to the application identified by the App ID.

1.1. Generating a Certificate Request

To begin, we'll need a certificate signing request file. This will be used to authenticate the creation of the SSL certificate.

  1. Launch the Keychain Access application on your Mac.

  2. Select the menu item Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority…

  3. Enter your email address and name.

  4. Select "Saved to disk" to download the .certSigningRequest file to your desktop.

Certificate Signing Request

1.2. Creating an App ID

Every iOS application installed on your developer device needs an App ID. As a convention, these are represented by reversed addresses (ex. com.example.MyParsePushApp). For this push app, you can use an App ID you've already created, but make sure it does not contain a wildcard character ("*"). The following instructions cover the creation of a new App ID.

  1. Navigate to the Apple Developer Member Center website, and select Certificates, Identifiers & Profiles.

  2. Select Identifiers from the iOS Apps section.

  3. You will see a list of your iOS App IDs. Select the + button to register a new App Id.

Register new iOS App ID
  1. Enter a name for your new App ID, then make sure to select the checkbox next to Push Notifications under App Services.
Enable Push Notifications under App Services
  1. Choose an App ID Prefix. The default selection should be correct in most cases.

  2. Under App ID Suffix, select Explicit App ID. Enter your iOS app's Bundle ID. This string should match the Bundle Identifier in your iOS app's Info.plist.

Explicit App ID
  1. Select "Continue" and make sure that all the values were entered correctly. Push Notifications should be enabled, and the Identifier field should match your app's Bundle Identifier (plus App ID Prefix). Select "Submit" to finalize the registration of your new App ID.

1.3. Configuring your App ID for Development Push Notifications

Now that you've created an App ID (or chosen an existing Explicit App ID), it's time to configure the App ID for Push Notifications.

  1. Select your newly created App ID from the list of iOS App IDs, then select "Settings".
Select new App ID
  1. Scroll down to the Push Notifications section. Here you will be able to create both a Development SSL Certificate, as well as a Production SSL Certificate. Start by selecting "Create Certificate" under "Development SSL Certificate".
Create Certificate
  1. The next screen will show instructions for creating a Certificate Signing Request (CSR). This is the same .certSigningRequest file you created earlier in Section 1.1. Select "Continue", then select "Choose File..." and locate the .certSigningRequest you created in Section 1.1.

  2. Select "Generate". Once the certificate is ready, select "Done" and download the generated SSL certificate from the "iOS App ID Settings" screen.

Download SSL Certificate
  1. Double click on the downloaded SSL certificate to install it in your Keychain.

  2. In Keychain Access, under "My Certificates", find the certificate you just added. It should be called "Apple Development IOS Push Services: ".

Export P12 Certificate
  1. Right-click on it, select "Export Apple Development IOS Push Services:...", and save it as a .p12 file. You will be prompted to enter a password which will be used to protect the exported certificate. Do not enter an export password when prompted! Note that you might have to enter your OS X password to allow Keychain Access to export the certificate from your keychain.
Export as .p12

If the Personal Information Exchange (.p12) option is grayed out in the export sheet, make sure "My Certificates" is selected in Keychain Access. If that does not help, double check that your certificate appears under the login keychain. You can drag and drop it into login if needed.

Note that you've just enabled Push Notification for your app in development mode. Prior to releasing your application on the App Store, you will need to repeat steps 1 through 7 of this section, but select "Production Push SSL Certificate" in step 2 instead, as covered in Section 7.

2. Creating the Provisioning Profile

A Provisioning Profile authenticates your device to run the app you are developing. Whether you have created a new App ID or modified an existing one, you will need to regenerate your provisioning profile and install it. If you have trouble using an existing profile, try removing the App ID and setting it back. For this tutorial, we'll create a new one.

  1. Navigate to the Apple Developer Member Center website, and select Certificates, Identifiers & Profiles.

  2. Select Provisioning Profiles from the iOS Apps section.

  3. Select the + button to create a new iOS Provisioning Profile.

  4. Choose "iOS App Development" as your provisioning profile type then select "Continue". We will create Ad Hoc and App Store profiles later.

  5. Choose the App ID you created in Section 1 from the drop down then select "Continue".

  6. Make sure to select your iOS Development certificate in the next screen, then select "Continue".

  7. You will be asked to select which devices will be included in the provisioning profile. Select "Continue" after selecting the devices you will be testing with.

  8. Choose a name for this provisioning profile, such as "My Parse Push App Development Profile", then select "Generate".

  9. Download the generated provisioning profile from the next screen by selecting the "Download" button.

  10. Install the profile by double-clicking on the downloaded file.

This should open Xcode's Organizer in the Devices pane. Your new provisioning profile should appear in the Provisioning Profiles section of your Library. Make sure that the status for this profile is "Valid profile". If the profile is invalid, make sure that your developer certificate is installed in your Keychain.

Note that prior to submitting your app to the App Store, you will need to test push notifications in production. This will be covered in Section 7.

3. Configuring the Parse App

To use Push Notifications with Parse, you will need to enable this feature in your Parse app and upload the Push SSL certificate you created above.

  1. Navigate to your Parse app on the Parse Dashboard, and select the "Settings" tab.

  2. Select "Push Notifications" from the left-hand side menu and select "Select your certificate" under the "Apple Push Certificate" header. and locate the .p12 certificate you exported from your Keychain earlier.

Push Settings

By default, push notifications can only be sent from your Parse dashboard, from Cloud Code, or through the REST API. If you want your users to be able to send push notifications from the client SDKs, you will need to toggle the "Client push enabled?" option to "on" under the "Push Notification Settings" header. This is useful for applications like chat clients, where users need to send push messages. For this tutorial, select toggle the option to "on".

4. Configuring a Push Enabled iOS Application

We are finally ready to create our iOS application! Let's start by configuring the Xcode project settings. We'll need to make sure that both the App ID and the provisioning profile are set.

  1. In the Info.plist file under the Supporting Files folder, modify the Bundle Identifier field to match your App ID's Bundle Identifier (ex. com.example.MyParsePushApp).
Info.plist configuration
  1. Select your project file in the left-hand menu. Under Project, navigate to "Build Settings", and find (or search for) the "Code Signing Identity" field.

  2. Set all values under this heading to match the provisioning profile installed earlier (ex. "My Parse Push App Development Profile").

Certificate Signing Request
  1. On the left-hand side, select your project's name under "Targets". Again, navigate to "Build Settings" and find the "Code Signing Identity" field. Ensure that all values here also match the new provisioning profile.

5. Adding Code for a Push Enabled iOS Application

We are now ready to start programming. We need to make a few modification to the app delegate in order to receive push notifications.

To register the current device for push, call the method [application registerForRemoteNotificationTypes:] in the app delegate's [application:didFinishLaunchingWithOptions:] method.

- (BOOL)application:(UIApplication *)application
 didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    // Register for push notifications
    [application registerForRemoteNotificationTypes: 
                                 UIRemoteNotificationTypeBadge |
                                 UIRemoteNotificationTypeAlert |             
                                 UIRemoteNotificationTypeSound];
    ...
}

If the registration is successful, the callback method [application:didRegisterForRemoteNotificationsWithDeviceToken:] in the application delegate will be executed. We will need to implement this method and use it to inform Parse about this new device.

- (void)application:(UIApplication *)application 
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)newDeviceToken {
    // Store the deviceToken in the current installation and save it to Parse.
    PFInstallation *currentInstallation = [PFInstallation currentInstallation];
    [currentInstallation setDeviceTokenFromData:newDeviceToken];
    [currentInstallation saveInBackground];
}

When a push notification is received while the application is not in the foreground, it is displayed in the iOS Notification Center. However, if the notification is received while the app is active, it is up to the app to handle it. To do so, we can implement the [application:didReceiveRemoteNotification] method in the app delegate. In our case, we will simply ask Parse to handle it for us. Parse will create a modal alert and display the push notification's content.

- (void)application:(UIApplication *)application 
didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [PFPush handlePush:userInfo];
}

You should now run your application (on your iOS device) to make sure everything is set up correctly. If it is, the first time you run this app you should see a modal alert requesting permission from the user to send push notifications.

6. Sending Push Notifications

Parse allows you to send push notifications from the Parse website, the web API as well as the Parse SDK.

6.1. Parse website

Let's start with the Parse website. By navigating to your Parse app and selecting the "Push Notifications" tab, you can use the text box to broadcast a message to "Everyone". Simply enter a message and click send! If you've installed the app on a device, you should see the notification appear within a few seconds.

6.2. REST API

You can use the Parse REST API to send push notifications to all iOS devices by sending a POST request. Here is an example of a broadcast notification containing the message "Hello World!" sent using curl. Detailed information about the required format can be found in the REST documentation.

curl -X POST \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "where": {
          "deviceType": "ios"
        },
        "data": {
          "alert": "Hello World!"
        }
      }' \
  https://api.parse.com/1/push

6.3. From the App

You can also send push notifications directly from a mobile application. Remember that you need to have enabled this feature in the Parse app's settings tab by selecting "Yes" under the heading "Client push enabled?". There are several methods that can be called to send push notifications. You can consult the full list in the iOS API documentation. Here is an example:

// Create our Installation query
PFQuery *pushQuery = [PFInstallation query];
[pushQuery whereKey:@"deviceType" equalTo:@"ios"];

// Send push notification to query
[PFPush sendPushMessageToQueryInBackground:pushQuery 
                               withMessage:@"Hello World!"];

6.4. From Cloud Code

Finally, you can send pushes automatically from Cloud Code. The Parse.Cloud.afterSave method lets us execute arbitrary code after an object is saved successfully. For example, if you wanted to send a push whenever a "Comment" object is saved:

Parse.Cloud.afterSave("Comment", function(request) {
  // Our "Comment" class has a "text" key with the body of the comment itself
  var commentText = request.object.get('text');

  var pushQuery = new Parse.Query(Parse.Installation);
  pushQuery.equalTo('deviceType', 'ios');
   
  Parse.Push.send({
    where: pushQuery, // Set our Installation query
    data: {
      alert: "New comment: " + commentText
    }
  }, {
    success: function() {
      // Push was successful
    },
    error: function(error) {
      throw "Got an error " + error.code + " : " + error.message;
    }
  });
});

In this tutorial, we've learned how to enable and use push notifications in an iOS application. We began by creating an App ID, generating an associated SSL certificate, and then linking this App ID to a new provisioning profile. Next, we configured the Parse app by uploading the SSL certificate. Afterwards, we created an iOS application and configured it to use the new App ID and provisioning profile. We then implemented a set of delegation methods used to register the app to use push. Finally, we looked at four ways to send push notifications to users: the Parse website, the REST API, the Parse iOS SDK, and Cloud Code.

If you run into any problems, take a look at the "Troubleshooting Tips" section below.

Read on to learn the necessary steps to get your app ready for the App Store.

7. Preparing for the App Store

You've configured your app to receive push notifications during development. Prior to submitting your app to the App Store, you will need to configure push notifications for distribution.

There are two types of distribution profiles: Ad Hoc, and App Store. You will need the latter to submit your app to the App Store, however it is good practice to test push notifications using an Ad Hoc profile prior to submitting your app.

7.1. Configuring your App for Distribution Push Notifications

  1. In Section 1.3., you configured your App ID for Push Notifications in Development. Retrace steps 1 through 7, but select "Production Push SSL Certificate" in step 2 instead.

  2. Your App ID should now be configured for both Development and Distribution push notifications. Make sure to download the new Production SSL Certificate from the App ID Settings screen.

Configured for Development and Distribution
  1. Double click on the downloaded SSL certificate to install it in your keychain. Right-click on it and export it as a .p12 file. Again, don't enter an export password when prompted.

  2. Go back to Section 2 and retrace steps 1 through 10, making sure to select "Ad Hoc" under Distribution in Step 4. You should also use a different name in Step 8, such as "My Parse Push App Ad Hoc Profile". This should help you distinguish between development and distribution profiles.

  3. Retrace the steps from Section 3, and upload your exported Production .p12 certificate to Parse instead.

  4. In Section 4, you configured your app to use a Development provisioning profile. Retrace your steps, but this time choose your new Distribution Ad Hoc provisioning profile instead.

  5. Build and run your app on an iOS device. Verify that push notifications are delivered successfully.

Note that once you have uploaded a production push certificate to Parse, you will only be able to target devices using a distribution provisioning profile. Devices running an app signed with a development provisioning profile will need to install the newly provisioned build again.

7.2. Configuring your App for App Store Distribution

You have now confirmed that your app is configured correctly to receive distribution push notifications using an Ad Hoc provisioning profile. Now it's time to submit your app to the App Store.

  1. Follow steps 1 through 10 from Section 2, making sure to select "App Store" under Distribution for Step 4. Note that this time around, since you will be submitting your app to the App Store, you can skip Step 7 (selecting test devices).

  2. Go through Section 4 again, this time selecting your new App Store Distribution provisioning profile.

  3. Build and archive your iOS app, then submit to the App Store.

8. Troubleshooting Tips:

Setting up Push Notifications is often a source of frustration for developers. The process is complicated and invites problems to happen along the way. If you run into issues, try some of these troubleshooting tips.