Set up push notifications in your starti.app-powered app — from no-code Manager broadcasts to per-user targeting and advanced FCM token management

Push Notifications

starti.app offers several approaches to push notifications. Pick the one that fits your needs — they can also be combined.

Approach	What you get	Code required?
Manager	Broadcast to all users or topic groups	No — configured entirely in the starti.app Manager
Webhooks	Per-user notifications triggered by your platform	One SDK call (`registerId`) + webhook configuration in Manager
Per-user API	Target individual users from your own backend	One SDK call (`registerId`) + API calls from your server
Advanced	Full control over FCM tokens and Firebase	You manage tokens and talk to Firebase directly

Set up push notifications

This approach requires no code changes in your web app. Everything is configured in the starti.app Manager.

Add a push notification page to your Introflow

In the Manager, open your app's Introflow and add a push notification consent page. When a user goes through the Introflow and accepts, they are automatically subscribed to receive push notifications.

Send broadcasts from the Manager

Once users have opted in, you can send push notifications to all subscribed users directly from the Manager. No API calls or code needed.

Add topics for targeted broadcasts

If you want users to choose which types of notifications they receive, add topic categories in the Manager. Users will see the available topics in the Introflow and can select the ones they are interested in.

When sending a notification from the Manager, you can choose to send to all subscribers or only to users subscribed to specific topics. The Manager shows subscriber counts for each topic so you can see how many users will receive the message.

Webhooks let you send per-user notifications without writing any backend code. Your existing platform (for example, an eCommerce system) calls a webhook URL, and the Manager takes care of delivering the notification to the right user.

Register the user in the frontend

Call registerId() when the user logs in so that starti.app knows who is on which device.

await startiapp.User.registerId("your-user-id");

When the user logs out, unregister them:

await startiapp.User.unregisterId();

Create a webhook in the Manager

In the Manager, create a new webhook. This gives you a URL that your platform can call when something happens — for example, when an order changes status.

Add the webhook URL to your platform's notification settings (most eCommerce platforms, CRM systems, and similar tools support outgoing webhooks).

Set up rules in the Manager

In the Manager, configure rules for what should happen when the webhook is called. For example, you can set up a rule that sends a push notification saying "Your order has been shipped" when an order gets the status "shipped".

The webhook payload includes the user ID, so the Manager knows exactly which user to notify — and starti.app delivers the message to all their devices.

You can also choose to send to a topic instead of an individual user, which is useful for broadcasts triggered by external events (for example, notifying all users subscribed to "offers" when a new promotion is created).

This approach is ideal when you want per-user notifications but don't want to build backend logic for sending them. Your platform triggers the webhook, and the Manager handles the rest.

When you need to send notifications to individual users from your own backend — and want full control over when and what to send — use the per-user API approach.

Request permission

Before sending push notifications, the user must grant permission. Call requestAccess() to prompt the user.

const granted = await startiapp.PushNotification.requestAccess();

if (granted) {
  console.log("Push notifications enabled!");
} else {
  console.log("User denied push notification access.");
}

On iOS, this shows the standard system permission dialog. On Android 13+, it shows the runtime permission dialog. On older Android versions, permission is granted by default.

If you already handle permission through the Manager Introflow, you can skip this step — users who accepted there already have permission.

Register the user

After the user logs in, call registerId() with the ID you use to identify the user in your system.

await startiapp.User.registerId("your-user-id");
console.log("User registered for push notifications!");

That's it. starti.app now knows which user is on which device. If the same user logs in on multiple devices (for example, an iPhone and an iPad), notifications sent to that user ID are delivered to all their devices.

You can now send push notifications to this user through the Admin API.

When the user logs out, unregister them so the device is no longer associated with their account:

await startiapp.User.unregisterId();

Use this approach when you need direct control over FCM tokens — for example, if you have a custom backend that sends push notifications through Firebase Cloud Messaging directly rather than through the starti.app API.

Request permission

const granted = await startiapp.PushNotification.requestAccess();

if (granted) {
  console.log("Push notifications enabled!");
} else {
  console.log("User denied push notification access.");
}

Get the FCM token

The FCM token uniquely identifies this device for push notifications. Send this token to your backend so your server can target this specific device.

const token = await startiapp.PushNotification.getToken();
console.log("FCM token:", token);

// Send it to your server
await fetch("/api/push/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ fcmToken: token }),
});

The FCM token can change over time (for example, when the user reinstalls the app or clears app data). Always handle token refreshes to keep your server up to date. See the next step.

Handle token refresh

FCM tokens can change. Listen for the tokenRefreshed event and update your server whenever a new token arrives.

