Skip to main content
Version: v2

RapidoReach React Native SDK

The RapidoReach React Native SDK lets you show rewarded survey content in your React Native app (offerwall / placements / quick questions) and receive reward events.

Latest release: 1.0.8 — brings safer init guards, error events, and Maven Central Android SDK.

Before you start​

Get an API key​

Create an app in the RapidoReach dashboard and copy your API key.

Requirements​

  • React Native: tested with React 19 / React Native 0.83.x
  • Android: minSdk 23 (native SDK requirement; new RN templates often use minSdk 24)
  • iOS: minimum iOS 15.1 (React Native 0.83 requirement)

Install​

Install the package:

npm install @rapidoreachsdk/react-native-rapidoreach

Then install iOS pods:

cd ios && pod install && cd ..

Note: the Android SDK is resolved from Maven Central (com.rapidoreach:cbofferwallsdk:1.1.0), so you don't need any credentials.

Usage​

Import​

import RapidoReach, { RapidoReachEventEmitter } from '@rapidoreachsdk/react-native-rapidoreach';

Initialize (required)​

Initialize once (app start or after login) and always await it:

await RapidoReach.initWithApiKeyAndUserId('YOUR_API_TOKEN', 'YOUR_USER_ID');

Most APIs return Promises and will reject with an error containing a code + message. Wrap calls in try/catch, especially during integration.

Common error codes:

  • not_initialized: call and await initWithApiKeyAndUserId first
  • no_activity (Android): call from a foreground screen (Activity available)
  • no_presenter (iOS): no active view controller available to present UI
  • not_linked: native module not installed/linked (run pods/gradle rebuild)

Example:

try {
  await RapidoReach.sendUserAttributes({ country: 'US' });
} catch (e) {
  console.warn('RapidoReach error:', e);
}

For non-Promise APIs (like showRewardCenter()), the native layer emits an onError event with { code, message } (see below).

Show the offerwall (reward center)​

RapidoReach.isSurveyAvailable((isAvailable) => {
  if (isAvailable) {
    RapidoReach.showRewardCenter();
  }
});

Tip: for more control and better UX, prefer placement-based checks using await RapidoReach.canShowContent(tag) and await RapidoReach.listSurveys(tag).

Rewards and callbacks​

For production reward attribution, use server-side callbacks whenever possible. See: ../api/callbacks

Client-side reward events​

const sub = RapidoReachEventEmitter.addListener('onReward', (quantity) => {
  // quantity: converted virtual currency amount
});

Events (survey availability, UI open/close, errors)​

Reward center opened/closed​

const opened = RapidoReachEventEmitter.addListener('onRewardCenterOpened', () => {});
const closed = RapidoReachEventEmitter.addListener('onRewardCenterClosed', () => {});

Survey availability​

const availability = RapidoReachEventEmitter.addListener(
  'rapidoreachSurveyAvailable',
  (surveyAvailable) => {
    // boolean
  }
);
const errSub = RapidoReachEventEmitter.addListener('onError', (payload) => {
  // payload: { code: string, message: string }
  console.warn('RapidoReach onError:', payload);
});

Remember to remove subscriptions on unmount:

sub.remove();
opened.remove();
closed.remove();
availability.remove();
errSub.remove();

Customization (navigation bar)​

RapidoReach.setNavBarColor('#211056');
RapidoReach.setNavBarText('Rewards');
RapidoReach.setNavBarTextColor('#FFFFFF');

Additional APIs​

  • updateBackend(baseURL, rewardHashSalt?) (staging/regional backends)
  • sendUserAttributes(attributes, clearPrevious?)
  • setUserIdentifier(userId)
  • Placement helpers: getPlacementDetails(tag), listSurveys(tag), hasSurveys(tag), canShowSurvey(tag, surveyId), canShowContent(tag), showSurvey(tag, surveyId, customParams?)
  • Quick Questions: fetchQuickQuestions(tag), hasQuickQuestions(tag), answerQuickQuestion(tag, questionId, answer)
  • Debug helpers: getBaseUrl(), enableNetworkLogging(enabled)
const tag = 'default';

const canShow = await RapidoReach.canShowContent(tag);
if (!canShow) return;

const surveys = await RapidoReach.listSurveys(tag);
const firstSurveyId = surveys?.[0]?.surveyIdentifier;
if (!firstSurveyId) return;

await RapidoReach.showSurvey(tag, firstSurveyId, { source: 'home_screen' });

User attributes​

Send attributes to improve targeting and eligibility (only send values you have consent for):

await RapidoReach.sendUserAttributes(
  { country: 'US', age: 25, premium: true },
  false // clearPrevious
);

Network logging (debug)​

RapidoReach.enableNetworkLogging(true);

const netSub = RapidoReachEventEmitter.addListener('rapidoreachNetworkLog', (entry) => {
  // { name, method, url, requestBody?, responseBody?, error?, timestampMs }
  console.log(entry);
});

Example app​

The repo includes a full example app:

cd example && npm install && cd ios && pod install && cd .. && npm run ios

Contact​

Please send questions or bug reports to admin@rapidoreach.com.