Push Notifications: Setting up APNs

All push notifications sent to iOS applications go via Apple’s APNs platform. Pusher uses APNs to deliver push notifications to your users on your behalf. When we deliver push notifications over APNs, we use your APNs credentials. This page guides you through the process of setting up an APNs account and creating a push certificate in order to send iOS push notifications.

This guide requires you to have a working Mac, as some steps use software for this platform.

Sign up for an Apple Developer Program membership

To send push notifications, you need to enroll in the Apple Developer Program. Visit the Apple Developer Program enrollment page. Follow the process to purchase an Apple Developer Program account. You will obtain an Apple account which is identified by your email address. You will need this email address later in the process.

screenshot of the Apple Developer Program enrollment page

Create a Vendor-Signed Certificate Signing Request

APNs uses a standard public-key infrastructure to identify senders and receivers on its platform. You are a sender, and in order to send push notifications you must identify yourself with a push certificate.

To generate a push certificate, you first need a Certificate Signing Request. This is a cryptographic document which contains information identifying you, and it contains your public key. You will give this document to Apple, and it tells them who to generate a certificate for.

You must generate your Certificate Signing Request from your Mac, which has access to your keypair. This is done with a standard OS X program called Keychain Access. Open Keychain Access.

screenshot of Keychain Access, with Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority... focussed

From the menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority …. This will bring up a wizard.

screenshot of Certificate Assistant wizard, with form completed as instructed

The wizard asks you for your personal details. These are the details which will be sent to Apple, and which will identify you in your resulting push certificate. Enter:

  • Your User Email Address should be the email address you used for your Apple Developer Program membership.
  • Your Common Name is your natural name like “Joe Bloggs”.
  • You can leave the CA Email blank (even if the field itself says it is “Required” - it is not).

The wizard asks what to do with the resulting Certificate Signing Request. Select “Saved to disk”. Save the file as ~/CSR.certSigningRequest.

At the end of this step, you should have a file which looks something like this:

% cat ~/CSR.certSigningRequest
-----BEGIN CERTIFICATE REQUEST-----
9i9WUfpOWsQg3ydxvHnB817o291u3FZk8cmzW3v8YBGkx0uEx6RgRXXI0XZ02XZK
09BffoPbuz545C7iZ7PBpDnSKsp5rjxP5rYDd3i5E5RMDY3urMd6X3NeSxa5T9KO
VJ+7oySpvBhPifePfbhfLx7tCZW8dw8WsSr+YKHUDlsS1fWcKv4eqivOZ8bB3VTF
svAjLcAbyKkKciFL8e/MXzJ5TQhr6I52NlFVI/QVCveZ2p87eh+3j37gQXXOWugd
vZ+5gpNxVUfxnZYEyVu6OPdO9byTPbhD5dsxK7UY2C0sWVxi/cBuetAGW56D5GgE
mBsz1iFF3pjwOSl389q5zpQRA7hTcgrkI12imisOsZUyVNA5kMkTeUWzApd6i/tO
G/D9uj/ADI2oGregWndXI2pjOupth2VdwzFuC58Qsc6Uwyl/7hRBf5oAEEkjGHJH
kAQhUZLJ935bAasWmme0DNXzvd5u4n5IIAJm5OQmda2ejKVKKbMXKOgqsXQgmzbo
+UfEBggWmF0pC/DwvlsugdDgv5VGgvc44iiVgVMdWpU05dZ5Z4ilWYSiMN3Hf7EO
MjBVsinc3NvyPX2Fn2IO0usPwJrpNusSOAUqGg1y47jOCzZ3tjs14Dj1Qtbvfeh+
LC//7iYDmWGtYxChWpEq7tc10PwGXBeyHKnCb3jK9VQSyHVw8p2PEhQKV6WHCD3P
CVyDeQoY+3uIslkfNJq3ATnthz1x5OPiQ98BuqbQQMTDNeg1bvXl+J1JeGuQ2Duj
9eCmIVrpIgC3o8LWBqiAK+eyxbn9eq5ROlPwi8XPyQnOFUCupGD4kMBHXoX2UnPa
n2CBFDCIAQ65z290QnQrXMhIuPudUDi8RgccZqtPa/1LDM4ajA==
-----END CERTIFICATE REQUEST-----

