ping-identity
    Preparing search index...

    Interface PushClient

    Reusable client for push MFA operations.

    Obtained by calling createPushClient. The underlying native PushClient instance is initialized eagerly at creation time.

    import { createPushClient } from '@ping-identity/rn-push';

    const client = createPushClient();
    const credential = await client.addCredentialFromUri('pushauth://...');
    interface PushClient {
        addCredentialFromUri(uri: string): Promise<PushCredential>;
        approveBiometricNotification(
            notificationId: string,
            authenticationMethod: string,
        ): Promise<boolean>;
        approveChallengeNotification(
            notificationId: string,
            challengeResponse: string,
        ): Promise<boolean>;
        approveNotification(notificationId: string): Promise<boolean>;
        cleanupNotifications(credentialId?: string): Promise<number>;
        close(): Promise<void>;
        deleteCredential(credentialId: string): Promise<boolean>;
        denyNotification(notificationId: string): Promise<boolean>;
        getAllNotifications(): Promise<PushNotification[]>;
        getCredential(credentialId: string): Promise<PushCredential>;
        getCredentials(): Promise<PushCredential[]>;
        getDeviceToken(): Promise<string>;
        getNotification(notificationId: string): Promise<PushNotification>;
        getPendingNotifications(): Promise<PushNotification[]>;
        onNotification(
            callback: (notification: PushNotification) => void,
        ): () => void;
        onTokenRegistered(callback: (token: string) => void): () => void;
        processNotification(
            messageData: Record<string, unknown>,
        ): Promise<PushNotification>;
        processNotificationFromMessage(message: string): Promise<PushNotification>;
        refreshToken(): Promise<string>;
        saveCredential(credential: PushCredential): Promise<PushCredential>;
        setDeviceToken(token: string, credentialId?: string): Promise<boolean>;
    }
    Index

    Methods

    addCredentialFromUri approveBiometricNotification approveChallengeNotification approveNotification cleanupNotifications close deleteCredential denyNotification getAllNotifications getCredential getCredentials getDeviceToken getNotification getPendingNotifications onNotification onTokenRegistered processNotification processNotificationFromMessage refreshToken saveCredential setDeviceToken

    Methods

    • Enrolls a new push credential from a pushauth:// URI.

      Parameters

      • uri: string

        The pushauth:// enrollment URI received from the server.

      Returns Promise<PushCredential>

      A promise that resolves to the newly enrolled PushCredential.

      PushError with code 'invalid_uri' if the URI is malformed.

      PushError with code 'duplicate_credential' if already enrolled.

      PushError with code 'registration_failed' if server registration fails.

      const credential = await client.addCredentialFromUri('pushauth://...');

    • Approves a biometric push notification using the specified authentication method.

      Parameters

      • notificationId: string

        The unique notification identifier.

      • authenticationMethod: string

        The biometric authentication method identifier.

      Returns Promise<boolean>

      A promise that resolves to true when approved successfully.

      PushError with code 'notification_not_found' if not found.

      PushError with code 'invalid_parameter_value' if authenticationMethod is empty.

      await client.approveBiometricNotification(notification.id, 'biometric');

    • Approves a challenge push notification with a user-provided response.

      Parameters

      • notificationId: string

        The unique notification identifier.

      • challengeResponse: string

        The user's challenge response string.

      Returns Promise<boolean>

      A promise that resolves to true when approved successfully.

      PushError with code 'notification_not_found' if not found.

      PushError with code 'invalid_parameter_value' if challengeResponse is empty.

      await client.approveChallengeNotification(notification.id, selectedAnswer);

    • Approves a standard push notification.

      Parameters

      • notificationId: string

        The unique notification identifier.

      Returns Promise<boolean>

      A promise that resolves to true when approved successfully.

      PushError with code 'notification_not_found' if not found.

      PushError with code 'policy_violation' if approval violates policy.

      await client.approveNotification(notification.id);

    • Runs the configured notification cleanup strategy.

      Parameters

      • OptionalcredentialId: string

        Optional credential identifier. When provided, only notifications associated with that credential are considered for cleanup. When omitted, cleanup applies across all credentials.

      Returns Promise<number>

      A promise resolving to the number of notifications that were removed.

      PushError with code 'not_initialized' if the client is not initialized.

      const removed = await client.cleanupNotifications();

    • Releases native push client resources and clears cached state.

      Returns Promise<void>

      A promise that resolves when resources are released.

      Safe to call multiple times — subsequent calls on an already-closed client are a no-op on both platforms. After calling close(), the client instance should be discarded and a new one created if push operations are needed again.

      await client.close();

    • Deletes a push credential by its identifier.

      Parameters

      • credentialId: string

        The unique credential identifier to delete.

      Returns Promise<boolean>

      A promise that resolves to true if deleted, false if not found.

      PushError with code 'storage_failure' if deletion fails.

      const deleted = await client.deleteCredential('cred-id');

    • Denies a push notification.

      Parameters

      • notificationId: string

        The unique notification identifier.

      Returns Promise<boolean>

      A promise that resolves to true when denied successfully.

      PushError with code 'notification_not_found' if not found.

      PushError with code 'policy_violation' if denial violates policy.

      await client.denyNotification(notification.id);

    • Returns a specific push credential by its identifier.

      Parameters

      • credentialId: string

        The unique credential identifier.

      Returns Promise<PushCredential>

      A promise that resolves to the PushCredential, or null if not found.

      PushError with code 'not_initialized' if the client is not initialized.

      const credential = await client.getCredential('cred-id');

    • Returns the current device push token.

      Returns Promise<string>

      A promise that resolves to the device token string, or null if not set.

      PushError with code 'not_initialized' if the client is not initialized.

      const token = await client.getDeviceToken();

    • Registers a callback invoked when a Ping push notification arrives.

      The SDK calls processNotification internally before invoking the callback. The callback receives the parsed PushNotification, or null when the payload was not a recognised Ping push message.

      The subscription is removed automatically when close() is called.

      Parameters

      • callback: (notification: PushNotification) => void

        Invoked with the notification or null.

      Returns () => void

      An unsubscribe function that removes only this subscription.

      const unsubscribe = client.onNotification((notification) => {
        if (notification) {
          // show approval UI
        }
      });
      // To unsubscribe manually:
      unsubscribe();

    • Registers a callback invoked after the device push token has been successfully registered with the native SDK.

      Fires both for tokens that arrived before createPushClient() was called (replayed at creation time) and for subsequent token rotations. Guaranteed to fire after setDeviceToken has completed, so calling getDeviceToken() inside the callback always returns the new token.

      The subscription is removed automatically when close() is called.

      Parameters

      • callback: (token: string) => void

        Invoked with the registered token string.

      Returns () => void

      An unsubscribe function that removes only this subscription.

      client.onTokenRegistered((token) => {
        console.log('token ready:', token);
      });

    • Processes an incoming push notification from a dictionary payload.

      Parameters

      • messageData: Record<string, unknown>

        The raw push message data dictionary (e.g. from FCM getData() on Android or APNs userInfo on iOS).

      Returns Promise<PushNotification>

      A promise resolving to a PushNotification, or null for unsupported payloads.

      PushError with code 'message_parsing_failed' if the payload cannot be parsed.

      const notification = await client.processNotification(message.getData());
      if (notification) {
        await client.approveNotification(notification.id);
      }

    • Processes an incoming push notification from a raw string or JWT payload.

      Parameters

      • message: string

        The raw push message string received from the push service.

      Returns Promise<PushNotification>

      A promise resolving to a PushNotification, or null for unsupported payloads.

      PushError with code 'message_parsing_failed' if the payload cannot be parsed.

      const notification = await client.processNotificationFromMessage(rawMessage);

    • Fetches the current platform push token and registers it with the native SDK.

      On Android, fetches the current FCM registration token and calls setDeviceToken internally. On iOS this is a no-op — the APNs token is delivered via AppDelegate.

      Useful when the automatic token delivery has not completed yet.

      Returns Promise<string>

      A promise resolving to the token string, or null on iOS.

      PushError when the FCM token fetch fails.

      const token = await client.refreshToken();

    • Saves an updated credential back to native storage.

      Parameters

      • credential: PushCredential

        The credential object to persist. Must have been obtained from the bridge (e.g. via getCredential). The sharedSecret field is never included in the JS representation and is handled natively.

      Returns Promise<PushCredential>

      A promise that resolves to the saved PushCredential.

      PushError with code 'credential_not_found' if the credential does not exist.

      PushError with code 'storage_failure' if persistence fails.

      const saved = await client.saveCredential(credential);

    • Updates the device push token, optionally scoped to a specific credential.

      Parameters

      • token: string

        The new device push token (FCM token on Android, APNs token on iOS).

      • OptionalcredentialId: string

        Optional credential identifier. When omitted, the token is set globally for all credentials.

      Returns Promise<boolean>

      A promise that resolves to true when the token is successfully updated.

      PushError with code 'registration_failed' if the server update fails.

      // Global token update
      await client.setDeviceToken(fcmToken);
      // Scoped token update
      await client.setDeviceToken(fcmToken, 'cred-id');

    Settings

    Member Visibility

    On This Page

    Methods