Push Notifications

Register for push notifications, manage topic subscriptions, and respond to incoming notifications. Uses Firebase Cloud Messaging (FCM) under the hood.

Access: startiapp.PushNotification

For a practical guide to managing topic subscriptions — see Manage Push Topics.

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

You don't need to call requestAccess() again to keep the backend in sync when a user later enables or disables notifications in their device settings. The SDK automatically reconciles the permission with the backend on every app launch and whenever the app returns to the foreground — updating the server (and the "all" topic subscription) only when the status actually changed.

`setBadgeCount(count: number): void`

Sets the app icon badge count on the device.

Parameters:

Parameter	Type	Required	Description
`count`	`number`	Yes	The number to display on the app badge. Set to `0` to clear.

Example:

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

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

`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:

Parameter	Type	Required	Description
`topics`	`string[]`	Yes	List of topic IDs to subscribe to.
`shouldCheckAccess`	`boolean`	No	Whether to request permission first. Defaults to `true`.

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:

Parameter	Type	Required	Description
`topics`	`string[]`	Yes	List of topic IDs to unsubscribe from.

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 } —The notification content.

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

On this page