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 RECONCILEDis 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, and RAW.
  • 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 return COMPLETE when you receive an offer or magic receipt callback.
• 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

We offer a callback tester on the dashboard to test your configured callback endpoints. Learn more about it here.

Legacy way of testing

🚧

The following part of the documentation explains how callbacks were tested before the callback tester on the dashboard existed. We highly recommend not using the following method anymore!

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.