Create an App ID

Your iOS app will be identified by an “App ID”. A push certificate is specific to one App ID. If you don’t already have an App ID, you will need to create one.

You create App IDs using the Apple Developer Member Center. Make sure you are signed in with your Apple Developer Program account.

In the sidebar, select Identifiers > App IDs.

screenshot of App ID page in Apple Developer Member Center

Click the + button to create a new App ID. This will ask you for:

  • An App ID Description. Enter a human name, like “My Push App”.
  • An App ID Suffix. Choose “Explicit App ID”. (The alternative, a “Wildcard App ID”, does not support push notifications.) For your Bundle ID, use a “reversed domain” string for your company’s domain, e.g. com.yourcompany.yourapp.
  • Under App Services, check “Push Notifications”. You may also check any other services you wish to use.

screenshot of 'Registering an App ID' page in Apple Developer Member Center with form completed

Click Continue. This takes you to a page describing your new App ID. Ensure that “Push Notifications” says “Configurable”.

screenshot of 'Confirm your App ID' page in Apple Developer Member Center with 'Push Notifications' set to 'Configurable'

Click the Register button. You are now told “This App ID is now registered to your account and can be used in your provisioning profiles.”

screenshot of 'Registration Complete' page in Apple Developer Member Center for App ID 'com.yourcompany678.yourapp' with 'Push Notifications' set to 'Configurable'

Click Done. Your new App ID should now be listed in the table under Identifiers > App IDs.

screenshot of App ID page in Apple Developer Member Center, with new app 'Your App' in list

Create a certificate

Now you have an App ID with push notifications enabled, you can request a certificate for that App ID. Still in the Apple Developer Member Center, go to the list of App IDs under Identifiers > App IDs, and select the App ID you just created.

Under the list of Application Services for that app, you see an “Edit” button. Click the Edit button.

screenshot of App ID page in Apple Developer Member Center, with app 'Your App' expanded, showing its list of Application Services, including Push Notifications set to 'Configurable'

You again see a list of Application Services. Scroll to the “Push Notifications” service. You see a table with options for a “Development SSL Certificate” and for a “Production SSL Certificate”.

screenshot of App ID Settings page in Apple Developer Member Center for app 'Your App', showing table of certificates for Push Notifications

Create a Production SSL Certificate. (We recommend this instead of a Development/Sandbox certificate. A Production certificate is strictly more powerful than a Development certificate). Click “Create Certificate…“ in the Production section of the table. You are taken to a page telling you to create a CSR file. Click Continue.

screenshot of 'About Creating a Certificate Signing Request' page in Apple Developer Member Center

Now click “Choose File…” and select the ~/CSR.certSigningRequest file you created earlier. Click Continue.

screenshot of uploading ~/CSR.certSigningRequest file to Apple Developer Member Center

You are told “Your certificate is ready”, and there is a “Download” button. Click the Download button, and save your certificate as ~/certificate.cer.

screenshot of page 'Your certificate is ready' with a Download button in the Apple Developer Member Center

From Finder, double-click the ~/certificate.cer file, or run open ~/certificate.cer. This will open Keychain Access. The certificate should now be added to the list under “My Certificates”.

Expand the certificate to show the associated private key. Right-click the private key.

screenshot of certificate in Keychain Access

Right-click the key, and choose “Export”. Save the file as ~/certificate.p12. Encrypt the key with a blank password. (Note: You may be asked for your system password to complete the export.)

screenshot of certificate in Keychain Access

