API Reference

This page provides a comprehensive reference for all PushBase SDK APIs across different platforms.

React Native SDK

The PushBase React Native SDK provides a complete wrapper around Firebase Cloud Messaging with automatic token management and permission handling.

Installation

<package_manager> [install|add] @pushbase/react-native

Core Class

`PushBase`

The main SDK class that provides all push notification functionality.

Static Methods

`getInstance(config?: PushBaseConfig): PushBase`

Returns the singleton instance of PushBase.

Parameters:

config (optional): Configuration object for the SDK

Returns: PushBase - The singleton instance

const pushBase = PushBase.getInstance({
  debug: true,
  androidChannelId: "my_notifications",
  androidChannelName: "My App Notifications",
});

Instance Methods

`initialize(): Promise<void>`

Initializes the SDK and sets up Firebase messaging.

Returns: Promise<void>

Throws: PushBaseError if initialization fails

await pushBase.initialize();

`requestPermissions(): Promise<PermissionStatus>`

Requests push notification permissions from the user.

Returns: Promise<PermissionStatus> - Current permission status

Throws: PushBaseError if permission request fails

const permissions = await pushBase.requestPermissions();
console.log("Granted:", permissions.granted);

`getToken(): Promise<string | null>`

Retrieves the current FCM token.

Returns: Promise<string | null> - The FCM token or null if unavailable

Throws: PushBaseError if token retrieval fails

const token = await pushBase.getToken();

`refreshToken(): Promise<string | null>`

Forces a token refresh and notifies listeners.

Returns: Promise<string | null> - The new FCM token or null

Throws: PushBaseError if token refresh fails

const newToken = await pushBase.refreshToken();

`subscribeToTopic(topic: string): Promise<void>`

Subscribes to a topic for receiving targeted messages.

Parameters:

topic: Topic name (1-900 characters)

Returns: Promise<void>

Throws: PushBaseError if subscription fails

await pushBase.subscribeToTopic("news");
await pushBase.subscribeToTopic("user_123");

`unsubscribeFromTopic(topic: string): Promise<void>`

Unsubscribes from a topic.

Parameters:

topic: Topic name to unsubscribe from

Returns: Promise<void>

Throws: PushBaseError if unsubscription fails

await pushBase.unsubscribeFromTopic("news");

`hasPermissions(): Promise<boolean>`

Checks if the app has notification permissions.

Returns: Promise<boolean> - True if permissions are granted

const hasPerms = await pushBase.hasPermissions();

`getInitialNotification(): Promise<PushMessage | null>`

Gets the initial notification that opened the app.

Returns: Promise<PushMessage | null> - The initial notification or null

const initialNotification = await pushBase.getInitialNotification();

`getState(): SDKState`

Returns the current SDK state.

Returns: SDKState - Current state of the SDK

const state = pushBase.getState();
console.log("Initialized:", state.initialized);

Event Listeners

`onMessage(handler: MessageHandler): () => void`

Listens for foreground messages.

Parameters:

handler: Function to handle incoming messages

Returns: () => void - Unsubscribe function

const unsubscribe = pushBase.onMessage((message) => {
  console.log("Foreground message:", message);
});

// Later, unsubscribe
unsubscribe();

`onBackgroundMessage(handler: MessageHandler): () => void`

Listens for background messages.

Parameters:

handler: Function to handle background messages

Returns: () => void - Unsubscribe function

const unsubscribe = pushBase.onBackgroundMessage((message) => {
  console.log("Background message:", message);
});

`onTokenRefresh(handler: TokenHandler): () => void`

Listens for token refresh events.

Parameters:

handler: Function to handle token updates

Returns: () => void - Unsubscribe function

const unsubscribe = pushBase.onTokenRefresh((token) => {
  console.log("New token:", token);
  // Send to your server
});

`onError(handler: ErrorHandler): () => void`

Listens for SDK errors.

Parameters:

handler: Function to handle errors

Returns: () => void - Unsubscribe function

