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 App Token
Before we can get started, you should retrieve your App Token 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 offer wall in an iFrame. Please note that a new tab will be opened for the user to take the survey if you choose.
The offer wall 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 offer wall just by opening a link. You can configure the behavior of the offer wall and 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_APP_TOKEN]
<iframe src="https://web.bitlabs.ai/?uid=test1234&token=5fec306d-039a-41f3-94be-56ae3e74b41f"></iframe>
This is where you will need the App token from the dashboard, as you will need to replace "YOUR_APP_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. They get saved into the session storage to prevent the parameters from being overwritten after a page reload.
parameter | possible values | description |
---|---|---|
os | android , ios , desktop | overrides the operating system that is currently used. |
sdk | IFRAME , TAB | overrides where the offer wall is opened in an iframe or own tab |
in_app | true , false | use this parameter when implementing the offer wall via a web view in mobile apps. |
maid | mobile advertising ID | this parameter sets the mobile advertising ID. |
display_mode | surveys , offers ,gaming ,magic_receipts ,all , surveys,offers,... | overrides which modes will be enabled. You can select between surveys, offers, games and combine them as you like. |
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 offer wall 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 |
username | "username123" | The username the user set on your page. This is used to display the username instead of anonymous in the leaderboard widget |
tags | &mytag=test123 | Encoded parameters you want to pass into BitLabs. All additional parameters you pass into the URL will be appended to the callbacks/redirects in the same way you pass them in. |
offer-id | id of an offer returned from our offer API | This parameter allows you to open a specific offer when visiting the offerwall. This can be used to redirect users from push notifications or deep links directly to our offerwall and a specific offer. |
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 user's browser settings. It's possible to override this behavior 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 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 parameter and only keeps 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.
reserved character | space | ! | # | $ | % | & | ' | ( | ) | * | + | , | / | : | ; | = | ? | @ | [ | ] |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
percentage encoded | %20 | %21 | %23 | %24 | %25 | %26 | %27 | %28 | %29 | %2A | %2B | %2C | %2F | %3A | %3B | %3D | %3F | %40 | %5B | %5D |
Updated 14 days ago
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.