@justgold/rn-sdk

Embed the JustGold gold & silver trading experience in your React Native app with JustGoldConnect.

The wrapper loads the trading UI from JustGold CDN (signed URL from the Partner API). You do not host or deploy the UI yourself.

| | | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | Registry | npm | | Version | 1.1.18 — see CHANGELOG | | Publish | Manual — GitHub Actions | | Partner docs | Quickstart · RN guide | | Requires | @justgold/partner-sdk on your backend |

Installation

yarn add @justgold/rn-sdk react-native-webview react-native-safe-area-context

| Peer dependency | Version | | -------------------------------- | ------- | | react | >= 18 | | react-native | >= 0.70 | | react-native-webview | >= 13 | | react-native-safe-area-context | >= 4 |

iOS: run pod install in your ios/ directory after adding the packages.

Wrap your app (or SDK screen) in SafeAreaProvider.

Quick start

Your backend issues a short-lived session JWT (and optional refresh token). Pass them to JustGoldConnect — never put client_secret in the app.

import { SafeAreaProvider } from 'react-native-safe-area-context';
import { JustGoldConnect } from '@justgold/rn-sdk';

<SafeAreaProvider>
  <JustGoldConnect
    token={sessionToken}
    refreshToken={refreshToken}
    sandbox={false}
    locale="en"
    theme={{ mode: 'light', primaryColor: '#2563eb' }}
    onClose={() => navigation.goBack()}
    onAuthRequired={() => refreshSessionFromBackend()}
    onSessionExpired={() => refreshSessionFromBackend()}
    onTokensRefreshed={({ sessionToken, refreshToken: rt }) => persistTokens(sessionToken, rt)}
    onPaymentRequired={(payload, _resume) => {
      navigation.navigate('PartnerPayment', payload);
    }}
    onError={err => {
      if (err.fatal) {
        // SDK cannot load — show your UI or close
      } else {
        console.warn(err);
      }
    }}
    onAnalytics={({ name, params }) => {
      // Optional — Mixpanel / Firebase / etc.
      console.log(name, params);
    }}
  />
</SafeAreaProvider>;

| Prop | Description | | ------------------- | ------------------------------------------------------------------------------ | | token | Required. Session JWT from your backend | | refreshToken | Enables silent renewal before JWT expiry | | sandbox | true → sandbox API + CDN; omit or false → production | | sdkUiSignedUrl | Optional pre-signed CDN URL from your backend (see below) | | sdkUrl | Optional UI URL override (advanced) | | locale | 'en' or 'ar' | | theme | Light/dark mode, brand colors, optional partner branding | | onClose | User closed the SDK | | onAuthRequired | Re-issue session (reason in payload) — prefer over closing the SDK | | onSessionExpired | Re-issue session from your backend | | onPaymentRequired | User confirmed a quote — collect payment on your side | | onAnalytics | Optional UI taps (ANALYTICS / Invest_*). Also on onSdkEvent | | onError | { code, message, fatal? } — if fatal, show your UI or close; otherwise log |

SDK UI (CDN)

By default, JustGoldConnect calls:

GET /v1/sdk/ui-url?sandbox=true|false
Authorization: Bearer <sessionToken>
→ { "url": "<signed CDN URL>", "expiresAt": "..." }

The signed URL is valid for 1 hour. The wrapper fetches a fresh URL when loading the WebView.

Alternatively, your backend can call the same endpoint and return sdkUiSignedUrl with the session tokens — pass it to JustGoldConnect to skip the in-app fetch.

Payment handoff

When the user confirms buy, sell, or delivery, the SDK creates a Pending transaction and calls onPaymentRequired. Your app:

1. Collects payment (your PSP / wallet)
2. Updates status via your backend: PATCH /v1/transactions/:id (HMAC) — Completed, Failed, or Cancelled if the user taps Back
3. Closes your payment screen — the SDK polls: result for complete/fail, or restore buy/sell with the original amount on cancel

Recommended: keep JustGoldConnect mounted and present your payment UI on top (modal, overlay, or new screen).

If you must unmount JustGoldConnect during payment (for example a native PSP SDK), remount it afterward with the same token and refreshToken. After Cancelled / Stale the SDK restores the trading form, not pending.

The second argument to onPaymentRequired (resume) is optional and can speed up navigation after payment completes.

If payment stays Pending for 10 minutes, JustGold marks it Stale. Do not PATCH Stale.

Session recovery (1.1.5+)

When auth fails, the embedded UI runs multi-phase recovery (retries + foreground auto-retry). Implement onAuthRequired to fetch fresh session tokens from your backend — do not unmount JustGoldConnect on the first failure. Refresh session again when the app returns to foreground if the SDK is still open.

Permissions

The SDK does not require camera, location, or other sensitive permissions.

Your app must declare Android INTERNET in the main manifest (not only debug) — required for CDN and API calls in release APKs:

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET"/>

iOS uses standard HTTPS (App Transport Security).

Environments

| Environment | Partner API | SDK CDN (signed) | | ----------- | ---------------------------------------- | -------------------------------- | | Sandbox | https://api.stage.partner.justgold.app | https://sdk.stage.justgold.app | | Production | https://api.partner.justgold.app | https://sdk.justgold.app |

Set sandbox: true for sandbox integration and testing; false or omit for production. API and CDN hosts are resolved automatically from this flag.

Support

• React Native integration guide
• Partner SDK Quickstart
• CHANGELOG
• Contact your JustGold onboarding team for sandbox credentials and go-live approval