40

Set up push notifications

The Expo plugin supports push notifications over APN for iOS and FCM for Android. Use this page to get started with push notification services.

How it works

If you followed our quick start guide, you’re already set up to support push notifications, including images and deep links.

Before a device can receive a push notification, you must:

1. Identify a person. This associates a token with the person; you can’t send push notifications to a device until you identify the recipient.
2. (Optional) Set up your app to report push metrics back to Customer.io.

Before you begin

Before you follow this process, make sure you’ve configured the plugin!

You need to enable Customer.io to send push notifications through your preferred service: Apple Push Notification Service (APNs) and/or Firebase Cloud Messaging (FCM) before you can send push notifications through Customer.io.

Set up push for Android

You don’t need to do anything to support Android devices. When you use our Expo plugin, your Android audience is automatically set up to receive push notifications.

Set up push on iOS

For the most part, we’ll set up push notifications for you when you run expo prebuild. But before you can support push notifications for iOS devices, you need to add Push Notification capabilities to your project in XCode.

1. Open your React Native project in XCode, go to the ios subfolder and open <yourAppName>.xcworkspace.
2. Select your project, and then under Targets, select your main app.
3. Click the Signing & Capabilities tab
4. Click Capability.
5. Add Push Notifications to your app.

   

   

When you’re done, you’ll see Push Notifications added to your app’s capabilities. Now you’re ready to run the expo prebuild.

Update iOS dependencies

In some cases, we may make fixes in our iOS push packages that fix downstream issues in the Expo plugin. The command to update these packages depends on whether your Expo project uses a managed or bare workflow. For managed workflows, you can simply re-run the prebuild.

expo prebuild --clean
# the --clean option is optional

pod update --repo-update --project-directory=ios

Sound in push iOS push notifications

When you send a push notification to iOS devices that uses our SDK, you can opt to send the Default system sound or no sound at all. If your audience’s phone is set to vibrate, or they’ve disabled sound permissions for your app, the Default setting will cause the device to vibrate rather than playing a sound.

In most cases, you should use the Default sound setting to make sure your audience hears (or feels) your message. But, before you send sound, you should understand:

1. Your app needs permission from your users to play sounds. This is done by your app, not our SDKs. Here’s an example from our iOS sample app showing how to request sound permissions.
2. iOS users can go into System Settings and disable sound permissions for your app. Enabling the Default setting doesn’t guarantee that your audience hears a sound when your message is delivered!

If you use Expo Application Services (EAS)

If you build your app using Expo Application Services (EAS), and you have a managed project, you can simply add the code below to your app.json or app.config.js file.

"expo": {
    ...
    "extra": {
        "eas": {
            "build": {
                "experimental": {
                    "ios": {
                        "appExtensions": [{
                            "targetName": "NotificationService",
                            "bundleIdentifier": "${appIdentifier}.richpush"
                        }]
                    }
                }
            }
        }
    }
}

If you have a bare Expo project, you’ll need to follow the official Expo docs to set up code signing for the new Xcode target. The bundle ID of the new Xcode target is <app-bundle-id>.richpush where <app-bundle-id> is the bundle ID of your host iOS app (e.g. io.customer.super-awesome-store).

Prompt users to opt-into push notifications

Your audience has to opt into push notifications. To display native iOS and Android push notification permission prompts, you’ll use the CustomerIO.showPromptForPushNotifications method.

You can configure push notifications to request authorization for sounds and badges as well (only on iOS). If a user opts into push notifications, the CustomerIO.showPromptForPushNotifications method will return Granted, otherwise it returns Denied as a string. If the user already responded to the push authorization prompt, the current authorization status is returned as a string.

var options = {"ios" : {"sound" : true, "badge" : true}}
CustomerIO.showPromptForPushNotifications(options).then(status => {
  switch(status) {
    case "Granted":
     // Push permission is granted, your app can now receive push notifications
      break;
    case "Denied":
      // App is not authorized to receive push notifications
      // You might need to explain users why your app needs permission to receive push notifications
      break;
    case "NotDetermined":
      // Push permission status is not determined (Only for iOS)
      break;
  }
}).catch(error => {
  // Failed to show push permission prompt
  console.log(error)
})

Get a user’s permission status

To get a user’s current permission status, call the CustomerIO.getPushPermissionStatus() method. This returns a promise with the current status as a string.

CustomerIO.getPushPermissionStatus().then(status => {
  console.log("Push permission status is - " + status)
})

Fetch the current device token

You can fetch the currently stored device token using the CustomerIO.pushMessaging().getRegisteredDeviceToken() method. This method returns an APN/FCM token in a promise as a string.

   let token = await CustomerIO.pushMessaging().getRegisteredDeviceToken()
   if (token) {
    // Use the token as required in your app for example save in a state
        setDeviceToken(token);
   }

Test your implementation

After you set up rich push, you should test your implementation. Below, we show the payload structure we use for iOS and Android. In general, you can use our regular rich push editor; it’s set up to send messages using the JSON structure we outline below.

If you want to fashion your own payload, you can use our custom payload.

{
    "aps": {
        // basic iOS message and options go here
        "mutable-content": 1,
        "alert": {
            "title": "string", //(optional) The title of the notification.
            "body": "string" //(optional) The message you want to send.
        }
    },
    "CIO": {
        "push": {
            "link": "string", //generally a deep link, i.e. my-app:://...
            "image": "string" //HTTPS URL of your image, including file extension
        }
    }
}

{
  "message": {
    "data": {
      "title": "string", //(optional) The title of the notification.
      "body": "string", //The message you want to send.
      "image": "string", //https URL to an image you want to include in the notification
      "link": "string" //Deep link in the format remote-habits://deep?message=hello&message2=world
    }
  }
}