General reward callbacks
This page explains how to use our general reward callbacks.
What is a general reward callback?
A general reward callback is the default way of receiving information about conversions from BitLabs. The sole purpose of this callback is to inform you about rewards across all demand and survey reconciliations. It does not include state changes and additional information beyond that.
The general reward callback should be used, if states like PENDING
and offer/magic receipt RECONCILED
is not interesting to your system. The set up is easy and allows to set up one callback for each demand. This means, you can enable/disable demand on the fly without the need to integrate multiple callback endpoints.
How to set up the general reward callback
To set up the general reward callback, visit the Publisher Dashboard -> Apps -> Your App -> Integration -> Reward Callback:
To configure a new URL, press the cog wheel to open the callback URL configurator:
Multiple fields have to be filled out:
- Callback URL Host: Enter the callback endpoint URL you have set up.
- Protocol: In most cases, you want to leave it as is.
- Callback Parameter: Here you can add all the parameters you need to process the callbacks correctly. We highly recommend that you have the following parameters in there:
UID
,TX
,VAL
, andRAW
.- Additionally, if you have surveys enabled, we do recommend to use the
TYPE
parameter. It will return the type or state of the survey callback.TYPE
is only for surveys! If you want to know what state an offer or magic receipts callback has then please take a look at the offer and magic receipt callback documentation.TYPE
will always returnCOMPLETE
when you receive an offer or magic receipt callback.
- Additionally, if you have surveys enabled, we do recommend to use the
- Custom Parameter: In case you want to attach a parameter yourself, you can add it here. However, it does only support static parameters.
- Example URL: This shows you an example callback URL that you would receive. Keep in mind the hash in the example is not a valid one!
Here is an example of how a callback URL could be configured:
Press the Save button and then the Save Changes button in the top right.
How to test callbacks
To test if the callbacks are being sent correctly, use our survey test mode. It is recommended to use it, even when you are not implementing surveys, since the callbacks will look identical.
Enable the survey test mode on the BitLabs Dashboard -> Apps -> Your App -> Surveys -> Test Mode. Keep in mind that you also need to enable surveys. Changes might need up to 5 minutes to apply because of caching.
Once the test mode is enabled, visit your offer wall and go to the surveys section. On there press the top left tile to send a callback.
When you see a success screen, then the callback is sent. You now need to check in your system if you have processed it correctly.
If you see an error JSON response, you most likely have not set up the callbacks correctly.
Test callbacks will not be logged on the dashboard.
Updated about 2 months ago