iFrame/Web Integration

This page will guide you through the implementation of BitLabs within an iFrame or web link.

Account Set-Up and retrieving your API Key

Before we can get started, you should retrieve your API Key for your integration from the BitLabs Dashboard. If you haven't created an account yet, you can do so here and follow the instructions for the dashboard starting with Sign up & Set up..

Behaviour

It is possible to embed the offerwall in an iFrame. Please note that a new tab will be opened for the user to take the survey if you choose to do so.

The offerwall will open in their browser where they can complete surveys in exchange for your virtual currency.

Opening BitLabs

You can send your users into the BitLabs offerwall just by opening a link. You can configure the behavior of the offerwall what should happen after a survey is completed on the BitLabs dashboard in the General Settings.

// This will open the offerwall in a new tab
window.open('https://web.bitlabs.ai/?uid=test1234&token=5fec306d-039a-41f3-94be-56ae3e74b41f', '_blank')

// URL Structure: https://web.bitlabs.ai/?uid=[USER_ID]&token=[YOUR_API_TOKEN]

This is where you will need the API key from the dashboard, as you will need to replace "YOUR_API_TOKEN" with it. For "USER_ID", 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.

Optional parameter

The Offerwall uses query parameters to dynamically adjust the user experience.
Every unused query parameter is added to the survey opening URL.
Query parameters always have the highest priority and will override default values or values provided by settings set on our Dashboard. To prevent the parameters from being overwritten after a page reload they get saved into the session storage.

parameter

possible values

description

os

android, ios, desktop

overrides the operating system which is currently used.

sdk

IFRAME, TAB

overrides where the offerwall is opened in an iframe or own tab

display_mode

surveys, offers, all, surveys,offers,all

overrides which modes will be enabled
only surveys, only offers, offers and surveys or all

debug

true, false

used to activate the debug mode

exchange

any number

overrides the factor which gets multiplied with the payout value

currency

string

overrides currency symbol with a string

currency_icon

icon URL

overrides currency symbol with an icon from the given URL

custom_logo_url

icon URL

overrides the custom logo

width

default, full_width

overrides the offerwall width:
default (700px) or full_width (100%)

element_border_radius

none, small, medium, big

overrides the border radius

navigation_color

colors

overrides the navigation color

background_color

colors

overrides the background color

interaction_color

colors

overrides the interaction color

survey_icon_color

colors

overrides the survey icon color

theme

theme

sets the color scheme the Offerwall should use

hash

hmac sha1 hash from the URL

to validate the set parameter settings more information

Colors

The color parameters accept a simple hex color code like #ff00ff or a linear-gradient.
The linear gradient needs this format: linear-gradient(45deg, #ff0000 0%, #00ff00 100%). (the numbers can be changed)

Theme

The Offerwall can operate in two color schemes (themes). Light and Dark. The theme is automatically set on startup based on the browser setting of the user. It's possible to override this behaviour with the theme query parameter. Just append theme=LIGHT or theme=DARK to force a given theme.

Hashing

To make these parameters a bit more save we suggest to hash the finished URL with hmac sha1 and the app/api token as hash salt.
Example:

import { createHmac } from 'crypto';

// URL with all desired parameters set
let urlWithParams = 'https://example.com/surveys?uid=123&token=abc123&width=full_width&navigation_color=%23ffff00';

// app/api token
const salt = 'abs123';

// create hash (result from this example: 6b9e14a31b642aed06a12882a13ae2fcb38ece4d)
const hash = createHmac('sha1', salt).update(urlWithParams).digest('hex');

// add hash to the URL
const finishedURL = urlWithParams + '&hash=' + hash;

// finished URL: https://example.com/surveys?uid=123&token=abc123&width=full_width&navigation_color=%23ffff00&hash=6b9e14a31b642aed06a12882a13ae2fcb38ece4d

❗️

Important!!!

special characters need to be changed to valid URL escape characters before adding the parameter value to the URL and the hash must be created with these escape characters!!!

special character

space

(

)

%

,

URL escape code

%20

%23

%28

%29

%25

%2c


Your next Step

You have now implemented BitLabs with your project. If you haven't done it already, it is time to configure server-to-server callbacks and the look and feel of your app.

Did this page help you?