@convex-dev/expo-push-notifications
v0.1.2
Published
A Convex component for managing push notifications with Expo.
Downloads
138
Readme
Convex Push Notifications Component
Note: Convex Components are currently in beta.
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.
// 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/component/convex.config";
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.