@convex-dev/expo-push-notifications

Convex Push Notifications Component

This is a Convex component that integrates with Expo's push notification API to allow sending mobile push notifications to users of your app. It will batch calls to Expo's API and handle retrying delivery.

Demo GIF

Example usage:

// App.tsx
<Button
  onPress={() => {
    void convex.mutation(api.example.sendPushNotification, {
      to: otherUser,
      title: `Hi from ${currentUser.name}`,
    });
  }}
>
  <Text>Say hi!</Text>
</Button>

// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.id("users") },
  handler: async (ctx, args) => {
    // Sending a notification
    return pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});

Pre-requisite: Convex

You'll need an existing Convex project to use the component. Convex is a hosted backend platform, including a database, serverless functions, and a ton more you can learn about here.

Run npm create convex or follow any of the quickstarts to set one up.

Installation

Install the component package:

npm i @convex-dev/expo-push-notifications

Create a convex.config.ts file in your app's convex/ folder and install the component by calling use:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import pushNotifications from "@convex-dev/expo-push-notifications/convex.config.js";

const app = defineApp();
app.use(pushNotifications);
// other components

export default app;

Instantiate the PushNotifications client in your Convex functions:

// convex/example.ts
import { PushNotifications } from "@convex-dev/expo-push-notifications";

const pushNotifications = new PushNotifications(components.pushNotifications);

It takes in an optional type parameter (defaulting to Id<"users">) for the type to use as a unique identifier for push notification recipients:

import { PushNotifications } from "@convex-dev/expo-push-notifications";

export type Email = string & { __isEmail: true };

const pushNotifications = new PushNotifications<Email>(
  components.pushNotifications,
);

Registering a user for push notifications

Get a user's push notification token following the Expo documentation here, and record it using a Convex mutation:

// convex/example.ts
export const recordPushNotificationToken = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    await pushNotifications.recordToken(ctx, {
      userId,
      pushToken: args.token,
    });
  },
});

You can pause and resume push notification sending for a user using the pausePushNotifications and resumePushNotifications methods.

To determine if a user has a token and their pause status, you can use getStatusForUser.

Send notifications

// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.string() },
  handler: async (ctx, args) => {
    const pushId = await pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});

You can use the ID returned from sendPushNotifications to query the status of the notification using getNotification. Using this in a query allows you to subscribe to the status of a notification.

You can also view all notifications for a user with getNotificationsForUser.

Troubleshooting

To add more logging, provide PushNotifications with a logLevel in the constructor:

const pushNotifications = new PushNotifications(components.pushNotifications, {
  logLevel: "DEBUG",
});

The push notification sender can be shutdown gracefully, and then restarted using the shutdown and restart methods.