Ping Identity React Native Browser

The Ping Identity React Native Browser module provides a safe, system-browser flow for OIDC/OAuth logins. It launches Custom Tabs/Auth Tabs on Android and ASWebAuthenticationSession on iOS, then returns the redirect URL to JavaScript.

Table of contents

• Integrating the SDK into your project
• How to Use the SDK
• Error handling
• TODO
• License

Integrating the SDK into your project

Add the package and let autolinking wire the native code:

yarn add @ping-identity/rn-browser
cd ios && pod install
Copy

Optional integration packages:

yarn add @ping-identity/rn-logger
Copy

• @ping-identity/rn-logger: optional JS/native logger integration.

How to Use the SDK

Configure (Android only)

Apply global customization for Custom Tabs/Auth Tabs. iOS currently ignores these options.

import { configureBrowser } from '@ping-identity/rn-browser';

configureBrowser({
  android: {
    customTabs: {
      showTitle: false,
      urlBarHidingEnabled: true,
      colorScheme: 'system',
    },
    authTabs: {
      ephemeral: true,
    },
  },
});
Copy

iOS per-call configuration

iOS browser behavior is configured per call via the ios options on open(...). These options do not have a global configuration equivalent on iOS.

Android manifest placeholder

Configure the manifest placeholder for your app's redirect URI scheme. This is used as a fallback when Auth Tabs are not available and Custom Tabs must rely on the manifest scheme:

android {
  defaultConfig {
    // For redirect URI "com.example.app://callback", configure:
    manifestPlaceholders["appRedirectUriScheme"] = "com.example.app"
  }
}
Copy

Configure logging (optional)

If you install the logger package, pass a JS logger instance per call via BrowserLoggerOptions. The logger must be created via @ping-identity/rn-logger. If the logger package is not installed/configured, omit the logger option.

import { open, configureBrowser, resetBrowser } from '@ping-identity/rn-browser';
import { logger } from '@ping-identity/rn-logger';

const jsLogger = logger({ level: 'debug' });

// Pass as the last argument to any browser call
const result = await open(
  'https://example.com',
  { callbackUrlScheme: 'com.example.app' },
  { logger: jsLogger },
);

// Also supported on configureBrowser and resetBrowser
configureBrowser({ android: { customTabs: { showTitle: true } } }, { logger: jsLogger });
resetBrowser({ logger: jsLogger });
Copy

Open a browser session

import { open } from '@ping-identity/rn-browser';

const result = await open('https://example.com', {
  callbackUrlScheme: 'com.example.app',
  redirectUri: 'com.example.app://callback',
  ios: {
    browserType: 'authSession',
    browserMode: 'login',
  },
});

// result: { type: 'success', url } | { type: 'cancel' }
Copy

Security note: The module does not validate or sanitize the url you pass to open. Only launch trusted URLs in your app (for example, enforce an https scheme and allow-listed hosts).

Error handling

Native promise rejections map to the shared GenericError contract from @ping-identity/rn-types. Errors are rejected as exceptions; cancellations are resolved as { type: 'cancel' } instead of being rejected.

Error codes:

• BROWSER_OPEN_ERROR for validation/launch failures

import type { BrowserError } from '@ping-identity/rn-browser';

try {
  await open('https://example.com', { callbackUrlScheme: 'com.example.app' });
} catch (e) {
  const error = e as BrowserError;
  // error.type, error.error, error.message, error.code, error.status
}
Copy

TODO

• Add an iOS test runner target to execute module unit tests.

License

MIT