The contents of this file are encoded in the PKCS 12 format. Pusher requires you to upload a certificate in the PEM format. We therefore need to convert your file to this format. You can do this using the openssl tool. From the command line, run:

openssl pkcs12 -in ~/certificate.p12 -out ~/certificate.pem -nodes -clcerts

This will create a new file ~/certificate.pem. It should look something like this:

% cat ~/certificate.pem
Bag Attributes
    friendlyName: Apple Push Services: com.yourcompany.yourapp
    localKeyID: 27 06 E2 22 89 D2 F1 AA 12 45 67 78 89 12 A2 A3 A4 B1 12 89
subject=/UID=com.yourcompany.yourapp/CN=Apple Push Services: com.yourcompany.yourapp/OU=H73L4F4DAW/O=Pusher Ltd/C=US
issuer=/C=US/O=Apple Inc./OU=Apple Worldwide Developer Relations/CN=Apple Worldwide Developer Relations Certification Authority
-----BEGIN CERTIFICATE-----
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
svaOzfjMy3V2vMSfqyPe
-----END CERTIFICATE-----
Bag Attributes
    friendlyName: Joe Bloggs
    localKeyID: 27 06 E6 33 23 24 25 56 12 23 A2 F3 BD E3 93 80 64 AA BB CC
Key Attributes: <No Attributes>
-----BEGIN RSA PRIVATE KEY-----
3iX1O+jHgderx0nrFHQjAEjRFZuBtqUXk9do1icbWYWlCFxUA7JGV7lLvQXNEYJY
Np/JOeIH5O4/4PfgFf6e83WNTHxaQS1UxyJBZSenJxhdHH2giOL9jnHhw6TpqAPx
00H9JbpP7QrBqSBaXJzw87cUugulakUg/qE2GkuB+qFXBkEqmp2ZRWOS8uo/Ih3d
K7sd6io8I9YVu8RtVubPvXUQBCFWVwEDvWpWnbFY6BTbqoZiVLR4T6xsbaXGF3KN
AqKQRQ42WD673RVAQJ8QnkSZnthZxnswWKU33Pvrq1dU2mZ0a2dTF3QVEAuEQhfC
KrpQbCsZ+MW82daZ8PzrScilKsThQjoagkJKW4PnBRVMmkHO9KPtSB2u/5OWKgAt
GmUT96xy/KRhAoEWNCdtCEhp49EOwmH/ihKkm8lAICkwAuwMQD/UQESVhVoEY/aJ
b+tj6ZFJZ24S5nWYWVezwnKKNL+zJwbW9gEtjQyKbbCwwHCrgRYLLxFny8WqOwo5
rVB9HcWNXEpfbcMjGfqnpvjeb/9RXx7WlM4grAau3b9liekfW3Lipt38zPfUJXOk
RL2hierg2DGpVjR1sQVsZqTVNlsmJLMcXdnUN0kaMEthiloDeXRM/oFwYUSb7Yvq
t4PRex1hSfQORbYl6HpJBvVHHSN/fjYzvqqLZURFTmr6TynjBI6p9mpxwZ9G3kte
HCeL0LhFuJbk/n9f5gJ+P3JY6S/7WnB+zIa9bIuLUzF4mgpPTaAdw1JushFyMKDp
kvYOTLWPK6B0NCU4q5JEQ1i7UTpRqF1WiuYdJ1+zA9G4ZIfuaVaKlAIOm/L19X1S
1gItBimJ0dXwlZajyMAiCvxSfm0DZXdspSd+Ci5WyWXAnMs5NoGMGftPGI/Z1IuL
BP3lKN6qTOtaGDW9qE37KqddGEf8bjY7PvWRDfeyQsF5CRJL42SN7/AzEelHT9qG
/ToiVTCtA9ky93NpM4R4AO2ykFvxBEcshYKdSp5HNjP4fmiSNaGGGhoYSI8XkyjV
NwvqmVxn2PXHunp/U4nD3q4Wdif39LEqISIjy1RJtugf7NrabEXrg51UwU+WK/cA
ekC+zfD7WIQSPYGMh9pzTdZQ06j29CPtjA9/jYDQevefAwNGFe85wqgkLFcwGD6o
/evXlaSVWUeuYurb8zVPc1ZNlVNg+pLrHB7tCyIc2+wZ3Jiblqs9bcYpGCBL78hS
eD9Cg4Ggv+2ObDMAiSE1ZZ8WbtMNfyd9I12t9OSwWFIrwCHa80nhTt1NrnGfbMUP
sibj5mQ11olhA+EokMqxBezPGyctCC3b6hZVsd+8KSO7Amp4QfSujKmLsWQXsFtO
5icN2VT6XlDBGoz1Q1MBdwxYuYva70IAwjFrGIVNCltlrqJO/oaOa/uva4zH+6bn
LORok57khUFcSBxx/yAFDsELTLJ920e+zCcr0y1LMLePsKhkgDBoUguzmruaMqtd
gJp0y9Y3u1nuK92GiSaxE44IP0aAAO2tQ1LnAKmDOxEHk5hM7A1Ve+6wO9WXKXJ6
Nr2V7WjT7+pE5vnF3sDzsvT3c7pLwLbSoJJba3BJpzzdLom4eQek+A==
-----END RSA PRIVATE KEY-----

