# Check Subscription Status
Source: https://docs.pushbase.dev/check-subscription-status
Determine if a device is currently subscribed to push notifications.
Pushbase SDK provides a function to determine if the device is already subscribed or not. This is helpful to decide if your app can request to subscribe or not.
```jsx theme={null}
// Import function
import { isSubscribedToNotifications } from "@pushbase/sdk";
// Later in your code
const isSubscribed = await isSubscribedToNotifications();
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Deep linking
Source: https://docs.pushbase.dev/deep-linking
Route users to specific screens on tap
Prerequisite: To enable deep linking, you must define your app’s scheme in the
`app.json` file.
```json app.json theme={null}
{
"expo": {
// replace this with your app scheme
"scheme": "myapp"
}
}
```
The Pushbase SDK supports deep linking, provided that the route is defined according to your app’s navigation structure.
To navigate a user to a specific screen via a notification, include the target route in the notification payload. When deep linking is enabled, the SDK automatically handles routing the user to the specified screen upon interaction.
To illustrate how deep linking works with the Pushbase SDK, consider a travel app that lists hotels across major U.S. cities.
Suppose the marketing team wants to send push notifications featuring city-specific discount codes. When a user taps on a notification, the app should automatically navigate to the targeted city and display a list of hotels specific to that location.
To enable this deep linking behavior, the app’s file structure should be organized based on the navigation strategy being used— **Expo Router** or **React Navigation**. Each approach requires a different configuration to correctly handle and route deep link URLs to the targeted screen.
```yaml Expo Router Project structure theme={null}
.
└── app/
├── _layout.tsx
├── destinations/
│ └── [slug].tsx
└── index.tsx
```
`destinations/[slug]` is a dynamic route, where `slug` is a unique identifier
representing each city's route.
```yaml React Navigation Project structure theme={null}
.
├── screens/
│ ├── HomeScreen.tsx
│ └── DestinationScreen.tsx
└── App.tsx
```
Screen route names and configurations in React Navigation are managed using a
[Stack Navigator](https://reactnavigation.org/docs/stack-navigator/)
```jsx App.tsx theme={null}
import { NavigationContainer } from "@react-navigation/native";
import { createStackNavigator } from "@react-navigation/stack";
const Stack = createStackNavigator();
export default function App() {
return (
);
}
```
## Defining deep links
A deep link to a specific destination screen should
follow this format:
- `destinations/san-francisco` - San Francisco
- `destinations/new-york-city` - New York City
- `destinations/miami` - Miami
- `destinations/washington-dc` - Washington DC
All deep links are configured and attached to notifications directly through the Pushbase dashboard.
**Create a deep link**
**List of deep links**
**Assign deep link to a notification**
## Handle Deep Link Routing
With Expo Router, Pushbase SDK automatically handles deep link navigation when a user taps on a notification that includes an assigned deep link. No extra works needed.
React Navigation’s [linking configuration](https://reactnavigation.org/docs/navigation-container#linking) can be used to handle incoming deep links from push notifications.
This involves mapping defined deep link routes to their corresponding screen route names within your navigation structure.
**Prerequisite**: install `expo-linking` package.
```bash theme={null}
npx expo install expo-linking
```
```js theme={null}
import { NavigationContainer } from "@react-navigation/native";
import { createStackNavigator } from "@react-navigation/stack";
import * as Linking from "expo-linking";
const Stack = createStackNavigator();
/* Map deep linking route to screen name.*/
const config = {
screens: {
// The slug value will be replaced by city value like san-francisco or miami.
Destination: "destinations/:slug",
},
};
const linking = {
prefixes: [prefix],
config,
};
export default function App() {
return (
);
}
```
The reason that is necessary to use `Linking.createURL` is that the scheme
will differ depending on whether you're in the client app or in a standalone
app
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Import devices
Source: https://docs.pushbase.dev/import-devices
Import Subscribed Devices from Existing Records.
If your app already has production users, Pushbase provides an API to seamlessly import your existing subscribed devices. This allows you to begin sending push notifications to those devices directly from the Pushbase Dashboard.
### Preparing Device Data for Import
To enable device segmentation and targeting in Pushbase, each device must conform to the following format.
Only the following properties are required: `platform`, `country`, `language`, `timezone`, and `expo_push_token`.
```ts theme={null}
interface Device {
/** One of React Native mobile supported OS
* @see https://gist.github.com/pushbasedev/5bf3c4ad6874d953d6399796cd0c282e
* */
platform: Platform;
/**
* Alpha-2 valid country code
* @see https://gist.github.com/pushbasedev/ab8046f6fe04de143e5500f0d9ce7e7f
*/
country: CountryCode;
/**
* Alpha-2 valid language code
* @see https://gist.github.com/pushbasedev/07be3c9c3cb416bc5d09c78bd2554fd1
*/
language: Language;
/**
* A valid timezone identifier
* @see https://gist.github.com/pushbasedev/f2275af1af486fb694de7e835d9c9e6a
*/
timezone: Timezone;
/** Subscription tier */
tier: "free" | "pro" | "enterprise";
expo_push_token: string;
device_push_token?: string;
manufacturer?: string;
model?: string;
brand?: string;
os_name?: string;
os_version?: string;
region?: string;
city?: string;
latitude?: string;
longitude?: string;
/* Unique Id from your database to identifier device owner */
external_id?: string;
/* User name from your database to identifier device owner */
external_name?: string;
/* Email from your database to identifier device owner */
external_email?: string;
/* Phone from your database to identifier device owner */
external_phone?: string;
/* When set true, this device will be used for push testing*/
is_tester?: boolean;
}
```
Follow example below on how to use our REST API to import devices for subscription.
```js theme={null}
const API_URL = "https://api.pushbase.dev/devices/import";
const API_KEY = "YOUR_API_KEY"; // Available in Pushbase dashboard app setting section
const myHeaders = new Headers();
myHeaders.append("x-api-key", API_KEY);
myHeaders.append("Content-Type", "application/json");
/* Replace this with the subscribed device records from your existing database.
*
*/
const devices = [
{
/* Required properties*/
platform: "ios",
country: "PL",
language: "PL",
timezone: "Europe/Warsaw",
expo_push_token: "ExponentPushToken[VSdTS398767-876hSpj4Aoc9]",
/* Optional properties*/
device_push_token: "c5b8u2adQjqey4fmIP8UYN:APA91bHiAM88JhhaYrLm9h9DKRzOdNAs3LIk6..."
tier:"free"
/* Location specific */
region: "Mazowieckie",
city: "Warsaw",
latitude: "52.237049",
longitude: "21.017532",
/* User identity*/
external_id: "cd23bf3c-bddf-431d-9145-d9b41fcecdcd",
external_name: "Maria Curie",
external_email: "marie-curie@kva.se",
external_phone: "08-673 95 00",
/* Device specific*/
manufacturer: "Apple",
brand: "Apple",
model: "iPhone 16",
os_name: "iOS",
os_version: "26.0",
},
{
platform: "android",
country: "US",
language: "EN",
timezone: "America/New_York",
expo_push_token: "ExponentPushToken[TAHZDfF9qqG10FaYku9eB9]",
//... more properties here
},
];
for (const device of devices) {
const raw = JSON.stringify({
device,
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow",
};
fetch(API_URL, requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
}
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
#
Source: https://docs.pushbase.dev/inbox
The Notification Inbox component for your app.
Push notifications are a powerful way to engage your audience.
However, in some cases, delivery may fail due to device settings, network issues, or battery optimization.
The Pushbase SDK includes an `` component that displays a list of past notifications sent to the user’s device.
This component is fully customizable to match your app’s branding and design, and supports deep linking to direct users to specific screens when a notification item is tapped.
```js theme={null}
import { View, Text, ActivityIndicator } from "react-native";
import { Inbox } from "@pushbase/sdk";
export default function NotificationsScreen() {
return (
Recent Notifications
{/* Add Inbox component*/}
} */}
/>
);
}
```
### Customizing `` component
The `` component provides multiple props to help you customize its appearance and behavior to fit your app’s design system.
**Props**
Item container style.
Notification title text.
Notification body text.
Time since notification was delivered text.
A valid color string used for the read status indicator on notification items.
A valid color string used as the background for notification items that are
unread or unopened.
A valid color string used for navigation indicator icon.
A boolean flag to show or hide navigation indicator.
Message shown when the user has no notifications.
Style for empty list message text view
A valid React element to render for custom content loading indicator or
skeleton. Component use React Native built-in ``
component by default.
Specifies the number of days from today to filter and match notifications
delivered within that period. Defaults to 7 days.
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Handle incoming notifications
Source: https://docs.pushbase.dev/incoming-notifications
Receive notifications and capture delivery analytics.
The Pushbase SDK offers a hook to listen for incoming notifications and automatically track delivery metrics when notifications are received and opened by users.
```js app/_layout.tsx theme={null}
import React from 'react';
import {Slot} from 'expo-router'
import {usePushbaseListeners} from '@pushbase/sdk'
// Configure how your app will handle notification
Notifications.setNotificationHandler({
handleNotification: async () => ({
shouldShowAlert: true,
shouldPlaySound: true,
shouldSetBadge: true,
}),
});
export default function Layout() {
// Optional enable automatic deep linking
usePushbaseListeners({ enableDeepLinking: true })
return
}
```
```js App.tsx theme={null}
import React from "react";
import * as Notifications from "expo-notifications";
import { NavigationContainer } from "@react-navigation/native";
import { usePushbaseListeners } from "@pushbase/sdk";
// Configure how your app will handle notification
Notifications.setNotificationHandler({
handleNotification: async () => ({
shouldShowAlert: true,
shouldPlaySound: true,
shouldSetBadge: true,
}),
});
export default function App() {
// Optional enable automatic deep linking
usePushbaseListeners({ enableDeepLinking: true });
return {/* Your content here */}>;
}
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Introduction
Source: https://docs.pushbase.dev/index
Push your first notification with Pushbase
## What is Pushbase
**Pushbase** is a notification management service built on top of the [Expo Push Service](https://docs.expo.dev/push-notifications/sending-notifications/). It provides tools for Expo app developers to subscribe users, define target audience segments and deep links, create and send push notification campaigns, and monitor campaign performance through analytics.
Install the Pushbase SDK in your Expo project.
Get your project ready to receive notifications.
Ask for user consent to receive push notifications
Add a device to the notification subscription list.
Enable device subscriptions with in-app banner component.
Remove a device from the notification subscription list.
Determine if a device is currently subscribed to push notifications.
Import Subscribed Devices from Existing Records.
Push notification through REST API
Receive notifications and capture delivery analytics.
Route users to specific screens on tap.
The Notification Inbox for your app.
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Installation
Source: https://docs.pushbase.dev/installation
Install the Pushbase SDK in your Expo project
**Prerequisite**: An Expo app with the Expo Notifications package installed and properly configured.
Refer to the [Expo Notifications](https://docs.expo.dev/versions/latest/sdk/notifications/) documentation for setup instructions.
Follow these steps to install Our SDK on your app.
## Install peer dependencies
```bash npm theme={null}
npx expo install expo-notifications expo-device expo-localization expo-secure-store
```
Each peer dependency package used to:
-
`expo-notifications` - fetch push notification tokens and to present,
schedule, receive and respond to notifications.
-
`expo-devices` - access system information about the physical device, such
as its manufacturer and model.
-
`expo-localization` - access device locale, language, timezone, and more.
-
`expo-secure-store` - store and securely cache frequent requests data for faster access.
## Install Pushbase SDK
```bash npm theme={null}
npm i @pushbase/sdk
```
```bash yarn theme={null}
yarn add @pushbase/sdk
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
#
Source: https://docs.pushbase.dev/opt-in
Easily collect device subscriptions with a seamless in-app opt-in.
Subscribing users to push notifications involves several steps: requesting permission, tracking the user’s permission status, designing an engaging UI to encourage opt-in, and integrating with the Pushbase SDK.
To simplify this process, the Pushbase SDK offers a pre-built `` component. It manages the technical complexities behind permission handling and subscription flow.
This component is fully customizable to align with your app’s color scheme and UI guidelines, ensuring a seamless user experience.
```js theme={null}
import { OptIn } from "@pushbase/sdk";
export default function HomeScreen() {
return (
);
}
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Push Notification (API)
Source: https://docs.pushbase.dev/push-notification-api
Push notification through REST API
Pushbase provides a REST API endpoint for sending push notifications programmatically. This is commonly used when notification content is dynamic or triggered by specific events.
### Preparing Notification Data for Push
To guarantee delivery, notification content must conform to the following format.
Only the following `title` and `body` properties are required.
```ts theme={null}
interface Device {
title: string;
body: string;
/* Target audience. Default to everyone.Available from dashboard.*/
segment_id?: number;
/* When notification will be delivered. Default to `instant` */
delivery?: "instant" | "scheduled";
/* For deep linking to a custom route. default to 1 for Main Screen */
link_id?: number;
/* Applied while notification is scheduled. Must be ISO 8601 datetime string.
* Scheduled in your local time and must be future date..
*/
scheduled_at?: string;
}
```
Follow example below on how to use our REST API to import devices for subscription.
```js theme={null}
const API_URL = "https://api.pushbase.dev/broadcasts/client-push";
const API_KEY = "YOUR_API_KEY"; // Available in Pushbase dashboard app setting section
const myHeaders = new Headers();
myHeaders.append("x-api-key", API_KEY);
myHeaders.append("Content-Type", "application/json");
/* Replace this with the subscribed device records from your existing database.
*
*/
const notification = {
title: "Terms & Policies updates",
body: "We have updated our policies and terms. Review now.",
/* Important: this is where you define target users from the dashboard.*/
segment_id: 1,
/* When notification will be delivered. Only `instant` and `scheduled` supported. */
delivery: "instant",
/* For deep linking to a custom route. default to 1 for Main Screen */
link_id: 1,
/* Applied while notification is scheduled. Must be future ISO 8601 datetime string. Scheduled in your local time.*/
scheduled_at: "2026-05-12T05:50:00",
};
const raw = JSON.stringify(notification);
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow",
};
fetch(API_URL, requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Request permission
Source: https://docs.pushbase.dev/request-permission
Ask for user consent to receive push notifications
To send push notifications that appear in the notification center, play
sounds, or trigger other behaviors, your app must first obtain the user’s
permission. Both iOS and Android require explicit user consent before allowing
notifications, but there are key differences between platforms:
**iOS:**
Notification permission must be requested at runtime using the system prompt. The user’s response (granted or denied) is final unless they manually change it in system settings. Notifications will not be delivered unless permission is explicitly granted.
**Android (Android 13+ / API 33+):**
Starting with Android 13, notification permission must also be requested at runtime, similar to iOS. For older versions, permission is granted by default upon app install, though users can still manually disable notifications in system settings.
Google and Apple recommend that developers clearly communicate the purpose of a permission request to users **before** prompting them for access. Providing context helps build trust and improves the likelihood that users will grant the requested permission
> Follow best practices when requesting notification permission.
## Request permission with Expo Notification
To ensure a smooth user experience, developers are responsible for requesting notification permissions at the appropriate point in the app’s lifecycle, using the expo-notifications API.
This step should be completed before attempting to subscribe the user to push notifications via the Pushbase SDK.
**Prerequisite** : Before initiating a device subscription, you must first request
notification permissions using
[`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/).
```js theme={null}
import * as Notifications from "expo-notifications";
const { granted } = await Notifications.requestPermissionsAsync({
ios: {
allowAlert: true,
allowBadge: true,
allowSound: true,
},
});
if (granted) {
/*After the user grants notification permission, your app is free to register the device for push notifications.*/
}
```
Requesting a device subscription before notification permission is granted will result in an error.
# Setup Pushbase SDK
Source: https://docs.pushbase.dev/setup
Get your project ready to receive notifications
**Prerequisite**: Expo`projectId` is required to attribute Expo push token to
the your project. It is set automatically when you create a development build.
### Get Pushbase app ID
Inside the dashboard, create your first app if not exist. Navigate to **Settings** and copy app ID.
### Integrate Expo project with Pushbase SDK
To utilize Expo push notification service, you must [configure your app](https://docs.expo.dev/push-notifications/push-notifications-setup/) by installing a set of libraries, implement functions to handle notifications, and set up credentials for Android and iOS.
Complete the steps outlined in this guide or follow the more detailed video below. At the end, you'll be able to send a push notification and receive it on a device.
Paste app ID into `app.json > expo > extra > pushbaseAppId`.
```json app.json {13} theme={null}
{
"expo": {
"name": "pushbase",
"slug": "pushbase",
"version": "1.0.0",
"orientation": "portrait",
"icon": "./assets/images/icon.png",
"scheme": "pushbase",
"userInterfaceStyle": "automatic",
"newArchEnabled": true,
//...more lines here
"extra": {
"pushbaseAppId": "5ea9••••••••••••••••••••ad83",
"eas": {
"projectId": "f4479670-ddc4-4bf8-913c-1e0065721c4f"
}
}
}
}
```
Having trouble setting up or configuring the SDK? Our support team is here to
help — [feel free to reach
out](mailto:hello@pushbase.dev?subject=Pushbase%20Product%20Support)
# Subscribe device
Source: https://docs.pushbase.dev/subscribe-device
Add a device to the notification subscription list
When integrated into your app, the Pushbase SDK handles notification subscriptions and collects relevant device information to support reliable message delivery.
All data is collected at the time of subscription and is used solely to
support notification delivery and targeting.
### Notification Token
* The SDK retrieves the device’s push token during subscription.
* This token is used to deliver notifications via the Expo Push Service.
### Device Metadata
* The SDK collects hardware details such as:
* **Device manufacturer** (Apple, Samsung)
* **Device model** (iPhone 14, Pixel 7)
* **OS version and platform** (Android or iOS)
### Location & Localization
* To support region-aware notifications, the SDK captures:
* **Locale** (en-US,fr-CA)
* **Language and country**
* **City and timezone**
* **Coordinates** - Latitude and longitude
Pushbase SDK offers a pre-built [``](/subscribe-banner)
component which manages the technical complexities behind permission handling
and subscription flow.
## Subscribe Your First Device
**Prerequisite** : Before initiating a device subscription, you must first request
notification permissions using
[`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/).
```js theme={null}
import * as Notifications from "expo-notifications";
export function requestPermissionsAsync() {
return Notifications.requestPermissionsAsync({
ios: {
allowAlert: true,
allowBadge: true,
allowSound: true,
},
});
}
```
Requesting a device subscription before notification permission is granted will result in an error.
After permission granted, subscribe device as below:
```js theme={null}
/* Import device subscription function */
import { subscribeToNotifications } from "@pushbase/sdk";
/* Later inside the app, subscribe device with optional user profile */
subscribeToNotifications({
user: {
id: 1,
name: "George Washington",
email: "washington@wh.gov",
},
tier: "free", // free, pro, or enterprise
});
```
We recommend including your app user's profile information—such as id, name,
email, or phone—at the time of subscription. This allows you to easily
identify which user is associated with each subscribed device in the Pushbase
dashboard.
# Unsubscribe device
Source: https://docs.pushbase.dev/unsubscribe-device
Remove a device from the notification subscription list
```js theme={null}
/* Import device unsubscribe function */
import { unsubscribeToNotifications } from "@pushbase/sdk";
/* Later inside the app, unsubscribe device */
unsubscribeToNotifications();
```
When a device is unsubscribed, it is removed from the subscription list and
excluded from the subscriber count for the next month’s billing cycle.