What are custom parameters?

Custom parameters let you pass static or dynamic values into BitLabs and have those same values returned to you in callbacks/postbacks.

For example, if you want to track a dynamic session ID, you can generate the session ID on your side, include it when opening the offer wall, and then receive it back in the callback for attribution or tracking purposes.

Depending on the demand source and integration type you’re using, there are multiple ways to pass these custom parameters into the offer wall.

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.

📘
Please do not add s4 or any other query parameters in the dashboard callback configuration. These parameters are automatically appended to the callback by BitLabs.

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

The next example shows you how to add multiple URL encoded parameters:

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

Callback outcome:

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

Survey API

For the survey API, you can append custom parameters in the tags query parameter to the click_url. 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/clicks?i=0bb13fe2-d8a8-43c3-ad9e-7a68cb1e1fae&s=5baeeaa0-f17f-4f8f-93ba-1fe5643bd273&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

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.