Skip to end of metadata
Go to start of metadata

IBM Mobile Push Notification provides a simple way to integrate Apple Push Notification Service (APNS) with your iOS (iPhone & iPad) 3.2 and above applications. IBM Mobile Push Notifcation's SDK provides application publishers with APNS registration, push notification handling and display, notification inbox, rich (HTML) notification support, user segmentation and (optionally) the ability to send messages based on user location.

This guide will help you get started with the most basic IBM Mobile Push Notification ntegration with simple push.  After you have completed these steps, you can move on to Advanced Integration topics.

Table of Contents

Download the SDK

This implementation guide is compatible with the 2.x version of our IBM Push Notification SDK for Apple iOSBefore you begin your development with the rich notification SDK, you will need to install the iOS development tools (see XCode installations instructions) and have an iOS provision file to develop iOS applications. The instructions assume familiarity with the iOS development process.

You can disable ARC on a file by file basis in the SDK. This is useful if you want to use the latest version of the SDK and also want to use ARC in your own code. To disable ARC on a file, open your project and select the target on the left side of the Xcode window. Select the Build Phases tab, and enter -fno-objc-arc in the text pop-up window for each file in the SDK.

You must fill out the NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription keys in the info.plist file. The two keys are required changes to the developer's project for background location services and foreground location services support in iOS 8.

To use the IBM Push Notification SDK for Apple iOS within the European Union, you must add the following line before the first call to the SDK in the App Delegate class (normally the -(id)init; method):

    [[XLEndpoint get] setEuropeanEndpoint];

 

Download the IBM Push Notification SDKs

Register your iOS App with Apple

In order to get pushes working on your iOS app, you'll need to create a provisioning profile and a push certificate on the Apple Developer Provisioning Portal for your Apple Application ID (Bundle ID). The provisioning profile you create must match the push certificate you upload to IBM Mobile Push Notification, for example, a Development Provisioning Profile will work with a Development Push Certificate. Similarly, there are two "production" distribution profiles: Ad Hoc and App Store. These provisioning profiles will only work with production push certificates.  The provisioning profile will be bundled with your app, it will include the push entitlement which will ask the user for permission to send push notifications upon launching your app for the first time. The push certificate will need to be uploaded to IBM so that we can send pushes to your app users on your behalf. This will allow you to use our push campaign automation tools on our console as well as our push API. Review the following instructions on how to set this up for your application.

  1. On Apple website https://developer.apple.com, in the App ID section of the Provisioning Portal, locate the App ID you wish to use with the Apple Push Notification service. Only App IDs with a specific bundle ID can be used with the APNs. You cannot use a “wild-card” application ID. You must see "Enabled" under the Apple Push Notification service column to register this App ID and configure a certificate for this App ID.

     
  2. Click the 'Edit' button under your desired App ID.
     
  3. In the Configure App ID page, check the Enable Push Notification Services box and click the Configure button. Clicking this button launches the APNS Assistant. This will guide you through the next series of steps where you will create your the distinct Client SSL certificate for your App ID.
     
  4. Download the Client SSL certificate file to your download location and click Done to exit the APNS Assistant.
     
  5. Navigate to the folder where you downloaded the certificate file and double-click on it to install it in your keychain.
     
  6. The application will create an entry called “Apple Development Push Services: <identifier>”.
     
  7. Expand the item and there will be a private key (your name or your corporate name), as a child beneath the Push Service. As in the image above, it will have a key icon next to it.
     
  8. Right click and export the certificate and the private key as .p12 format. 
    1. As part of the export, it will ask you to provide a password for this file, enter a password and make a record of it. You will need to enter this password when you load the certificate to the IBM Mobile Push Notification platform. This password will not be stored on IBM's servers.
       
  9. After you finish these steps, return to the Configure App ID page. Your new certificate will be badged with a green circle and the label “Enabled”.
     
  10. In order to receive test notifications on your device, you'll need to setup a new Provisioning Profile (https://developer.apple.com/iphone/manage/provisioningprofiles/index.action) based on your new APNS-enabled App ID. 
    1. The provisioning profile bundled with your app must have the push entitlement in order for the phone to receive notifications. The entitlement is created when you setup your App ID on the Apple Developer portal.  
    2. After you download the Development and/or Distribution provisioning profiles, they will be available for selection under Code Signing Identities for both your Target and Project settings. Select the correct profile for either Development or Distribution.
    3. If you get this step wrong, you'll see the message no valid 'aps-environment' entitlement string found for application in your xCode console log. Make sure you've selected the correct provisioning profile for your bundle ID under Build Settings > Code Signing Identities.

