Offer callbacks
This page describes on how to utilize callbacks for different offer states.
What is an offer callback?
An offer callback is a specific callback only sent for offer state changes (also called stateful offer callbacks). The offer callbacks work differently from the general reward callbacks since you will receive all the different states of an offer or offer task as well as additional information about the offer or offer task.
How to set up offer callbacks
To set up the offer callbacks, visit the Publisher Dashboard -> Apps -> Your App -> Integration -> Offer Reward Callback:
IMPORTANT: You can enable the stateful offer callbacks which have the following effects:
- Offer callbacks for all states will be sent now (Before only
COMPLETED
andRECONCILED
would be sent)- Please configure the Offer Reward Callback and the Offer Reconciliation Callback separately.
- The transaction ID for each state change will be the same
- The
TYPE
parameter will return the typestate_change
- Reconciliation callbacks are no longer negative
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 offers, we also recommend to add the following parameters:
offer_id
,task_id
andoffer_state
.offer_state
will return the state of an offer:PENDING
,RECONCILED
,COMPLETED
. Learn more about the offer states here.
- For offers, 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.
Offer states
Each offer callback will have a different state. The following states are available:
COMPLETED
: The COMPLETED
callback will be sent when an offer task is completed. A COMPLETED
callback can also be sent if a user completes an install task, which usually gives a $0 reward.
PENDING
: A PENDING
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.
RECONCILED
: A RECONCILED
callback will be sent when an offer 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 RECONCILED
callback can either occur after a PENDING
or after a COMPLETED
was sent.
Make sure to only reward users for offer_state=COMPLETED callbacks!
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 sent incorrectly and should be inverted again.
It is important to know that if stateful offer callbacks are enabled, the Reconciliations will no longer be negative.
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.
Ban callbacks
In case of fraud, our system bans users. To help you recognize it, we will send a ban callback. Please ask our account management to enable this callback option for you. Once enabled, you can configure it on the BitLabs Dashboard:
Here you can paste in the following URL while replacing publisher.com to match your endpoint. Keep in mind that as for all callbacks, a hash for validation will be attached at the end.
<https://publisher.com?uid=[%UID%]&ban_reason=[%BAN_REASON%]&ban_state=[%BAN_STATE%]>
Parameter | Type | Description |
---|---|---|
[%BAN_REASON%] | String | Returns the reason for a user ban. |
[%BAN_STATE%] | String | Returns ACTIVE or BANNED . |
This will ban the user from all games and offers and only games and offers. They will still be able to complete surveys and upload receipts.
Offer parameters
For offers we do provide additional parameters for additional information:
Parameter | Type | Description |
---|---|---|
[%OFFER_ID%] | Integer | ID of the completed task's offer. One offer can have many tasks. |
[%TASK_ID%] | Integer | ID of the completed task. |
[%OFFER_STATE%] | String | It can only be used when using Stateful Offer Callbacks. One of: NONE , COMPLETED , PENDING , RECONCILED .It is NONE if stateful offer conversion callbacks are disabled (this is the default). If they are enabled, however, it indicates the latest state of the offer conversion. |
[%OFFER_NAME%] | String | Localized name of the offer. Language is equivalent to what the user saw. |
[%TASK_NAME%] | String | Localized name of the task. Language is equivalent to what the user saw. |
[%OFFER:TITLE%] | String | Returns the anchor name of an offer. |
[%OFFER:DELAY%] | Integer | Returns the user reward delay in minutes. |
For a full list of all parameters click here.
How to test offer callbacks
We offer a callback tester on the dashboard to test your configured callback endpoints. Learn more about it here.
Testing with real offers
To test with a real offer you can visit the offer wall, select a game, and install it. This way you will either receive a COMPLETED
offer callback or a PENDING
one, depending on whether delayed crediting is enabled or not.
Updated 3 days ago