Sending Push Notifications with GraphQL & Scaphold

Easily send push notifications using Scaphold’s GraphQL API.

Published in

Scaphold

7 min readFeb 14, 2017

At Scaphold, we’ve talked to thousands of people from all walks of GraphQL life, and discovered that mobile is the next frontier for GraphQL tooling. Apollo has already done a wonderful job of strengthening the community with Apollo Client for iOS and Android. And there’s certainly more to come.

We’re joining the mobile effort!

… With more GraphQL support for iOS and Android push notifications on Scaphold. In this guide, we’ll show you how to send push notifications with a GraphQL API built to the open standard that works with both Apollo and Relay on any client platform.

Configuring Push Notifications with GraphQL

Before we begin, you’ll have to have configured your push notification keys for APNS and/or GCM depending on which platform you’re using. Because it’s not the most straightforward process to set up all these accounts and keys for your app on Apple or Google, we’ve also written up step-by-step guides for you to help you get started that fit seamlessly with what we do here today.

If you have these tokens already, but don’t have a GraphQL server at your disposal, the quickest way is to sign up for free on Scaphold and create an app. You’ll instantly have a GraphQL server deployed for you, and you’ll need to enable the integration for the appropriate platform where you’re trying to send push notifications. The aforementioned setup guides will show you how.

Now that we’re on the same page, let’s begin. The process for sending push notifications in any workflow starts with your device token. It’s a unique identifier for your app on your device specifically. This is how APNS and GCM, or any other push notification hub for that matter, understand where to send your push notifications to.

💌 Think of a device token as a mailing address for push notifications.

This means that we’re going to have to register each device token that’s created on a particular device with Apple or Google, so that they have a registry of valid device tokens for our app.

We’ll be using these working boilerplates for the remainder of this tutorial:

1. Registering Device Tokens & Users.

Run your app and make sure you generate a device token. The boilerplate will have this printed out in the console. It will look something like this:

iOS

Android

Associate Token with a Valid User

In order to use the device token to send a push notification, it’s important that we associate a device token with a user in the app.

This is needed since let’s say that User A wants to send a push notification to User B. The problem is that User A will only have context of its own device token, but not the device token of User B. However, User A will most likely have the user ID of User B, so we can send a push notification User B in that manner, so long as User B has a valid device token associated to that person.

In order to accomplish this, we must login first to obtain the user’s authentication credentials.

// Mutationmutation LoginUser ($user: LoginUserInput!) {
  loginUser(input: $user) {
    token
    user {
      id
      username
    }
  }
}// Variables{
  "user": {
    "username": "elon@spacex.com",
    "password": "SuperSecretPassword"
  }
}

The result of this mutation will provide an authentication token that you will need to set as the Authorization header for future requests.

Thus, when we run the createDeviceToken mutation, the GraphQL server will know to connect the new device token with this particular user.

Then, we run the createDeviceToken mutation to register the device token with APNS or GCM through our GraphQL server.

// Mutationmutation CreateDeviceToken($input: CreateDeviceTokenInput!) {
  createDeviceToken(input: $input) {
    changedDeviceToken {
      id
      token
      user {
        id
        username
      }
      platform
      createdAt
    }
  }
}// Variables{
  "input":  {
    "token": "<YOUR_DEVICE_TOKEN>",
    "platform": "APNS_DEV" // or GCM
  }
}

The GraphQL server understands that if the token was created already, the existing token instance will update instead of create a new one. Associating a token with a valid user can all be done in one step. Typically, following the login flow for your app, you should send an authenticated request to create the device token object on the server. This will create the token and associate the user altogether like above, so long as you have a valid authentication token in the header of your request.

Now with this device token registered and associated to a user, we can start sending push notifications!

Send Push Notification to User

Since we rarely know what the device token is for another user, Scaphold abstracts away the association of device token to user, meaning from your client app with User A, you can send a push notification to User B only knowing that person’s user ID.

This is a direct way of sending push notifications to a single user. Run this GraphQL mutation to send a push notification:

