DocsMobile SDKs

React Native SDK

Show the offerwall in your React Native or Expo app on Android and iOS. Your server creates a short, single-use session, and the package opens the offerwall with it, so no key ever ships inside your app.

How it works

When the user taps your Earn button, your app asks your own server for a session.
Your server calls POST /v1/session with your API key and the user’s ID, and passes the token to the app.
The app calls Sharklio.open(token). The package opens the offerwall in a native screen.
Rewards reach your server through your postback, exactly as with the offerwall link. See Postbacks.

A token works once and for 10 minutes. Create a new one each time the user opens the offerwall. Your API key and your link hash salt stay on your server, so nothing in your app can be used to open another user’s offerwall.

Platform	Status
Android	Supported. The package uses the Android SDK inside.
iOS	Supported. The package uses the iOS SDK inside. Build with Xcode 16 or newer.
Expo	Supported in development builds, `npx expo prebuild` and EAS Build. Not in Expo Go, which cannot load native code.
Web and other platforms	Not supported. `open` checks the app ID and the token and then reports `UNSUPPORTED`.

Install

React Native 0.77 or newer, or Expo SDK 53 or newer. The package works with the New Architecture and, on React Native 0.77 to 0.81, with the old architecture too. Your Android project needs Kotlin 2.0 or newer, which these versions use by default. It is in the Sharklio npm registry. Add the registry for the @sharklio scope to the .npmrc file next to your package.json:

@sharklio:registry=https://sharklio.com/npm/

Then install the package and rebuild your app:

npm install @sharklio/react-native-offerwall
# or
yarn add @sharklio/react-native-offerwall
# Expo
npx expo install @sharklio/react-native-offerwall

npm, Yarn 1 and pnpm read .npmrc. With Yarn 2 or newer, add the scope to .yarnrc.yml instead:

npmScopes:
  sharklio:
    npmRegistryServer: "https://sharklio.com/npm"

Prefer a file? Download sharklio-react-native-offerwall-1.0.0.tgz and run npm install ./sharklio-react-native-offerwall-1.0.0.tgz.

There is nothing else to set up:

Android: the package adds the Sharklio Maven repository (only for the com.sharklio group) and the Android SDK to your Gradle build, the same way React Native adds its own repositories. If your settings.gradle sets repositoriesMode to FAIL_ON_PROJECT_REPOS or PREFER_SETTINGS, add maven { url = uri("https://sharklio.com/maven") } to the repositories there.
iOS: the package brings the Sharklio iOS SDK with it, and CocoaPods links and embeds it. Run pod install in your ios folder.

Expo

Add the config plugin to app.json, then run npx expo prebuild or start an EAS Build:

{
  "expo": {
    "plugins": ["@sharklio/react-native-offerwall"]
  }
}

Expo Go cannot load native code, so the offerwall does not open there: Sharklio.isSupported is false and open reports UNSUPPORTED. Use a development build to test.

Create a session on your server

POSThttps://api.sharklio.com/v1/session

Send the fields as a form or as JSON, with your API key in the Authorization header. This is the same request as for the Android SDK.

Field	Description
`user_id`requiredstring	The same user ID you receive in postbacks. 1 to 100 characters: letters, numbers, and `. _ @ : + -`.
`sub1` to `sub5`optionalstring	Your own tracking values. They are returned in the postback as `{sub1}` to `{sub5}`.

Errors: 400 invalid_user_id, 401 invalid_api_key, 403 app_not_live or user_blocked (do not show the offerwall), 405 method_not_allowed, 429 rate_limited (retry after the time in the Retry-After header).

Open the offerwall

Call init once with the App ID from the Integration tab. Then open the offerwall with a fresh token from your server.

import { Sharklio } from '@sharklio/react-native-offerwall';

Sharklio.init('YOUR_APP_ID');

async function openOfferwall() {
  // Your own endpoint, which creates the session for the signed-in user
  const res = await fetch('https://your-server.example/earn/session', { method: 'POST' });
  const { token } = await res.json();
  Sharklio.open(token);
}

open never throws for offerwall problems. They arrive as events, see Events.

Branding

