LATEST VERSION: 1.9 - CHANGELOG
Push Notification Services v1.8

Configuring Heartbeat Monitor for iOS

This topic describes how Pivotal Cloud Foundry (PCF) operators can configure the Push Notification Heartbeat Monitor app for iOS.

Heartbeat Monitor is a Cloud Foundry app deployed by the PCF Push Notification service to help you ensure the service runs correctly end-to-end. It does this by sending a push, or heartbeat, every minute to the devices registered with the app. You can also select the app in the Push dashboard to view its historical data.

Follow the instructions below to configure Heartbeat Monitor and run the companion iOS app on your device.

Prerequisites

To configure the Heartbeat Monitor app for iOS, you must have the following:

  • An iOS 8+ device
  • The latest Xcode that supports Swift 2.2 installed on your workstation
  • An Apple Developer account

Request an iOS Development Certificate

Follow these steps to obtain an iOS development certificate:

  1. Navigate to the Certificates, Identifiers & Profiles section of the Apple Developer Portal.

  2. In the side navigation, select Certificates > All.

    Select all

  3. Click the + button in the top right to add a new certificate.

    Add Certificate

  4. Select iOS App Development and click Continue.

    Select Development Certificate

  5. Follow the on-screen instructions to Create a CSR file and click Continue.

    iOS CSR

  6. Upload the .csr file you created and click Continue to generate the new certificate.

  7. Click Download.

  8. Open your certificate and import it to the Keychain Access app when prompted.

    Add cert to Keychain

Request an APNS Certificate

Follow these steps to enable your app to receive push notifications:

Create an App ID

  1. Navigate to the Certificates, Identifiers & Profiles section of the Apple Developer Portal.

  2. In the side navigation, select Identifiers > App IDs.

  3. Click the + button to create an App ID.

  4. Enter an Name and a Bundle ID.

    APNS Certs 2

  5. Select the Push Notifications checkbox and click Continue.

    APNS Certs 3

  6. Click Register.

Create an APNS Certificate

  1. In the App IDs list, select the App ID you registered and click Edit.

    APNS Certs 5

  2. Under the Push Notifications section, choose Development SSL Certificate and click the corresponding Create Certificate button.

    APNS Certs 6

  3. Follow the on-screen instructions to create a new CSR.

  4. Upload the .csr file you created and click Continue to generate the new certificate.

  5. Click Download.

  6. Open your certificate and import it to Keychain Access when prompted.

  7. In Keychain Access, select both your Apple Development iOS Push Services certificate and the private key it was signed with.

    APNS Certs 7

  8. Right click your selection and choose Export 2 Items…

  9. Save the .p12 file for uploading to the Push dashboard in a later step.

    APNS Certs 8

Create a Provisioning Profile

Follow these steps to create a Provisioning Profile that you specify when building the Heartbeat Monitor iOS app in Xcode:

Register a Device

Note: You need an iOS 8+ Device to use Heartbeat Monitor. If you already have an iOS 8+ Device registered, skip to the next step.

  1. Navigate to the Certificates, Identifiers & Profiles section of the Apple Developer Portal.

  2. In the side navigation, select Devices > All.

  3. Click on the + button in the top right to add a device.

  4. Retrieve the UDID of your device:

    1. Connect your device to your computer.
    2. Open iTunes.
    3. Select the device tab.

    Provisioning 2

  5. Click the Serial Number of the device to reveal the UDID and right click the field to copy it.

    Provisioning 3

  6. In the Apple Developer Portal, enter a Name for your device and paste the UDID into its field.

    Register Device

  7. Click Register.