const unsubscribe = pushBase.onError((error) => {
  console.error("PushBase error:", error);
});

`destroy(): void`

Cleans up the SDK and removes all listeners.

pushBase.destroy();

Types

`PushBaseConfig`

Configuration options for the SDK.

interface PushBaseConfig {
  /** Enable debug logging */
  debug?: boolean;
  /** Custom notification channel for Android */
  androidChannelId?: string;
  /** Custom notification channel name for Android */
  androidChannelName?: string;
  /** Auto-initialize the SDK */
  autoInitialize?: boolean;
  /** Custom server endpoint for token registration */
  serverEndpoint?: string;
  /** Additional metadata to send with token */
  metadata?: Record<string, any>;
}

`PushMessage`

Represents a push notification message.

interface PushMessage {
  messageId?: string;
  data?: Record<string, string>;
  notification?: {
    title?: string;
    body?: string;
    imageUrl?: string;
    android?: {
      channelId?: string;
      smallIcon?: string;
      color?: string;
      priority?: "default" | "high" | "low" | "max" | "min";
    };
    ios?: {
      badge?: number;
      sound?: string;
      categoryId?: string;
    };
  };
  from?: string;
  collapseKey?: string;
  sentTime?: number;
  ttl?: number;
}

`PermissionStatus`

Represents the current permission status.

interface PermissionStatus {
  granted: boolean;
  status: "authorized" | "denied" | "not_determined" | "provisional";
  settings: {
    alert: boolean;
    badge: boolean;
    sound: boolean;
  };
}

`SDKState`

Represents the current SDK state.

interface SDKState {
  initialized: boolean;
  token: string | null;
  permissions: PermissionStatus | null;
  lastError: Error | null;
}

Event Handler Types

type MessageHandler = (message: PushMessage) => void | Promise<void>;
type TokenHandler = (token: string) => void | Promise<void>;
type ErrorHandler = (error: Error) => void;

Error Handling

`PushBaseError`

Custom error class for SDK-specific errors.

class PushBaseError extends Error {
  public readonly code: ErrorCodes;
  public readonly timestamp: Date;

  constructor(code: ErrorCodes, message: string, cause?: Error);
  toJSON(): object;
}

`ErrorCodes`

Enum of possible error codes.

enum ErrorCodes {
  INITIALIZATION_FAILED = "INITIALIZATION_FAILED",
  FIREBASE_NOT_CONFIGURED = "FIREBASE_NOT_CONFIGURED",
  PERMISSION_DENIED = "PERMISSION_DENIED",
  TOKEN_RETRIEVAL_FAILED = "TOKEN_RETRIEVAL_FAILED",
  TOKEN_REGISTRATION_FAILED = "TOKEN_REGISTRATION_FAILED",
  TOPIC_SUBSCRIPTION_FAILED = "TOPIC_SUBSCRIPTION_FAILED",
  TOPIC_UNSUBSCRIPTION_FAILED = "TOPIC_UNSUBSCRIPTION_FAILED",
  INITIAL_NOTIFICATION_FAILED = "INITIAL_NOTIFICATION_FAILED",
  NOTIFICATION_DISPLAY_FAILED = "NOTIFICATION_DISPLAY_FAILED",
}

Error Handling Example

import { PushBaseError, ErrorCodes } from "@pushbase/react-native";

pushBase.onError((error) => {
  if (error instanceof PushBaseError) {
    switch (error.code) {
      case ErrorCodes.FIREBASE_NOT_CONFIGURED:
        console.error("Firebase not configured properly");
        break;
      case ErrorCodes.PERMISSION_DENIED:
        console.error("User denied notification permissions");
        break;
      default:
        console.error("PushBase error:", error.message);
    }
  } else {
    console.error("Unknown error:", error);
  }
});

Expo SDK

Coming soon

The Expo SDK will provide similar functionality optimized for Expo applications with managed workflow support.

Web SDK

Coming soon

The Web SDK will provide browser-based push notifications using Firebase Cloud Messaging for web applications.

API Reference

On this page