It is this file which Pusher requires. Let’s upload it!

Upload your certificate to our Dashboard

You should have a Pusher app which you want to use Push Notifications with. If not, create a new Pusher app.

Visit dashboard.pusher.com and sign in with your Pusher account.

In the dashboard for your Pusher app, go to the Push Notifications tab.

On the Push Notifications tab, click the “Configure APNs” tab.

You are asked to select between “Development” and “Production”. This selects which APNs host we will use to deliver your push notifications. For now, choose “Development”, which will let you push to development versions of your app (but not to versions published to the App Store). See below for more information.

Click the button “Choose a file …” and choose your ~/certificate.pem file to upload. Click “Upload”.

You’re done! Next, let’s set up your iOS app to receive some push notifications!

Understanding “Development vs. Production”

There are two orthogonal Development/Production choices to be made:

  1. Push certificate type. Push certificates are marked as either “Development” or “Production”. You decide which when you create the certificate.
  2. APNs host. Apple operates two separate APNs systems, named “Development” and “Production”. You decide which Pusher uses when you configure your app in the dashboard.

Which type of push certificate should I create?

The two APNs hosts differ in which type of push certificate they accept:

Development APNs host Production APNs host
Development push certificate OK Not accepted
Production push certificate OK OK

As this table demonstrates, a Production push certificate is strictly more powerful than a Development push certificate: a Production push certificate “always works”. For this reason, we recommend always creating a Production push certificate.

Which APNs host should I choose in the dashboard?

The choice of APNs host depends on which kinds of iOS app you wish to send push notifications to. There are two kinds of iOS app:

  • Published apps. These are published to the App Store and installed from there. These apps go through the usual App Store publication process, such as code-signing.
  • Development apps. These are “everything else”, such as apps installed from XCode, or through private app publication systems.

The two APNs hosts differ in which kind of app they will send push notifications to:

Development APNs host Production APNs host
Published App Store apps Not accepted OK
Development apps OK Not accepted

As this table demonstrates, there is no single best choice of APNs host: they each send notifications to a separate kind of app. We therefore recommend the following strategy:

  1. When starting out, create a “development” Pusher app and choose the Development APNs host. You will be able to publish to your apps while developing.
  2. Once you decide to publish your app to the App Store, create a separate “production” Pusher app and choose the Production APNs host. If you created a Production push certificate, you may re-use it in your production Pusher app.

Further reading

Ray Wenderlich’s guide to getting started with push notifications

Google’s guide to generating APNs certificates

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.