Create a Profile

  1. Navigate to the Certificates, Identifiers & Profiles section of the Apple Developer Portal.

  2. In the side navigation, select Provisioning Profiles > All.

  3. Click on the + button in the top right to create a Provisioning Profile.

  4. Choose the iOS App Development type and click Continue.

  5. From the App ID dropdown, select the App ID you created earlier and click Continue.

  6. Select the Developer Certificate(s) that you want to use and click Continue.

  7. Select the Devices that you registered and click Continue.

  8. Provide a descriptive Name for the Provisioning Profile and click Continue.

  9. Click Download and open your Provisioning Profile.

    Note: When you open your Provisioning Profile, Xcode installs it without providing any confirmation. In a later step, you configure your Xcode app project to use this Provisioning Profile.

Configure your Push Dashboard

Follow these steps to navigate to the Push dashboard and then configure the service to talk to your device.

You can navigate to the Push dashboard using either Apps Manager or the Cloud Foundry Command Line Interface (cf CLI). Use the cf CLI instructions if you did not enable the Push Apps Manager errand when deploying Elastic Runtime.

  1. In a browser, navigate to apps.YOUR-SYSTEM-DOMAIN.

  2. Select the system org and the push-notifications space.

  3. Click the Services tab.

  4. Select the PCF Push Notification Service row and click the Manage link.

  1. Open a terminal window and log in:

    $ cf login -a https://api.YOUR-SYSTEM-DOMAIN -u USERNAME -p PASSWORD
  2. Target the correct org and space:

    $ cf target -o system -s push-notifications
  3. Run the following command:

    $ cf service push-service-instance
  4. Copy the URL from the Dashboard field and paste it into your browser.

Configure the Push Notification Service

  1. Select the Heartbeat App from the list of applications.

    Select app

  2. Select the Configuration pane.

    Select Config

  3. Under the Platforms section, in the Heartbeat iOS Platform row, click the pencil icon to edit the record.

    Edit Platform

  4. Complete the following fields:

    • MODE: Select Development from the dropdown menu.
    • CERTIFICATE: Click Choose File and upload the APNS certificate you created.
    • PASSWORD: Enter the password you used when creating your APNS certificate.

    Choose File

  5. Click Save.

Run the App on Your Device

Follow these steps to open the project for the Heartbeat Monitor iOS app in Xcode and run the app on your device:

Download the App Repo

  1. Clone the Push iOS Heartbeat Monitor repository:

    $ git clone git@github.com:cfmobile/push-ios-heartbeatmonitor.git
  2. Run the following command to open the Xcode project:

    $ open PCF\ Push\ Heartbeat\ Monitor.xcodeproj/

Configure the App Project

  1. In the Project Navigator, select the Pivotal.plist file.

    Project Navigator

  2. In the editor, change the value for pivotal.push.serviceUrl to the Push Notification API endpoint for your environment: https://push-api.YOUR-SYSTEM-DOMAIN.

    API URL

  3. Ensure that the values for the following Root fields in the editor match the corresponding values in the Push dashboard under the Heartbeat iOS Platform record:

    Root Field in Editor Platform Field in Push Dashboard
    pivotal.push.platformUuidDevelopment Platform UUID
    pivotal.push.platformSecretDevelopment Platform Secret

  4. Under the General tab, set the Provisioning Profile dropdowns to the profile you created earlier.

    Note: Do not select the checkbox to automatically manage signing.

    Enable Steps

  5. Under the Capabilities tab, ensure that both Steps are enabled for Push Notifications.

    Enable Steps

  6. If your PCF deployment does not use an SSL certificate signed by a Certificate Authority (CA), add an exception domain to the info.plist file by selecting App Transport Security Settings > Exception Domains and entering push-api.YOUR-SYSTEM-DOMAIN.

Build and Run the App

  1. At the top of the Xcode window, select the device icon and choose your device. Select device

  2. Click the play button to build and run the app on your device.

  3. Select Allow when the app asks if it can send you notifications.

    allow notifs

    The screen updates with a new heartbeat count every minute as it receives pushes from your environment.

    Note: If you send a test push to your device from the Push dashboard, ensure the app is not open on your device. You cannot see the test push while the app is open.

Create a pull request or raise an issue on the source for this page in GitHub