Push Notifications

Access: startiapp.PushNotification

Methods

getToken(): Promise<string>

Returns the FCM token for this device. The token uniquely identifies the device and is required when sending push notifications from a server.

Returns: Promise<string> —The FCM token, or an empty string if unavailable.

Example:

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

checkAccess(): Promise<PermissionStatus>

Checks the current permission status for push notifications without prompting the user.

Returns: Promise<PermissionStatus> —The current permission status.

Example:

const status = await startiapp.PushNotification.checkAccess();
if (status.granted) {
  console.log("Push notifications are allowed");
}

requestAccess(): Promise<boolean>

Prompts the user to grant push notification permissions. If granted, the device is automatically subscribed to the "all" topic and the server is notified of the permission change.

Returns: Promise<boolean> —true if the user granted permission, false otherwise.

Example:

const granted = await startiapp.PushNotification.requestAccess();
if (granted) {
  console.log("Notifications enabled!");
} else {
  console.log("User declined notifications");
}

setBadgeCount(count: number): void

Sets the app icon badge count on the device.

Parameters:

Example:

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

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

clearNotifications(options: { tags: string[] }): Promise<void>

Removes delivered notifications from the device's notification centre, by the tag they were sent with.

Call it when your page has shown the user what a notification announced — they opened the app on their own and are looking at the result — so the notification does not linger as unread on the lock screen. Tags the device holds no notification for are ignored. The badge count is a separate matter and is left alone; change it with setBadgeCount if it should follow.

Needs App Shell 4.258 or later. On older builds the call does nothing, and the notification stays until the user dismisses it. Check with startiapp.App.supports("clearNotifications") if your page wants to know.

Parameters:

Example:

// The render the notification announced is on screen now.
await startiapp.PushNotification.clearNotifications({ tags: [`render-${renderId}`] });

// A list that shows several finished results at once
await startiapp.PushNotification.clearNotifications({
  tags: renders.map((render) => `render-${render.id}`),
});

getTopics(): Promise<Topic[]>

Retrieves the list of available push notification topics for the current brand. Each returned Topic object includes its current subscription state.

Returns: Promise<Topic[]> —An array of Topic objects.

Throws: Error if the server request fails.

Example:

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

topics.forEach(topic => {
  console.log(`${topic.name} (${topic.topic}): ${topic.subscribed ? "subscribed" : "not subscribed"}`);
});

subscribeToTopics(topics, shouldCheckAccess?): Promise<Array<{ topic: string; name: string }>>

Subscribes the device to one or more push notification topics. By default, requests notification permission first.

Parameters:

Returns: Promise<Array<{ topic: string; name: string }>> —The topics that were successfully subscribed, with their server-assigned IDs and display names.

Throws: Error if permission is denied (when shouldCheckAccess is true), or if the network request fails.

Example:

try {
  const subscribed = await startiapp.PushNotification.subscribeToTopics(["news", "offers"]);
  console.log("Subscribed to:", subscribed);
} catch (error) {
  console.error("Subscription failed:", error.message);
}

unsubscribeFromTopics(topics: string[]): Promise<void>

Unsubscribes the device from one or more push notification topics.

Parameters:

Throws: Error if the network request fails.

Example:

await startiapp.PushNotification.unsubscribeFromTopics(["news", "offers"]);

Notification history

The methods below let your site show a notification bell or inbox: the push notifications this device has been sent, newest first, with an unread count.

The history holds notifications sent from the Manager to topics the device subscribes to, and to everyone. Messages sent to individual users, and notifications sent through the REST API, are not included. It starts the first time the app opens with an SDK version that has these methods, so it is empty on a device until the next notification arrives. When a notification is sent, the Manager can leave it out of the history.

getHistory(options?): Promise<NotificationHistoryPage>

Returns one page of the history, newest first.

Parameters:

Returns: Promise<NotificationHistoryPage> — the items and the cursor for the next page, which is null on the last page.

Throws: Error if the history cannot be reached.

Example:

let cursor = null;

async function loadMore() {
  const page = await startiapp.PushNotification.getHistory({ cursor });
  page.items.forEach(renderItem);
  cursor = page.nextCursor;
  moreButton.hidden = cursor === null;
}

getUnreadCount(): Promise<number>

Counts the notifications sent since the user last called markAllAsSeen. Use it for the badge on the bell.

Example:

const unread = await startiapp.PushNotification.getUnreadCount();
bellBadge.textContent = unread > 0 ? String(unread) : "";

markAllAsSeen(): Promise<void>

Marks every notification in the history as seen, typically when the user opens the bell. The unread count is then 0 until the next notification arrives. Stored on the device.

Example:

bell.addEventListener("click", async () => {
  openInbox();
  await startiapp.PushNotification.markAllAsSeen();
});

openHistoryItem(id: string): Promise<void>

Opens a notification from the history. The tap is counted in the notification's statistics in the Manager, together with taps on the push itself, once per device. If the notification was sent with a link, the app goes to it.

Parameters:

Example:

function renderItem(item) {
  const row = document.createElement("button");
  row.textContent = item.title;
  row.classList.toggle("unread", item.unread);
  row.addEventListener("click", () => startiapp.PushNotification.openHistoryItem(item.id));
  inbox.append(row);
}

Events

tokenRefreshed

Fired when the FCM token is refreshed by the platform. If you send push notifications through the starti.app Manager, Admin API, or webhooks, this event is handled automatically — you only need to listen for it if you work directly with Firebase Cloud Messaging.

Event data: string —The new FCM token.

Example:

startiapp.PushNotification.addEventListener("tokenRefreshed", (event) => {
  const newToken = event.detail;
  console.log("Token refreshed:", newToken);
  // Send updated token to your server
});

notificationReceived

Fired when a push notification is received while the app is in the foreground.

Event data: { title: string; body: string; tag?: string } — the notification content, and the tag it was sent with when the sender gave it one.

The event fires whether or not the system shows the notification. If the sender set silentInForeground on the message, this event is the only thing that arrives while the app is open, and presenting the message is up to your page.

Example:

startiapp.PushNotification.addEventListener("notificationReceived", (event) => {
  const { title, body } = event.detail;
  console.log(`Notification: ${title} - ${body}`);
});

Types

Topic

Represents a push notification topic. Returned by getTopics().

class Topic {
  /** The unique topic identifier. */
  topic: string;

  /** The human-readable topic name. */
  name: string;

  /** Whether the device is currently subscribed to this topic. */
  subscribed: boolean;

  /** Subscribes the device to this topic. */
  subscribe(): void;

  /** Unsubscribes the device from this topic. */
  unsubscribe(): void;

  /** Returns a plain JSON representation of the topic. */
  toJSON(): { topic: string; name: string; subscribed: boolean };
}

Example:

const topics = await startiapp.PushNotification.getTopics();
const newsTopic = topics.find(t => t.topic === "news");

if (newsTopic && !newsTopic.subscribed) {
  newsTopic.subscribe();
}

NotificationHistoryPage

Returned by getHistory().

interface NotificationHistoryPage {
  /** The notifications on this page, newest first. */
  items: NotificationHistoryItem[];

  /** Pass to the next getHistory call; null on the last page. */
  nextCursor: string | null;
}

interface NotificationHistoryItem {
  /** Pass to openHistoryItem when the user taps the notification. */
  id: string;

  title: string;
  body: string;

  /** Where the notification leads, when it was sent with a link. */
  openToUrl: string | null;

  /** When it was sent. */
  createdAt: Date;

  /** Sent after the user last called markAllAsSeen. */
  unread: boolean;
}