The top bar of the offerwall screen shows the Sharklio mark, like the offerwall itself, with your offerwall title and colors from the Design tab of your dashboard. To set the title or color yourself, or to hide the mark, pass options. The color can be any color string React Native understands; transparency is ignored.

Sharklio.open(token, {
  title: 'Earn coins',
  toolbarColor: '#004ABB',
  showLogo: false,
});

Events

Sharklio.addListener returns a subscription. Remove it when your screen goes away.

useEffect(() => {
  const closed = Sharklio.addListener('closed', refreshBalance);
  const failed = Sharklio.addListener('error', (error) => {
    console.warn(`${error.code}: ${error.message}`);
  });
  return () => {
    closed.remove();
    failed.remove();
  };
}, []);

Event	When
`opened`	The offerwall finished loading its first page.
`closed`	The user closed the offerwall. A good moment to load the user’s balance from your server.
`error`	The listener receives a `SharklioError` with a `code`: `NOT_INITIALIZED`, `INVALID_APP_ID`, `INVALID_TOKEN`, `TOKEN_EXPIRED_OR_USED`, `NETWORK`, `UNSUPPORTED`, or `UNKNOWN`, the same names the native SDKs use. Create a new session and try again.

Errors from init and open arrive right after the call returns, so a listener you add in the same tick still receives them. TypeScript types are included.

App Store and Google Play privacy

The iOS SDK inside the package has a privacy manifest that lists what the offerwall collects, as described in our privacy policy. In App Store Connect, under App Privacy, and in Google Play’s Data safety form, add these data types for your app:

Data type	Linked to the user	Used for tracking	Purpose
User ID	Yes	No	App Functionality
Device ID	Yes	No	App Functionality
Coarse Location	Yes	No	App Functionality
Product Interaction	Yes	No	App Functionality

The user ID is the pseudonymous ID your server sends with the session, the device ID is used for fraud prevention, the coarse location comes from the IP address, and product interaction is the offers a user views, starts, and completes. The SDK does not track users across apps and does not use the advertising identifier. In Google Play’s Data safety form, the same data types are called User IDs, Device or other IDs, Approximate location, and App interactions.

Security

Create sessions on your server only. Never put the API key or the link hash salt in your app, because anyone can read an app’s files, including its JavaScript bundle.
Credit rewards only from the signed postback on your server, never from events in the app. Events can be faked on a user’s device.
Make sure your own endpoint that returns tokens only does so for the signed-in user.

Testing

Before you launch, create a session from your server for a test user ID and open it in a development build on an Android phone, an iPhone, or the iOS Simulator. Check that the offerwall opens, that an offer opens in the store or the browser, and that the back and close buttons work. Then send test postbacks from Integration status on the Integration tab of your app to check your server. Test on a normal home or mobile connection: on a VPN or a test device in the cloud, the offerwall shows a block page such as VPN detected instead of offers. See Testing.

Clicks that come through the package show as sdk in the {integration} postback macro and in the Reporting API, and as Mobile SDK in your dashboard, like the Android and iOS SDKs.

Changelog

1.0.0: first release. Sharklio.init and Sharklio.open with the same checks and error codes as the Android and iOS SDKs, opened, closed and error events, top bar options, a TurboModule for the New Architecture that also works with the old one, the Android SDK 1.1.0 added to Gradle automatically, the iOS SDK 1.0.1 bundled, and an Expo config plugin.

License

The package is free to use under the Apache License 2.0. The license file is in the package.

Install

# .npmrc
@sharklio:registry=https://sharklio.com/npm/

npm install @sharklio/react-native-offerwall

Create a session

POSTapi.sharklio.com/v1/session

curl -X POST "https://api.sharklio.com/v1/session" \
  -H "Authorization: Bearer $SHARKLIO_API_KEY" \
  -d "user_id=user_1234"

$ch = curl_init('https://api.sharklio.com/v1/session');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query(['user_id' => $userId]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);
$token = json_decode(curl_exec($ch), true)['token'] ?? null;

const res = await fetch('https://api.sharklio.com/v1/session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHARKLIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user_id: userId }),
});
const { token } = await res.json();

Your API key is in your dashboard under Apps, your app, Integration. Up to 600 requests per minute for each app.

Questions? [email protected]