Survey callbacks
This page describes on how to utilize callbacks for different survey states.
What is a survey callback?
Unlike an offer or magic receipt callback, there is no dedicated survey callback field. Instead, the General Reward Callback field will be used. The states will be received via the TYPE
parameter.
How to set up survey callbacks
To set up the survey callbacks, 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
.- For surveys, we also recommend to add the following parameters:
TYPE
.TYPE
will return the state of a survey:SCREENOUT
,RECONCILIATION
,START_BONUS
,COMPLETE
. Learn more about the survey states (type) here.
- For surveys, we also recommend to add the following parameters:
- 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.
Survey states
Each survey callback will have a different state (type). The following states (types) are available:
COMPLETE
: The COMPLETE
callback will be sent when a survey reward is being sent. A COMPLETE
callback can also be sent if a user completes an install task, which usually gives a $0 reward. Notice that for surveys it is COMPLETE
instead of COMPLETED
.
START_BONUS
: The START_BONUS
callback will be sent when a user completes the starting bonus survey. It contains a reward similar to the COMPLETE
callback. To receive START_BONUS
callbacks separately, we offer a separate callback field.
SCREENOUT
: A SCREENOUT
callback will be sent when an offer is completed, but the reward is still pending. This can be the case when delayed crediting (a security feature) is enabled. After a PENDING
callback was sent, a COMPLETED
or RECONCILED
can follow.
RECONCILIATION
: A RECONCILIATION
callback will be sent when a survey reward is reconciled. This means that we deduct the reward, mainly because of fraudulent reasons. 95% of reconciliations occur in the first 30 days after completion, but technically a reconciliation can occur anytime. A RECONCILIATION
callback can occur after a COMPLETE
was sent. Notice that for surveys it is RECONCILIATION
instead of RECONCILED
.
Reconciliation callbacks
These callbacks notify you when there has been a reconciliation of previous transactions. This happens when researchers are not satisfied with the answers of a user, for example when a user just chose the first option for each question without any context. In this case, the transaction has to be reversed. If you are paying users with real money, we highly recommend setting up these reconciliation callbacks as they may prevent users from cashing out unrightfully.
Although it does not happen often, note that it can happen that a complete callback receives more than one following reconciliation callback. For example: a user completes a $2 survey. After that, you receive a reconciliation callback of -$2 indicating that the complete was reconciled. Sometimes, you might receive another reconciliation callback of $2 again showing that the reconciliation was send incorrectly and should be inverted again.
Note that every reconciliation callback has a unique transaction ID that is also different from the transaction ID of the complete callback. If you need the transaction ID of the complete callback instead, have a look at the [%REF%] parameter.
To receive reconciliation callbacks on a separate endpoint, we offer a dedicated callback field.
Survey parameters
For surveys we do provide additional parameters for additional information:
Parameter | Type | Description |
---|---|---|
[%TYPE%] | String | Type of the callback ("COMPLETE", "SCREENOUT","RECONCILIATION", "START_BONUS") |
[%REASON%] | String | Explains the reason for a screenout. It can be one of the following: NONE: The user faced a screenout during the client survey ERROR: Something went wrong before the user joined the client survey. QUALITY: The user faced a screenout due to quality issues CLICK: The user faced a screenout during the qualification process |
[%RAT%] | Integer | Survey Rating from 0 to 5 |
[%NET%] | String | Internal Survey Source/Mediation Layer |
[%LOI%] | Integer | Length of the Survey in minutes. |
[%CAT%] | String | Category of the Survey. |
[%COUNTRY%] | String | The Country the User took the survey from as ISO Code. (Example: US, DE, FR) |
[%DELAY%] | Integer | Delay in seconds for which BitLabs withholds a callback to the publisher. In most cases this is zero. |
[%V2SID%] | String | Unique survey id returned in /v2/client/surveys endpoint. Only available if new integration API is used. |
For a full list of all parameters click here.
How to test survey callbacks
To test if the callbacks are being sent correctly, use our survey test mode.
Enable the survey test mode on the BitLabs Dashboard -> Apps -> Your App -> Surveys -> Test Mode. 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 any of the first 5 tiles 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