Features > Push Notifications

Push notifications are a powerful tool for enhancing user engagement and driving conversions. Personalized notifications increase interaction and retention, keeping your app top-of-mind.

In our boilerplate, we have integrated OneSignal for push notifications. We chose OneSignal due to its robust SDKs and ease of use. Additionally, for advanced usage, OneSignal offers services with segmentation and targeting that can significantly increase your conversion rate.

In this document, we will explain how to set up OneSignal. But before start, you need to have OneSignal, App Store Connect and/or Play Store Console set up.

OneSignal Setup

1. First, you need to create an account for free on OneSignal, if you didn't create one.

2. Follow their setup documents on Quickstart Guide

3. Visit your app's dashboard on OneSignal and click Settings → Keys & IDs from the left side panel.

4. Copy the OneSignal App ID. Paste the value on your mobile .env file EXPO_PUBLIC_ONESIGNAL_APP_ID=[PASTE YOUR ONESIGNAL APP ID]

5. Copy the OneSignal App ID and Rest API Key. Paste the values on your backend .env file ONESIGNAL_APP_ID=[PASTE YOUR ONESIGNAL APP ID] andONESIGNAL_API_KEY=[PASTE YOUR REST API KEY]

iOS Setup

An authenticated connection to Apple Push Notification Services (APNs) is required to send push notifications to all iOS mobile apps. You only need to use one authentication method, either token-based (.p8) or certificate-based (.p12).

Whether you use .p8 or .p12 certificates is up to you. Although the recommended method is .p8, you cannot have more than two .p8 certificates defined in your Apple account. You can follow one of the two documents below to complete the necessary setup steps for iOS.

p8 Authentication Token or p12 Push Notification Certificate

Android Setup

Unlike iOS, sending notifications to Android devices requires the use of Firebase Cloud Messaging (FCM) service. For configuration details, you should follow the OneSignal documentation linked below.

Android: Firebase Credentials

Backend Setup

From time to time, it may be necessary to trigger notifications to a user, a group, or all users as a result of certain events on the backend. This can be done using OneSignal APIs.

In our boilerplate, there are utility functions available to simplify this process. There is even a sample use case code provided. In an example scenario, when credits are added to a user's account, a notification is sent to the user saying "X credits added to your account."

Check your .env file

Ensure that the ONESIGNAL_APP_ID and ONESIGNAL_API_KEY environment variables are correctly configured for secure communication with OneSignal on the backend.

Code Examples

From time to time, it may be necessary to trigger notifications to a user, a group, or all users as a result of certain events on the backend. This can be done using OneSignal APIs.

Trigger on click on notification

mobile/utils/onesignal.ts

export const handleNotificationClick = (event: NotificationClickEvent) => {
    console.log('OneSignal: notification clicked:', event);
};

Trigger on notification when app is on foreground

mobile/utils/onesignal.ts

export const onBeforeNotification =
  async (event: NotificationWillDisplayEvent): Promise<void> => {
  console.log('OneSignal: notification will display:', event);
};

Decide if notification should shown when app is already on foreground

mobile/utils/onesignal.ts

export const shouldDisplayNotification =
  (event: NotificationWillDisplayEvent): boolean => {
  return true;
};

Request notification permission whenever you think is right

mobile/utils/onesignal.ts

export const requestNotificationPermission = () => {
  // Need enable notifications to complete OneSignal setup
  OneSignal.Notifications.requestPermission(true);
};

Send notification to user on backend

backend/functions/src/index.ts

import { sendNotification } from "./utils/onesignal";
...
sendNotification(userId, `${credits} credits added to your account!`, payload);
...