What are custom parameters?

Custom parameters are static or dynamic values that can be passed into BitLabs to receive them in the callbacks. For example: You want to add a dynamic session ID to the opening of an offer wall and receive those in the callbacks. You can generate this session ID on your end and pass it into the offer wall in multiple ways, depending on the demand and integration type you are using.

Static custom parameters

The easiest way to pass in static parameters is to set up custom parameters in the callback editor on the dashboard (BitLabs Dashboard -> Apps -> Select your app -> Integration). In the example below you can see that the custom parameter source was added and included the value bitlabs.

To add a new custom parameter, you can click on the + sign and then fill out the parameter name and value.

Dynamic custom parameters

The dynamic ones allow you to pass in data when opening the offer wall or clicking on an offer. Different ways have to be used to pass in the data depending on the integration and demand.

Offer wall iframe & web integration

For the offer wall iframe integration, you can use the opening query parameters to pass in custom parameters. Just add a new query parameter to the URL and you will receive it in the callbacks:

https://web.bitlabs.ai/?token=YOUR_TOKEN&uid=USERID&my_custom_parameter=123

In the example above you will receive the my_custom_parameter parameter in the callbacks, exactly like you would for other parameters with the value 123.

Callback example:

https://publisher.com?UID=testuser&VAL=1000&RAW=1&TXID=101&my_custom_parameter=123

This currently does not work for magic receipts events.

SDK custom parameters (tags)

To see how to use custom parameters or tags in the SDK, please read the SDK documentation of the SDK of your choice first and then come back to this documentation. Depending on the SDK, the way to add custom tags will be different. Here is an example:

If you want to use your own parameters, you need to add them via a function (different function depending on the SDK):

BitLabs.addTag("my_custom_parameter", "123")

In the example above a new custom parameter was added called my_custom_parameter which has a value of 123.

The result of the callback will be the following:

https://publisher.com?UID=testuser&VAL=1000&RAW=1&TXID=101&my_custom_parameter=123

This approach currently does not work for the magic receipts SDK integration.

Offer API (user based and static)

For the offer API, the custom parameter work a bit differently. Here you want to pass in custom parameters as subparameters URL encoded in the s4 query parameter in the offer click URL:

https://bitlabs.link/vc/naubqWo/users/326209820/offers/698523?s2=bitburst%3Auser-based&s3=UID&s4=my_custom_parameter%3D123&source_type=user_based_api

In the callback, you will then be able to grab the subparameter as a normal parameter from the callback URL.

Callback example:

https://publisher.com?UID=testuser&VAL=1000&RAW=1&TXID=o101&my_custom_parameter=123

Survey API

For the survey API, you can append custom parameters in the tags query parameter when calling the API. They need to be URL encoded and we will turn them into your needed query parameters in the callback.

https://api.bitlabs.ai/v2/client/surveys?platform=MOBILE&os=ANDROID&tags=my_custom_parameter%3D123

Callback example:

https://publisher.com?UID=testuser&VAL=1000&RAW=1&TXID=101&my_custom_parameter=123

Magic Receipts API

For the magic receipts API, you can append custom parameters in the tags query parameter when calling the upload receipts endpoint. They need to be URL encoded and we will turn them into your needed query parameters in the callback.

https://receipts.bitlabs.ai/?cmd=mp-mr-api-upload-receipt&imageCount=1&offerIDs=7233287&merchantID=11&tags=my_custom_parameter%3D123

Callback example:

https://publisher.com?UID=testuser&VAL=1000&RAW=1&TXID=mr101&my_custom_parameter=123