Push Notifications: Setting up APNs
Our Push Notifications system is currently in beta. This means you may experience errors, and the APIs may change. We would love to hear your feedback, so please get in touch!
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.
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.
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.
From the menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority …. This will bring up a wizard.
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
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-----
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.
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.
- Under App Services, check “Push Notifications”. You may also check any other services you wish to use.
Click Continue. This takes you to a page describing your new App ID. Ensure that “Push Notifications” says “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.”
Click Done. Your new App ID should now be listed in the table under Identifiers > App IDs.
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.
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”.
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.
Now click “Choose File…” and select the
~/CSR.certSigningRequest file you created earlier. Click Continue.
You are told “Your certificate is ready”, and there is a “Download” button. Click the Download button, and save your certificate as
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.
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.)
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!
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!
There are two orthogonal Development/Production choices to be made:
- Push certificate type. Push certificates are marked as either “Development” or “Production”. You decide which when you create the certificate.
- 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.
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.
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:
- 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.
- 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.