Savers React Native SDK

React Native SDK that bridges host app features like maps, dialer, browser, device info, session storage, URL generation, navigation, and webview event handling.

Features

- Open maps by coordinates with fallback to browser
- Dial pad invocation with optional number
- External browser navigation
- Close current screen via global navigationRef (React Navigation)
- Device ID and location retrieval
- Session and keys management (API and encryption)
- URL generator to compose Savers mobile URLs
- WebView message handler to trigger native actions from web

Installation

- Install the library:

``bash
npm install @saversapp/react-native-sdk
`

- Install required peer dependencies:

`bash
npm install @react-native-async-storage/async-storage \
@react-native-community/geolocation \
@react-navigation/native \
react-native-device-info
`

- Optional (for WebView-based messaging):

`bash
npm install react-native-webview
`

iOS Setup

- Add dialer schemes to Info.plist:

`xml
LSApplicationQueriesSchemes

tel
telprompt

`

- Permissions (add keys and descriptions in Info.plist):
- NSLocationWhenInUseUsageDescription

Example:

`xml
NSLocationWhenInUseUsageDescription
Location access is required to provide location-based features.
`

Ensure native pods are installed and linked for the peer dependencies.

Android Setup

- Add permissions in AndroidManifest.xml:

`xml


`

Link and configure the peer dependencies according to their documentation.

Quick Start

Initialize the SDK (optional keys):

`ts
import { SaversAppSDK } from '@saversapp/react-native-sdk';

SaversAppSDK.initialized({
apiKey: 'YOUR_API_KEY',
encryptionKey: 'YOUR_ENCRYPTION_KEY',
});
`

Generate URL:

`ts
import { generateUrl } from '@saversapp/react-native-sdk';

const url = await generateUrl({
pRefId: 'PROGRAM_CODE',
authType: 'PHONE', // 'EMAIL' | 'USERNAME'
profile: {
firstname: 'Jane',
lastname: 'Doe',
phone: '+15555550100',
pv: '1',
ev: '1',
},
screen: { name: 'Explore' },
});
// returns https://m.saversapp.com/?pRefCode=...&qP=...
`

Navigation (Close Current Screen)

The SDK can close the current screen without knowing the host app's navigation structure using a global navigationRef.

One-time host app setup:

`tsx
import { NavigationContainer } from '@react-navigation/native';
import { navigationRef } from '@saversapp/react-native-sdk';

export function App() {
return {/ ... /};
}
`

SDK API:

`ts
import { closeCurrentScreen, closeCurrentScreenSafe } from '@saversapp/react-native-sdk';

closeCurrentScreen(); // returns boolean
closeCurrentScreenSafe(); // Android-only fallback to exitApp if it can't goBack()
`

WebView Integration

Trigger native actions from web & Bind onMessage to WebView:

`ts
import { handleWebMessage } from '@saversapp/react-native-sdk';
import { WebView } from 'react-native-webview';
...

const onMessage = (e: any) => {
const raw = e?.nativeEvent?.data;
const postBack = (data: any) => {
// send data back to the webview as needed
};
handleWebMessage(raw, postBack);
};

originWhitelist={['*']}
source={{ html }}
onMessage={onMessage}
/>;
`

Supported actions:
- OPEN_MAP { lat, lng, label }
- CLOSE_CURRENT_SCREEN
- SHOW_DIAL_PAD { number? }
- MERCHANT_PORTAL_REDIRECT { url }
- SESSION_ID { sessionId }
Note: Unified WebView helpers were removed. Use handleWebMessage directly with react-native-webview.

$3

Your web page loaded in react-native-webview can trigger native features by posting a JSON message. Use:

`html

`

Message schema:
- action: one of OPEN_MAP, CLOSE_CURRENT_SCREEN, SHOW_DIAL_PAD, MERCHANT_PORTAL_REDIRECT, SESSION_ID
- payload: object with action-specific fields:
- OPEN_MAP: { lat: number, lng: number, label?: string }
- SHOW_DIAL_PAD: { number?: string }
- MERCHANT_PORTAL_REDIRECT: { url: string }
- SESSION_ID: { sessionId: string }
- CLOSE_CURRENT_SCREEN: no payload required

Example App

This repository includes an example app demonstrating usage:

`bash
npm install
npm --workspace @saversapp/react-native-sdk-example run start
npm --workspace @saversapp/react-native-sdk-example run ios


or


npm --workspace @saversapp/react-native-sdk-example run android
`

Development

Common scripts:

`bash
npm run lint
npm run typecheck
npm test
npm run prepare # builds the library via bob
`

Troubleshooting


- Ensure peer dependencies are installed and linked
- On Android, grant runtime permissions for location
- If SaversAppSDK.initialized` logs missing modules, install the indicated packages

License

MIT