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