Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
For Web Surveywalls, you have to manually manage your users' currencies on your own servers.
You can configure a conversion callback URL in our publisher dashboard. To do so, navigate to Placements / Apps, edit your placement and set the Callback URL to your server's postback URL:
If this is the callback URL you set for your offerwall placement:
A typical conversion callback sent by our server will look like this:
This assumes you set external_identifier to username in the original Offerwall URL for that user, the currency conversion rate in your placement was 1000 per $1 and the user completed an offer with a $0.36 payout.
Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.
You can automatically process Reversals made to your account and placements by enabling Reversal Callbacks.
Simply navigate to Placements / Apps, edit your placement and check the box Enable Reversal Callbacks.
Once enabled we will send reversal callbacks directly to the callback URL you set up for your placements.
The unique transaction ID we send for each conversion will carry an "r-" prepended to the ID for each reversal callback.
For chargebacks the original transaction ID of a conversion is prepended with "r-".
Example Transaction IDs:
381f99333613b41392b15183d69a7240308e8461 -> Regular Callback
r-381f99333613b41392b15183d69a7240308e8461 -> Reversal Callback
Below is a list of all relevant parameters to use in order to distinguish reversal callbacks from regular callbacks.
Note: If the parsing capabilities of your callback endpoint are limited, each of the parameters below is also available in a sanitized version. By suffixing any of the parameters below with _sanitized
(for example {external_identifier_sanitized}
), any character that is not in 0-9 a-z A-Z - _
will be removed. Whitespaces will be replaced by underscores.
Important: To ensure each conversion is granted only once to your users, always use {transaction_id}. Occasional callback resends may occur for various reasons. Utilizing {transaction_id} prevents granting conversions more than once.
Variable | Type | Description |
---|---|---|
Variable | Type | Description |
---|---|---|
{transaction_id}
string
Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "r-".
{is_chargeback}
int
Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason}
string
Reason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}
string
Date of chargeback creation. Only available if is_chargeback set to 1.
{transaction_id}
string
Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "r-".
{payout_usd}
float
The actual conversion payout in USD. If chargeback value is negative.
{currency_amount}
float
The amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.
{external_identifier}
string
The user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link.
{user_id}
integer
Our internal ID for this offerwall user
{placement_identifier}
string
The placement_identifier for which the conversion occured
{survey_id}
int
Survey ID of the completed survey
{loi}
int
Length of interivew - the time it took the user to complete the survey
{adslot_id}
int
The ID of the adslot for which the conversion occured
{sub_id}
string
The ID of the Placement for which the conversion occured [PL-1...n]
{ip}
string
Converting device's IP address if known, 0.0.0.0 otherwise
{offer_id}
int
Offer ID of the converting offer
{offer_name}
string
Name / title of the converting offer
{device_uuid}
string
ayeT-Studios internal device identificator
{device_make}
string
Device manufacturer
{device_model}
string
Device model
{advertising_id}
string
Device advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id}
string
Device sha1 hashed android id if known, otherwise empty
{sha1_imei}
string
Device sha1 hashed IMEI, if known, otherwise empty
{is_chargeback}
int
Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason}
string
Reason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}
string
Date of chargeback creation. Only available if is_chargeback set to 1.
{task_name}
string
Only available for CPE campaigns, shows individual task name for that conversion.
{currency_identifier}
string
Shows virtual currency name as set in adslot.
{currency_conversion_rate}
decimal
Shows currency conversion rate used to calculate user currency for the given conversion.
{custom_1}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_2}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_3}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_4}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_5}
string
Custom parameter to pass variables to the conversion callbacks.
If you want to restrict postbacks to our callback server IPs, please whitelist the following IPs and check back regularly for possible changes:
Last IP List Update: 2017-04-07
Our server will always add a custom header, X-Ayetstudios-Security-Hash, containing a SHA256 HMAC hash of the request parameters and your publisher api key. Your API key can be found in your dashboard at ayetstudios.com under settings.
To verify the hash, perform the following steps:
Get all request parameters
Order the request parameters alphabetically
Build and compare the HMAC hash using the ordered request parameter string and your API key
PHP Example:
Assuming the below is the callback we sent to you:
1) Get all request parameters
Strip away your domain and order the request parameters alphabetically.
In this example the parameters are already ordered alphabetically.
2) Order the request parameters alphabetically
This is the ordered request parameter string for the HMAC hash calculation:
Your API Key from the ayeT dashboard:
3) Build and compare the HMAC hash using the ordered request parameter string and your API key
Hashing the ordered request parameter string with your Secret Key (API Key) with SHA256, you will get the following HASH Key:
Compare the HASH Key you calculated to the X-Ayetstudios-Security-Hash our server will always add as custom header for each conversion.
For Web Offerwalls and SDKs, you have to manually manage your users' currencies on your own servers.
You can configure a conversion callback URL in our publisher dashboard. To do so, navigate to Placements / Apps, edit your placement and set the Callback URL to your server's postback URL:
If this is the callback URL you set for your offerwall placement:
A typical conversion callback sent by our server will look like this:
This assumes you set external_identifier to username in the original Offerwall URL for that user, the currency conversion rate in your placement was 1000 per $1 and the user completed an offer with a $0.36 payout.
Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.
You can automatically process Reversals made to your account and placements by enabling Reversal Callbacks.
Simply navigate to Placements / Apps, edit your placement and check the box Enable Reversal Callbacks.
Once enabled we will send reversal callbacks directly to the callback URL you set up for your placements.
The unique transaction ID we send for each conversion will carry an "r-" prepended to the ID for each reversal callback.
For chargebacks the original transaction ID of a conversion is prepended with "r-".
Example Transaction IDs:
381f99333613b41392b15183d69a7240308e8461 -> Regular Callback
r-381f99333613b41392b15183d69a7240308e8461 -> Reversal Callback
Below is a list of all relevant parameters to use in order to distinguish reversal callbacks from regular callbacks.
Note: If the parsing capabilities of your callback endpoint are limited, each of the parameters below is also available in a sanitized version. By suffixing any of the parameters below with _sanitized
(for example {external_identifier_sanitized}
), any character that is not in 0-9 a-z A-Z - _
will be removed. Whitespaces will be replaced by underscores.
Important: To ensure each conversion is granted only once to your users, always use {transaction_id}. Occasional callback resends may occur for various reasons. Utilizing {transaction_id} prevents granting conversions more than once.
Variable | Type | Description |
---|---|---|
Variable | Type | Description |
---|---|---|
{transaction_id}
string
Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "r-".
{is_chargeback}
int
Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason}
string
Reason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}
string
Date of chargeback creation. Only available if is_chargeback set to 1.
{transaction_id}
string
Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "r-".
{payout_usd}
float
The actual conversion payout in USD. If chargeback value is negative.
{currency_amount}
float
The amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.
{external_identifier}
string
The user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link.
{user_id}
integer
Our internal ID for this offerwall user
{placement_identifier}
string
The placement_identifier for which the conversion occured
{adslot_id}
int
The ID of the adslot for which the conversion occured
{sub_id}
string
The ID of the Placement for which the conversion occured [PL-1...n]
{ip}
string
Converting device's IP address if known, 0.0.0.0 otherwise
{offer_id}
int
Offer ID of the converting offer
{offer_name}
string
Name / title of the converting offer
{device_uuid}
string
ayeT-Studios internal device identificator
{device_make}
string
Device manufacturer
{device_model}
string
Device model
{advertising_id}
string
Device advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id}
string
Device sha1 hashed android id if known, otherwise empty
{sha1_imei}
string
Device sha1 hashed IMEI, if known, otherwise empty
{is_chargeback}
int
Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason}
string
Reason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}
string
Date of chargeback creation. Only available if is_chargeback set to 1.
{task_name}
string
Only available for CPE campaigns, shows individual task name for that conversion.
{task_uuid}
string
Only available for CPE campaigns, shows unique id for the task and campaign
{currency_identifier}
string
Shows virtual currency name as set in adslot.
{currency_conversion_rate}
decimal
Shows currency conversion rate used to calculate user currency for the given conversion.
{custom_1}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_2}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_3}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_4}
string
Custom parameter to pass variables to the conversion callbacks.
{custom_5}
string
Custom parameter to pass variables to the conversion callbacks.
Sandbox Identifiers can be used to test the user and callback flow from initial entering the offerwall until successfully processing a callback.
A Sandbox Identifier is basically an external identifier (a User ID) that you define. Appending or passing this identifier to the offerwall will trigger the offerwall to run in sandbox mode.
Sandbox Identifiers will help you to test the offerwall across multiple devices and in different GEOs for certain predefined "Identifiers".
Using Sandbox Identifiers for testing helps you to avoid triggering any of the ayeT-Studios Fraud Prevention Checks that would block your device from accessing the offerwall.
Click on Edit Placement in the ayeT-Studios Publisher Dashboard and enter a identifier of your choice for the Sandbox Identifiers feature.
In the example below, the sandbox identifier is set to testuser123.
You can enter several identifiers if needed to make it easer to test with different devices and in different GEOs across your team.
Now that the sandbox identifier is set, you have to pass the sandbox identifier to your Offerwall AdSlot that you want to test.
Note: If you passed the sandbox identifier correctly, your offerwall will show three test offers (see screenshot below).
In the example below, the testuser123 was passed to a Web Offerwall AdSlot. The offerwall now shows three test offers.
Clicking on one of the test offers will show a detail modal with more instructions.
Clicking on the Earn Button will trigger a test callback.
Once you clicked on an offer, you can see the click ID and additional conversion details. In this case, a test callback with 200 in virtual currency and $0.2 in USD payout was triggered.
You can also see the transaction ID and a describtion where to find more details for the callback in the ayeT-Studios dashboard.
If you navigate to Reports / Conversions in the ayeT-Studios dashboard, you are able to find the test postback with your sandbox identifier that you just triggered.
Note: Sandbox offer conversions will generate regular callbacks with fake payouts and user currency.
&is_sandbox=1
is appended to every callback url to easily allow discarding test conversions.
If you click on Details for the test callback, you are able to see all details for the test callback.
The Callback Details show a list of available macros and information as well as the callback URL that was triggered, including the is_sandbox=1 macro to identifiy the callback as a test.
If your callback URL is missing information, please navigate to placements and edit your callback URL by adding additional callback macros.
To see a list of available callback macros, please go to the following section:
This checklist is supposed to help you to take care of all important and relevant settings before going live with your Offerwall.
With the Callback Tester you can verify that you receive back all relevant information you need in order to pay your users and if the added macros are populated correctly.
The Callback Tester was built to help you to verify that you:
added all the macros to your Callback URL that you need to receive back
that those macros are populated by ayeT-Studios' servers as expected
You can check all availabe macros that can be added to your callback URL here:
Click on Edit Placement in order to open the detail modal. Here you can change your postback URL and i.e. add additional macros.
In addition you can send a test postback to your servers.
The example shows that the macros
{external_identifier}
{payout_usd}
{currency_amount}
{placement_identifer}
were added to your callback URL.
When you click Send Test Postback, you will a list of fields and the information with which we will populate the macros you added to your callback URL.
For a few of those fields you can input values yourself. A few other fields are locked and only the information displayed can be passed.
Clicking on Send Postback will send the test postback.
Clicking on Check Postback Status afterwards, will lead you to Reports / Conversions, where the callback that just got sent will be displayed.
If you click on Details, you will be able to see the entire payload we sent and your Callback URL with populated macros.
In this specific example the ayeT-Studios servers populated only the macros that you previously added to your callback URL:
{external_identifier} = my-test-user-567
{payout_usd} = 0
{currency_amount} = 320
{placement_identifer} = deb88ed8abe52ab1f67a97068d88d9db
To handle video conversions with S2S Callbacks, first make sure your callback URL is setup correctly in your publisher placement. To do so, navigate to Placements / Apps, edit your placement and set the Callback Url to your server's postback url:
Also make sure that "Send S2S Callbacks" for video views is enabled for your Rewarded Video AdSlot in "AdSlot Details" > "Overview".
If this is the callback url you set for your placement:
A typical conversion callback sent by our server will look like this:
This assumes you set externalIdentifier to username when calling AyetVideoSdk.init(...)
, the currency amount per view was set to 10 in your rewarded video adslot #16 and the delivered video had an eCPM of $7.00.
Hint: If you send callbacks from multiple different adslots (e.g. rewarded_video and offerwall) make sure to pass and validate {adslot_id}
in your callback URL to determine if the conversion was a normal offer or a rewarded video.
Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.
Note: If the parsing capabilities of your callback endpoint are limited, each of the parameters below is also available in a sanitized version. By suffixing any of the parameters below with _sanitized
(for example {external_identifier_sanitized}
), any character that is not in 0-9 a-z A-Z - _
will be removed. Whitespaces will be replaced by underscores.
Important: To ensure each conversion is granted only once to your users, always use {transaction_id}. Occasional callback resends may occur for various reasons. Utilizing {transaction_id} prevents granting conversions more than once.
Variable | Type | Description |
---|
{transaction_id} | string | Unique transaction id - use for duplicate checks. |
{payout_usd} | float | The actual conversion payout in USD. |
{currency_amount} | float | The amount of currency the user earned (taken from your offerwall currency configuration). |
{external_identifier} | string | The user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link |
{user_id} | integer | Our internal id for this offerwall user |
{placement_identifier} | string | The placement_identifier for which the conversion occured |
{adslot_id} | int | The ID of the adslot for which the conversion occured |
{sub_id} | string | The ID of the Placement for which the conversion occured [PL-1...n] |
{ip} | string | Converting device's IP address if known, 0.0.0.0 otherwise |
{offer_id} | int | Offer ID of the converting offer |
{offer_name} | string | Name / title of the converting offer |
{device_uuid} | string | ayeT-Studios internal device identificator |
{device_make} | string | Device manufacturer |
{device_model} | string | Device model |
{advertising_id} | string | Device advertising id (GAID/IDFA) if known, otherwise empty |
{sha1_android_id} | string | Device sha1 hashed android id if known, otherwise empty |
{sha1_imei} | string | Device sha1 hashed imei if known, otherwise empty |
{currency_identifier} | string | Shows virtual currency name as set in adslot. |
{currency_conversion_rate} | decimal | Shows currency conversion rate used to calculate user currency for the given conversion. |
{custom_1} | string | Custom parameter to pass variables to the conversion callbacks |
{custom_2} | string | Custom parameter to pass variables to the conversion callbacks |
{custom_3} | string | Custom parameter to pass variables to the conversion callbacks |
{custom_4} | string | Custom parameter to pass variables to the conversion callbacks |
{custom_5} | string | Custom parameter to pass variables to the conversion callbacks |
This checklist is supposed to help you to take care of all important and relevant settings before going live with your rewarded video placement.