startiapp.PushNotification.addEventListener("tokenRefreshed", function (event) {
  const newToken = event.detail;
  console.log("FCM token refreshed:", newToken);

  // Update your server with the new token
  fetch("/api/push/register", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fcmToken: newToken }),
  });
});

In practice, none of our customers use this approach — the additional setup and manual token management is rarely worth it. The other approaches cover the vast majority of use cases. But the option is here if you need it.

Work with topics

Topics let you segment your notifications so you can send messages to groups of users rather than individuals. Topics can be configured in the Manager or managed programmatically with the SDK — regardless of which approach you use for sending notifications.

Get available topics

Fetch the list of topics configured for your brand.

const topics = await startiapp.PushNotification.getTopics();

topics.forEach(function (topic) {
  console.log(
    topic.name + " (" + topic.topic + ") - subscribed: " + topic.subscribed,
  );
});

Each Topic object has:

Property	Type	Description
`topic`	`string`	The topic identifier used internally
`name`	`string`	A human-readable display name
`subscribed`	`boolean`	Whether the device is currently subscribed

const result = await startiapp.PushNotification.subscribeToTopics(["news", "offers"]);
console.log("Subscribed to:", result);

subscribeToTopics() automatically requests push notification permission if it has not been granted yet. If you subscribe to a topic that does not already exist, it is created automatically.

Unsubscribe from topics

await startiapp.PushNotification.unsubscribeFromTopics(["offers"]);
console.log("Unsubscribed from offers.");

Subscribe/unsubscribe using Topic objects

The Topic objects returned by getTopics() also have convenience methods.

const topics = await startiapp.PushNotification.getTopics();

// Subscribe to the first topic
topics[0].subscribe();

// Unsubscribe from the second topic
topics[1].unsubscribe();

Set badge count

Set the app icon badge number to indicate unread notifications. Pass 0 to clear the badge.

// Show 5 unread notifications
startiapp.PushNotification.setBadgeCount(5);

// Clear the badge
startiapp.PushNotification.setBadgeCount(0);

On Android, badge support depends on the device manufacturer's launcher. Most modern launchers support it, but behavior may vary.

Check permission status

You can check whether the user has already granted push notification permission without prompting them.

const status = await startiapp.PushNotification.checkAccess();
console.log("Permission granted:", status.granted);

This is useful on page load to decide whether to show an "Enable notifications" button or go straight to your push notification setup.

Listen for foreground notifications

When a notification arrives while the app is in the foreground, the SDK dispatches a notificationReceived event with the notification's title and body.

startiapp.PushNotification.addEventListener(
  "notificationReceived",
  function (event) {
    var title = event.detail.title;
    var body = event.detail.body;
    console.log("Notification received:", title, body);
  },
);

Push notifications are always displayed to the user by the operating system — whether the app is in the foreground or background, and regardless of whether you listen for this event. The notificationReceived event is only for cases where your code needs to react to a notification while the app is open. Most apps do not need this. If you need real-time data updates from your backend, consider using WebSockets or server-sent events instead.

Complete working examples

async function main() {
  if (!startiapp.isRunningInApp()) return;

  await startiapp.initialize();

  // Request permission
  const granted = await startiapp.PushNotification.requestAccess();

  if (!granted) {
    console.log("User denied notifications.");
    showOptInBanner();
    return;
  }

  // Register the user — this handles FCM token management automatically
  const userId = getCurrentUserId(); // your own function
  if (userId) {
    await startiapp.User.registerId(userId);
  }

  // Optionally, load and display topics
  const topics = await startiapp.PushNotification.getTopics();
  renderTopicList(topics);
}

main();

async function main() {
  if (!startiapp.isRunningInApp()) return;

  await startiapp.initialize();

  // Request permission
  const granted = await startiapp.PushNotification.requestAccess();

  if (!granted) {
    console.log("User denied notifications.");
    showOptInBanner();
    return;
  }

  // Get and send the FCM token to your server
  const token = await startiapp.PushNotification.getToken();
  await registerTokenOnServer(token);

  // Listen for foreground notifications
  startiapp.PushNotification.addEventListener(
    "notificationReceived",
    function (event) {
      showNotificationBanner(event.detail.title, event.detail.body);
    },
  );

  // Handle token refresh
  startiapp.PushNotification.addEventListener("tokenRefreshed", function (event) {
    registerTokenOnServer(event.detail);
  });

  // Optionally, load and display topics
  const topics = await startiapp.PushNotification.getTopics();
  renderTopicList(topics);
}

async function registerTokenOnServer(token) {
  await fetch("/api/push/register", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fcmToken: token }),
  });
}

main();

Push Notifications

On this page