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"]);

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();
}