iFrame integration

To provide the best experience for your users on your platform, we advise integrating BitLabs as an iFrame. BitLabs offers a lot of customization, which will allow you to configure it in a way, where it would blend into your style guide and website branding.

How to integrate via iFrame

Use the following code snipped to implement the BitLabs offer wall into your iFrame:

<iframe src="https://web.bitlabs.ai/?uid={USERID}&token={TOKEN}"></iframe>

In the above example, you need to replace the values of the following query parameters:

• uid: Replace the placeholder with the user ID you want to receive back from our callbacks in the [%UID%] parameter.
• token: To identify the offer wall, you need to replace the placeholder with your offer wall token. You can find the token on the BitLabs Dashboard -> Apps -> Your app placement -> Integration -> App/API Token.

Link integration

Besides integrating via iFrame, you can also let users open the link to the offer wall directly. However, this is not recommended, since it will have downsides compared to the iFrame integration:

• Some opening query parameters do not get stored in locally. This means upon refreshing the offer wall page, some query parameters will get lost.
• In case the user clears their cache, the user id and token, which got stored locally, will be removed and the user will no longer be able to visit the offer wall unless they click on the opening URL with all the query parameters attached.

In general, we advice you to always integrate via an iFrame on Web.

How to integrate via a link

Similar to the iFrame integration, the offer wall will be opened via the web.bitlabs.ai URL. To open the offer wall in a new tab, you can use this JavaScript example snippet:

// This will open the offerwall in a new tab
window.open('https://web.bitlabs.ai/?uid={UID}&token={TOKEN}', '_blank')

Replace the placeholders according to what is explained in the iFrame integration guide.

Multiple offer wall placements

You can have multiple placements of the BitLabs offer wall on your website or app. It doesn't matter if you are using both mobile and web, the same app token can be used for all types of integrations, even if you want to use multiple different types of integrations at the same time.

In case you want to use one app token, but have placements for each demand type separately, that is also possible by using the display_mode opening parameter. Learn more about opening parameters in the following section.

Opening parameters

To add more configuration options or information to your offer wall, we provide a variety of opening query parameters.

Mandatory parameters

These parameters are not optional and always have to be added to an opening link, otherwise the offer wall does not work.

Cosmetic parameters

These parameters change the appearance of the offer wall.

Colors

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

Theme

The Offerwall can operate in two themes: Light and Dark. The theme is automatically set on startup based on the user's browser settings. However, it is possible to override the theme by using the theme query parameter. Append theme=LIGHT or theme=DARK to force a given theme.

Currency exchange rate parameter

This parameter will change the exchange rate of the currency. It only affects the front end and will not change the exchange rate on the dashboard (our backend).

🚧

This parameter is only available for the survey currency exchange rate.

Other parameters

Hashing

To make these parameters a bit more secure, we suggest hashing the finished URL with hmac sha1 and the App/API token as hash salt. This is only recommended if you change currency or exchange rate parameters. If the hash is invalid, the offer wall will drop all extra parameters and only keep the UID and the token. This includes that any additional tags get dropped as well.

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

To comply with RFC3986 the query parameter values have to be percentage encoded. This means to replace reserved characters with their corresponding percentage encoded code. These codes also have to be uppercase. You can find a list of these codes below.