Skip to main content
Version: v2

RapidoReach Flutter SDK

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

Before you start​

Get an API key​

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

Requirements​

  • Flutter: >= 3.0.0
  • Dart: ^3.8.0
  • Android: minSdk 23
  • iOS: minimum deployment target 12.0

iOS privacy notes (IDFA / ATT)​

If your app uses Apple’s Advertising Identifier (IDFA) for ad attribution/retargeting, implement App Tracking Transparency (ATT) in your app and include NSUserTrackingUsageDescription in your iOS Info.plist.

Install​

Add the dependency:

dependencies:
  rapidoreach: ^1.1.0

Then run:

flutter pub get

This plugin already contains the native SDKs so you don't need to hit any public Maven/CocoaPods repos:

  • Android: the AAR is shipped under android/maven/com/rapidoreach/cbofferwallsdk/1.1.0.
  • iOS: the RapidoReach Objective-C sources (v1.0.7) live inside ios/Classes/RapidoReach.

Quick start​

Import​

import 'package:rapidoreach/rapidoreach.dart';

Initialize (required)​

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

await RapidoReach.instance.init(
  apiToken: 'YOUR_API_TOKEN',
  userId: 'YOUR_USER_ID',
);

Show the offerwall (reward center)​

await RapidoReach.instance.showRewardCenter();

Most APIs return Futures and can throw:

  • Dart-side integration mistakes throw StateError (for example, calling methods before init).
  • Native failures typically throw PlatformException with a code and message.

Common error codes:

  • not_initialized: call and await init first
  • no_activity (Android): call from a foreground Activity (don’t call from a background isolate)
  • no_presenter (iOS): no active UIViewController available to present UI

Example:

try {
  await RapidoReach.instance.sendUserAttributes(
    attributes: {'country': 'US'},
  );
} catch (e) {
  // Show a friendly message in debug builds.
}

Rewards and callbacks​

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

Client-side reward events​

RapidoReach.instance.setOnRewardListener((quantity) {
  // quantity: converted virtual currency amount
});

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

Reward center opened/closed​

RapidoReach.instance.setRewardCenterOpened(() {});
RapidoReach.instance.setRewardCenterClosed(() {});

Survey availability​

RapidoReach.instance.setSurveyAvaiableListener((available) {
  // available is typically 1/0
});

Error events (optional)​

RapidoReach.instance.setOnErrorListener((message) {
  // Useful for logging/QA.
});

Customization (navigation bar)​

await RapidoReach.instance.setNavBarText(text: 'Rewards');
await RapidoReach.instance.setNavBarColor(color: '#211548');
await RapidoReach.instance.setNavBarTextColor(textColor: '#FFFFFF');

Placements let you control where/how content is shown in your app (and support multiple placements).

final tag = 'default';
final canShow = await RapidoReach.instance.canShowContent(tag: tag);
if (!canShow) return;

final surveys = await RapidoReach.instance.listSurveys(tag: tag);
final firstSurveyId = surveys.isNotEmpty
    ? surveys.first['surveyIdentifier']?.toString()
    : null;
if (firstSurveyId == null || firstSurveyId.isEmpty) return;

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

Available placement helpers:

  • getPlacementDetails(tag)
  • listSurveys(tag)
  • hasSurveys(tag)
  • canShowContent(tag)
  • canShowSurvey(tag, surveyId)
  • showSurvey(tag, surveyId, customParams?)

Quick Questions​

final tag = 'default';
final payload = await RapidoReach.instance.fetchQuickQuestions(tag: tag);
final has = await RapidoReach.instance.hasQuickQuestions(tag: tag);

if (has) {
  await RapidoReach.instance.answerQuickQuestion(
    tag: tag,
    questionId: 'QUESTION_ID',
    answer: 'yes',
  );
}

User attributes​

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

await RapidoReach.instance.sendUserAttributes(
  attributes: {'country': 'US', 'premium': true},
  clearPrevious: false,
);

Network logging (debug)​

RapidoReach.instance.setNetworkLogListener((payload) {
  // payload: { name, method, url?, requestBody?, responseBody?, error?, timestampMs }
});

await RapidoReach.instance.enableNetworkLogging(enabled: true);

You can read the configured base URL:

final baseUrl = await RapidoReach.instance.getBaseUrl();

Android multidex (only if you hit dex limits)​

If you hit dex method count issues, enable multidex in your app:

android {
  defaultConfig {
    multiDexEnabled true
  }
}

dependencies {
  implementation "androidx.multidex:multidex:2.0.1"
}

Example app​

The repo includes a full example app (init, offerwall, placements, surveys, quick questions, attributes, network logs):

cd example && flutter run