Register your iOS App with IBM

  1. Select "Add New Application" on the Create/Manage Application Keys page.
     
  2. Upload the .p12 certificate you created in the previous section and enter the password you created for it. Make sure to upload the correct Apple certificate. Most problems developers have with our service stem from uploading the incorrect .p12 certificate file, so double check that you are right.
    1. For development/testing: upload the development certificate.
    2. For production: upload the production or ad hoc certificate.
       
  3. Click Submit.
     
  4. Copy your Application Key and Secret from the page.
 

Implement the IBM Push Notification SDK for Apple iOS within your App

  1. Download the Download the IBM Push Notification SDK for Apple iOS package.
     
  2. Make sure that the Apple Push Notification Service is enabled for your App Id (verify with Apple Provisioning Portal).
     
  3. Create an iPhone app key on the IBM Mobile Push Notification and upload the APN certificate.
     
  4. Open XCode and create a new iOS project.
     
  5. In order to use the iOS Rich Notification SDK, the source files from the SDK folder must be brought into the app project. The easiest way is to drag the XtifyLib folder from the local folder (e.g. ~/XtifyRich vN.n/XtifyLib) into the app XCode project. Make sure the ‘Copy items into destination group’s folder (if needed)’ is checked.
     
  6. Update XtifyGlobal.h:

     

    1. Replace the xAppKey with your app key

       

  7. Add the following frameworks in your project file
    1. Foundation.framework
    2. UIKit.framework
    3. CoreGraphics.framework
    4. SystemConfiguration.framework
    5. MapKit.framework
    6. CoreData.framework
    7. MessageUI.framework
    8. CoreLocation.framework
    9. CFNetwork.framework
    10. libxml2.2.dylib
    11. libz.1.1.3.dylib
    12. MobileCoreServices.framework
    13. CoreTelephony.framework
    14. CoreBluetooth.framework

       
  8. In your App delegate header file (AppDelegate.h):
    1. Add @class XLappMgr ;

       

    2. In your App Implementation file (AppDelegate.m), add #import "XLappMgr.h", and 
      incorporate the member functions marked as ‘//Add or incorporate function into your Application Delegate file’
      .

       

  9. Add  "-ObjC" to "Other Linker Flags"
    1. In XCode navigator select your project, then select TARGETS from the left tab and 'Build Settings'  from the right tab. Look for "Other Linker Flags" and add -ObjC to "Other Linker Flags"
       
  10. Compile and run. The app should register correctly and work normally. If you get a runtime error 'Unrecognized selector' it means the linker flag was not setup correctly.
     
  11. To test your app, create a notification.

Build the IBM Push Notification SDK for Apple iOS Sample App

The IBM Push Notification SDK for Apple iOS SDK package includes the iOS sample app SampleRich.  It will help demonstrate end-to-end functionality of IBM Mobile Push Notification, including simple push notification above combined with standard rich notification integration as described in our Advanced Integration Guide. Remember, you can't receive push notifications on an emulator. You must deploy a provisioning profile on an actual Apple device.

  1. Make sure that the Apple Push Notification Service is enabled for your App Id (verify at Apple Provisioning Portal).
     
  2. Create an iPhone app key on the IBM Mobile Push Notification console and upload the APN certificate.
     
  3. From the XCode File menu, open the SampleRich project.
     
  4. Update XtifyGlobal.h and replace the xAppKey with your app key.
     
  5. Update SampleRich-Info.plist file and replace the Bundle Identifier with your App Id (as obtained in step 1).

  6. Update the project file with your provision file.

  7. Create a rich content within the Notification Manager tab of the IBM Mobile Push Notification console and make sure you get a Rich Notification to your SampleRich App. For help on this, read 3. IBM Mobile Push Notification Console Guide.

Testing and Preparing your iOS for App Store Distribution

It can be a bit confusing when you first encounter all of the different profiles, certificates and keys required for implementing rich push notifications within your app.  This section will provide a quick overview on how to properly configure and test an Ad Hoc build of your application with IBM Mobile Push Notification before submitting it to the app store.

There are two types of profiles Apple offers for testing and releasing iOS applications: Development and Distribution. These profiles also relate to the application type you've setup with IBM Mobile Push Notification in our console.  Applications built with the Apple Development profile need to be assigned to the Development/Testing application type in our console. Similarly, applications built with the Apple Distribution profile need to be assigned to the Production application type in our console.