// Mutationmutation SendToUser($notif: SendPushNotificationToUserInput!) {
  sendPushNotificationToUser(input: $notif) {
    changedPushConfirmation {
      status
      message {
        APNS_DEV {
          alert {
            title
            body
          }
          badge
        }
        GCM {
          title
          body
          badge
        }
      }
    }
  }
}// Variables{
  "notif": {
    "userId": "VXNlcjox", // ID of User B
    "message": {
      "APNS_DEV": {
        "alert": {
          "title": "New Message from Elon Musk",
          "body": "Hey what's up Zuck?"
        },
        "badge": 1
      },
      "GCM": {
        "title": "New Message from Elon Musk",
        "body": "Hey what's up Zuck?",
        "badge": "1"
      }
    }
  }
}

Nice! You just sent your first push notification with GraphQL!

So what just happened?

We sent a notification to both APNS and GCM so that any device from either platform associated with that user ID will receive the message.

The way that each app receives notifications is through broadcast listeners.

For iOS, the listener method is called: didReceiveRemoteNotification in the AppDelegate file.

And on Android, the method is called: onReceive for the class that extends a BroadcastReceiver.

Bonus: We’ve included a mutation that allows you to send push notifications to a list of users all in one request with a list of their user IDs. 🙌

2. Managing Push Channels (Groups).

Often times, you’ll want to send push notifications to a group of people.

Perhaps if you’re running Facebook Messenger. Each time a new chat message is sent to a chat group, you’ll want each person in that group to receive a notification that someone sent a new message, waiting to be read.

Create Push Channel

In this case, we’ve provided the ability to create and manage push notification channels for your app. These are unique by name. In the Facebook example, a new push channel would be created when a user decides to create a new chat group with his/her friends.

// Mutationmutation CreateChannel ($channel: CreatePushChannelInput!) {
  createPushChannel(input: $channel) {
    changedPushChannel {
      id
      name
    }
  }
}// Variables{
  "channel": {
    "channelName": "Zuck_Family"
  }
}

But the channel (group) is still empty, so sending a push notification to this channel won’t go to anyone right now.

Subscribe to a Push Channel

In order for a user to be part of this new push channel, a user needs to subscribe to the channel.

// Mutationmutation Subscribe ($subscribe: SubscribeDeviceToChannelInput!) {
  subscribeDeviceToChannel(input: $subscribe) {
    changedDeviceToken {
      token
      user {
        username
      }
    }
  }
}// Variables"subscribe": {
    "token": "<YOUR_DEVICE_TOKEN>",
    "channelName": "Zuck_Family"
  }
}

Now that we’ve subscribed ourselves to Zuck’s family’s group chat thread 😂 we can start receiving push notifications whenever this channel is sent a new message. Currently, there’s only one member in this group, but of course we can keep adding more users.

Send Push Notification to Channel

Let’s send a push notification to everyone who’s subscribed to this channel in one request.

// Mutationmutation SendToChannel ($msg: SendPushNotificationToChannelInput!) {
  sendPushNotificationToChannel(input: $msg) {
    changedPushConfirmation {
      status
      message {
        APNS_DEV {
          alert {
            title
            body
          }
          badge
        }
        GCM {
          title
          body
          badge
        }
      }
    }
  }
}// Variables{
  "msg": {
    "channelName": "Zuck_Family",
    "message": {
      "APNS_DEV": {
        "alert": {
          "title": "New Message from Priscilla",
          "body": "Where are the kids?"
        },
        "badge": 1
      },
      "GCM": {
        "title": "New Message from Priscilla",
        "body": "Where are the kids?",
        "badge": "1"
      }
    }
  }
}

Neat! We just sent a message to the Zuck family group chat.

The result appears just the same as if the message were sent individually from one user to another.

Great job 🎉! You’ve now learned how to send push notifications through GraphQL and set up your GraphQL server to handle this workflow in a flexible way.

You can take these practices of setting up a push notification system to your own GraphQL backend, but we can guarantee that Scaphold makes it easier for you since you won’t have to create an entirely new GraphQL server from scratch, manage device tokens and associations to user, let alone coordinate subscribing to channels.

Enjoy how easy that was to set up a GraphQL server for iOS and Android push notifications? Join Scaphold today!

And be sure to follow us on Twitter and join our Slack for more awesome ways to learn about how to quickly launch your next app with GraphQL!