edit

Step-by-step guide on setting up Apple push notifications for your GraphQL backend

GraphQL and Apple Push Notifications

Calling all iOS mobile developers! Today, we’re going to walk you through how to set up Apple push notifications for your GraphQL server.

It’s about time for mobile to get some GraphQL love. ❤️

We’re going to cut right to the chase with the 4 steps to get you set up right away with iOS push notifications.

Prerequisite: You must have an Apple Developer Account and an actual iOS device configured for development. Learn how to configure your device here.

1. Create and register your iOS app.

We’re going to start off by creating an iOS app. To make it easier for you, we’ve provided a starter kit that goes along with this guide.

Download the starter kit here.

Once we’ve created the app, we’ll want to add it to the Apple Developer Center.

First, under Targets > General, ensure that your Bundle ID is unique.

Update Bundle ID

Next, under Targets > Capabilities, enable Push Notifications.

Enable Push Notifications

Once this happens, you’ll have an App ID associated with your Apple Developer profile that has push capabilities.

Registered App ID

2. Obtain certificates (APNS SSL Certificate & App Private Key).

Here, you’ll be creating certificates to configure your GraphQL server for sending mobile push notification messages.

APNS SSL Certificate

Go to the Apple Development Center to create a certificate. You can create two types of SSL certificates (Production & Development). We’ll create a Development version for this tutorial.

Provision_SSL_Cert_1

Follow along and select the correct App ID associated with your app.

Provision_SSL_Cert_2

Using Keychain Access on your computer, follow the instructions on the next page to request a certificate from a certificate authority. Define an email address and name for your key. Leave the “CA Email Address” field blank.

Provision_SSL_Cert_3

Upload the CertificateSigningRequest.certSigningRequest file that was just downloaded on the next screen.

Provision_SSL_Cert_4

After successful completion of these steps, make sure you download your generated .cer file.

Now, convert the APNS SSL certificate from .cer format to .pem format. Using the openssl utility on your computer, run this command in your terminal. Be sure to replace mynsappcert.cer with the name of the certificate you downloaded from the Apple Developer site.

1
openssl x509 -in myapnsappcert.cer -inform DER -out myapnsappcert.pem

Hold onto your SSL certificate (.pem file) for use later.

App Private Key

In order to create an app private key that’s associated with your SSL certificate, you should export it from the Keychain Access application on your computer. Be sure you’re exporting the private key.

Provision_Private_Key_1

Create a password for your private key and save it as a .p12 file format.

Provision_Private_Key_2

After downloading the private key, run this command to convert the app private key from a .p12 format to a .pem format. Again, be sure to replace mynsappcert.cer with the name of app private key you just created. You’ll also be prompted to type in the password you created a minute ago for your private key.

1
openssl pkcs12 -in myapnsappprivatekey.p12 -out myapnsappprivatekey.pem -nodes -clcerts

Verify

You can verify that your APNS SSL certificate (.pem) and your App Private Key (.pem) are valid by connecting them to APNS.

Run this command to do so, and as always, ensure that you’re using your own key names.

1
openssl s_client -connect gateway.sandbox.push.apple.com:2195 -cert myapnsappcert.pem -key myapnsappprivatekey.pem

If successful, you should get a response that completes with:

1
Verify return code: 0 (ok)

Good work. ✅

3. Integrate your GraphQL server with APNS.

Now, it’s time to connect your GraphQL server with APNS so that you can actually send push notifications.

To make it easy, Scaphold.io provides an easy way to set up your very own GraphQL server for free in minutes. Sign up for an account and create an app. At this point, you instantly have a GraphQL server deployed in production, ready to make requests.

Now, go to Scaphold’s Integrations Portal to enable iOS push notifications for development. Click Add to begin.

Create_Integration_1

A form will then pop up, asking for your SSL Certificate file and your App Private Key file. Drop them into the appropriate boxes and hit Create.

Create_Integration_2

Good job! You’ve now connected your GraphQL server to be able to send push notifications to devices with your app installed.

4. Obtain a device token to send push notifications.

In order to send a push notification to a device, we need to generate a device token that is a unique identifier for a device and an app together. In that case, we’ll need to install your app onto an actual Apple device.

But first, we need to create an event handler to receive the device token once a user permits the app to send push notifications to their phone. In your app, you’ll need to put the following snippet in your AppDelegate file:

1
2
3
- (void)application:(UIApplication*)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
    NSLog(@"deviceToken: %@", deviceToken);
}

We’re going to be using the boilerplate code from earlier to illustrate.

Now install your app on your Apple device by pressing the big ▶️ button in the top bar of Xcode.

Note: An actual device is needed since the simulator is transient and cannot have a device token associated to it.

Allow_Push

Once the app is installed and run, you’ll get a notification that prompts the user to allow push notifications to be sent to the device. And surely, hit Allow.

Upon success, your device token will be issued by APNS and printed out in your Xcode console.

Device_Token

Save this device token and send it to Scaphold to register it on your behalf with APNS. This take the form of sending a GraphQL mutation from your app, but for demonstration purposes, we’ll use GraphiQL to do so.

Create_Device_Token


Congratulations! You’ve successfully configured your app and device to be able to send and receive iOS push notifications. And the best part is that it was all done with GraphQL.

Now that your GraphQL server is set up for iOS push notifications, the next part of this guide will walk you through how to...

  • Send push notifications
  • Associate users to device tokens
  • Manage push channels (i.e. groups)

Thanks for following along! We'll walk you through sending your first push notification with GraphQL in the next part of this tutorial.

Looking for how to set up Android push notifications with GCM? Follow along here!

Enjoy how easy that was to set up a GraphQL server? Join Scaphold today! And be sure to follow us on Twitter or join our Slack for more awesome ways to learn about how to quickly launch your next app with GraphQL!