---
updatedAt: 2026-04-07T05:28:57.000Z
agentTools:
  projectIndex: https://developer.bitlabs.ai/llms.txt
---

# BitLabs React Native SDK

This page will guide you through the integration of our React Native SDK into your app.

## Version History

To check the latest version and all the previous ones of the SDK, you can check [this page](https://github.com/BitBurst-GmbH/bitlabs-react-native/blob/master/CHANGELOG.md).

## Account Set-Up and retrieving your API Key

Before we can get started with implementing the SDK, you should retrieve your API Key for your integration from the BitLabs Dashboard.

## Adding the SDK

In your project directory, open a terminal and add:

```shell yarn
yarn add bitlabs
```
```shell npm
npm install bitlabs
```

<Callout icon="📘" theme="info">
  The library uses Native Modules, so expect that it will be installing via `pod install`when you run it for the first time. If it didn't you may need to do so manually.
</Callout>

## BitLabsOfferwall

This is module sets up the Offerwall and presents it to the user. You **must** initialise it before anything else.

```typescript
import { BitLabsOfferwall } from 'bitlabs';

  BitLabsOfferwall.init(APP_TOKEN, UID);
```

**APP\_TOKEN**:  This is the API key from the dashboard.\
**UID**: You will need to dynamically insert the user id for each app user. Make sure the id used here is unique and that it does not change, as the user's profile will be stored under this id.

### Launch the Offerwall

```typescript
import { BitLabsOfferwall } from 'bitlabs';

BitLabsOfferwall.launch();
```

This will launch the Offerwall. A new screen will appear.

> 👍 That's it!
>
> Anything below is optional but can improve the user experience.

### Custom & Configuration Parameters

```typescript
import { BitLabsOfferwall } from 'bitlabs';

BitLabsOfferwall.setTags({
  premium_user: 'true', // custom tag
  display_mode: 'offers', // Configuration parameter
});
```

Tags can be of two natures:\
**Custom**: When you want to send something custom to your [Server-To-Server Callback](https://developer.bitlabs.ai/docs/custom-parameters-in-callbacks#what-are-custom-parameters), you pass it here as a tag.\
**Configuration**: You use these to configure the Offerwall. Refer to [this guide](https://developer.bitlabs.ai/docs/iframeweb-integration#opening-parameters).

### Callbacks

```typescript
import { BitLabsOfferwall } from 'bitlabs';

BitLabsOfferwall.setOnReward((reward) => {
  console.log(`Reward this time: ${reward}`);
});

BitLabsOfferwall.setOnOfferwallClosed(() => {
  console.log('Offerwall closed');
});
```

Both are invoked when the user leaves the Offerwall. The reward is the total reward of surveys the user got since the Offer Wall is opened until it is closed. The reason we have both is to separate semantic code.

<Callout icon="📘" theme="info">
  The reason we have both is to separate semantic code. It is also planned in the future that the onReward callback invocation behaviour will change.
</Callout>

### Advertising ID (iOS)

```typescript
import { BitLabsOfferwall } from 'bitlabs';

BitLabsOfferwall.requestTrackingAuthorization()
```

This will fetch the Ad ID internally. So you only have to call it before launching the Offerwall.

> 📘 iOS Only
>
> This is only for iOS, because for Android, this already happens automatically without needing to call this.

<Callout icon="❗️" theme="error">
  You **must** add the following to `ios/<ProjectName>/Info.plist`:

  ```xml PLIST
  <key>NSUserTrackingUsageDescription</key>
  <string>Custome Message that is shown to the user.</string>
  ```

  Don't forget to the add your own custom message in the string.
</Callout>

### Deep Linking

#### To a specific Offer

```typescript
BitLabsOfferwall.openOffer(offerId: string)
```

#### To a specific Magic Receipts Offer

```typescript
BitLabsOfferwall.openMagicReceiptsOffer(offerId: string)
```

#### To a specific Magic Receipts Merchant

```typescript
BitLabsOfferwall.openMagicReceiptsMerchant(merchantId: string)
```

<br />

## BitLabsAPI

This is module sets up the communication with BitLabs API so that you can get specific data from it. You **must** initialise it before using its functions.

```typescript
import { BitLabsAPI } from 'bitlabs';

BitLabsAPI.init(APP_TOKEN, UID);
```

**APP\_TOKEN**:  This is the API key from the dashboard.\
**UID**: You will need to dynamically insert the user id for each app user. Make sure the id used here is unique and that it does not change, as the user's profile will be stored under this id.

### Get Surveys

```typescript
import { BitLabsAPI } from 'bitlabs';

BitLabsAPI.getSurveys()
  .then((surveys) => {
    console.log(`Surveys found: ${surveys.length}.`);
  })
  .catch((error) => console.log(error.message));
```

This will get all available surveys for the user with **UID**. It's a promise that resolves with a list of type **Survey**.

Each **Survey** has the following properties:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        `Type	`
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        string
      </td>

      <td>
        The id of the Survey.
      </td>
    </tr>

    <tr>
      <td>
        type
      </td>

      <td>
        string
      </td>

      <td>
        Values are survey or start_bonus. Start Bonus is a legacy term and refers to the initial profiler.
      </td>
    </tr>

    <tr>
      <td>
        clickUrl
      </td>

      <td>
        string
      </td>

      <td>
        This link can be used as is to open the survey.
      </td>
    </tr>

    <tr>
      <td>
        cpi
      </td>

      <td>
        string
      </td>

      <td>
        CPI of this survey in USD without any formatting applied.
      </td>
    </tr>

    <tr>
      <td>
        value
      </td>

      <td>
        string
      </td>

      <td>
        CPI formatted according to your app settings. Can be shown to the user directly.
      </td>
    </tr>

    <tr>
      <td>
        loi
      </td>

      <td>
        number(float)
      </td>

      <td>
        Assumed length of the survey in minutes.
      </td>
    </tr>

    <tr>
      <td>
        country
      </td>

      <td>
        string(ISO 3166-1 ALPHA-2)
      </td>

      <td>
        * <br />
      </td>
    </tr>

    <tr>
      <td>
        language
      </td>

      <td>
        string(ISO 639-1)
      </td>

      <td>
        * <br />
      </td>
    </tr>

    <tr>
      <td>
        rating
      </td>

      <td>
        int
      </td>

      <td>
        Difficulty ranking of this survey. 1-5 (1 = hard, 5 = easy). Minimum value is 1, maximum value is 5.
      </td>
    </tr>

    <tr>
      <td>
        category
      </td>

      <td>
        Category(name: string, iconUrl: string, iconName: string, nameInternal: string)
      </td>

      <td>
        The details of the category this Survey is classified in.
      </td>
    </tr>

    <tr>
      <td>
        tags
      </td>

      <td>
        ## Versi
      </td>

      <td>
        Values are `recontact` or `pii`  
        recontact = this is a follow-up survey for specific users that completed a different survey before;  
        pii = this survey might collect sensitive information from the user;
      </td>
    </tr>
  </tbody>
</Table>

### Check for Surveys

```typescript
import { BitLabsAPI } from 'bitlabs';

BitLabsAPI.checkSurveys()
  .then((hasSurveys) => console.log(`Has Surveys: ${hasSurveys}`))
	.catch((error) => console.log(error.message))
```

This will check if there is at least one survey for the user with corresponding **UID**. It's a promise that resolves with a boolean.

## Whitelist HTTP Domains

Since BitLabs works with a plethora of survey providers, we can't always make sure that the domains are secured with HTTPS schemes. So you need to whitelist some providers if needed.

### For iOS:

1. Navigate to **rojectRootDirectory]/i/ios/rojectDirectory]/i/info.plist**
2. Paste the following inside the main **\<dict>**:

```xml
<key>NSAppTransportSecurity</key>  
	<dict>  
		<key>NSExceptionDomains</key>  
		<dict>  
			<key>samplicio.us</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>cint.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>qualtrics.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>spectrumsurveys.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>decipherinc.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>ssisurveys.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
			<key>lucidhq.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>paradigmsample.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>focusvision.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>vi.ga</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>opinionetwork.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>surveyrouter.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>opinionbar.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>prsrvy.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>ptrack1.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>globaltestmarket.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>  
        	<key>eocucom.com</key>  
			<dict>  
				<key>NSIncludesSubdomains</key>  
				<true/>  
				<key>NSExceptionAllowsInsecureHTTPLoads</key>  
				<true/>  
			</dict>		
		<key>prodegemr.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>swagbucks.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>sgizmo.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>surveygizmo.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>reviewrobin.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>questmindshare.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>peanutlabs.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>marketknowledgesurveys.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>dubinterviewer.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>confirmit.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>survia.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
    	<key>insights.supply</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
		<key>roirocket.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSExceptionAllowsInsecureHTTPLoads</key>
			<true/>
		</dict>
	</dict>
</dict
```

#### If you want to allow any HTTP request instead, inside the *info.plist* put the following:

```xml
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
      <true/>
</dict>
```

### For Android:

1. Download the [whitelist xml](https://github.com/BitBurst-GmbH/bitlabs-react-native/blob/master/example/android/app/src/main/res/xml/network_security_config.xml).
2. Put the downloaded file inside **rojectRootDirectory]/a/android/app/src/main/res/xml/**
3. Inside **rojectRootDirectory]/a/android/app/src/main/AndroidManifest.xml** put the following:

```xml
<Application
             ...
             	android:networkSecurityConfig="@xml/network_security_config"
             ...>
  ...
</Application>
```

#### If you want to allow any HTTP request instead, inside *AndroidManifest.xml* put the following:

```xml
<Application
             ...
             	android:usesCleartextTraffic="true"
             ...>
  ...
</Application>
```

# Gaming offers on iOS

To enable gaming offers for SDK integrations on iOS, you need to follow this [guide](https://developer.bitlabs.ai/docs/enable-games-for-sdk-integrations-for-ios).