There are two sub-classes of Apple Distribution profiles: Ad Hoc and App Store.  Before submitting your app to the App Store you should absolutely build a version of your app with an Ad Hoc Distribution profile. In this way, you will be able to associate your production application with your test devices. This will help you review the experience your users will have when using IBM Mobile Push Notification and Apple production push facilities and have confidence that your app will work properly in the wild.

Here's a quick walkthrough on how to setup your app with an Ad Hoc distribution profile:

  1. Follow the instructions for integrating IBM-enabled push notifications with your app.
    1. Within the application configuration section of the Apple Provisioning Portal, make sure you enable your application for use with the Production APNS service. The certificate you generate and upload to IBM Mobile Push Notification must be Production in order for your Ad Hoc app build to work.
  2. Go to the Apple iOS Provisioning Portal
    1. Click on Devices and add your test device IDs.  You can get your device ID through the xCode organizer or through iTunes. Here are instructions.
    2. Click on Provisioning, then click the Distribution tab, then New Profile
      1. Select Distribution Method: Ad Hoc
      2. Select the appropriate App ID associated with the Production Push service
      3. Select your test devices (your Ad Hoc build won't work on devices that are not setup here)
      4. Click Submit
    3. Download your new Ad Hoc Distribution Profile to your computer and install it in xCode by double-clicking on it.
  3. Switch back to your App in xCode
    1. Go to Project Build Settings
    2. Under Code Signing > Release, select your new Distribution Profile
    3. Make sure to do the same under Target Build Settings as well
  4. Delete the development version of your app from your device.  If you try to build your production ad hoc version of your app over your development version, it may not recognize the production entitlements and you will not receive a push.
  5. (optional verification step) Make sure your app is setup correctly in the IBM Mobile Push Notification > Developer Tools.
    1. This is the step that most first-timers get wrong and is the root cause of about 90% of the support request: "I'm not getting a push notification sent to my phone." So double check this before asking for more help.
    2. The Application Key Type must be Production
    3. The .p12 file you uploaded must be the Production-version of the certificate you created in step 1 within Apple's iOS Provisioning Portal 
    4. With your device connected to your computer, build the app on your phone and watch the xCode console for the string Attempt to register after your app fires up. You should see success messages for both Apple push services and IBM Mobile Push Notification registration as well as your token. Note that if you see the same token as your development build, then there is a provisioning profile mismatch in xCode.
  6. Build your app
    1. Connect your iOS device to your computer and build it. Your app & ad hoc provisioning profile will be loaded onto your device and you can begin testing right away.
  7. Send your app to other test devices
    1. You can either connect your other test devices to your computer and build the app for it, as long as their device ID was associated to the Ad Hoc profile in the Apple Provisioning Portal. Or,
    2. You can email the compiled .app on your computer and the downloaded provisioning profile to your testers and they can drag/drop/sync in iTunes. Or,
    3. You can use the Over the Air method. Search google for how to engage this method.
  8. Test rich push notifications
    1. If you know your device token (you can find it by viewing the xCode console as described in Step 4 above), you can push a message directly to your device by using our Push API. Here's a handy perl script to use for testing.
    2. For sending out pushes to all users of your production app, you can use our Push Console.
  9. After you've successfully tested your app
    1. Edit XtifyGlobal.h and set xLogging to false. 
    2. Go back to the Apple iOS Provisioning Portal > Provisioning and this time create an App Store Distribution Profile instead of Ad Hoc.
      1. Also, read this discussion about dirtied provisioning profiles. In certain circumstances your app may not receive the appropriate entitlements when going into the App Store:  http://stackoverflow.com/questions/5681172/bundle-identifier-and-push-certificate-aps-environment-entitlement-error
    3. Download the new Distribution Profile and associate it with your Project and Target Build Settings for Release
    4. You can verify that your Distribution Profile is correct by opening it in a text editor and verifying that it has the correct production values.  It must contain the following key/value: aps-environment production
    5. Build the app
    6. Then go to iTunes Connect and follow the instructions for submitting your app for approval.
    7. If you are incorporating location-based services within your app, it is important to disclose to Apple exactly how you will use this data. For example: "my app may, at the user's option, use location data to present relevant and timely content".
    8. Wait for approval (97% are approved within 5 business days)

If you're running into issues that are not covered here, Get Support.

 

Now that you have the basics working, you can move on to Advanced Integration Topics.
Labels: