Offerwall PublishersHosted Offerwall

Playfull Hosted Offerwall

Step 1: Account Creation and Configuration

Create an account with us at https://www.playfull.com/offerwall-signup. After you’ve created an account, please let us know the email used to signup so that we can approve your account.

Step 2: Dashboard Access

Once your account is approved, you can visit your dashboard at https://www.playfull.com/offerwall/dashboard to manage your offerwall and enable offers to be displayed.

Step 3: Offerwall Link

Your offerwall link will be available on your dashboard. It will look like:

https://wall.playfull.com/offerwall?owid=<offerwall_id>

where owid will be prefilled with your offerwall ID.

We support the following parameters to the offerwall link:

ParametersTypeStatusDescription
uidstringrequiredUser ID in your application.
pf_sub1stringoptionalCustom parameter assigned by your application.
pf_sub2stringoptionalCustom parameter assigned by your application.
pf_sub3stringoptionalCustom parameter assigned by your application.

Step 4: Postback Configuration

Next, we will configure your postback for successful conversions. You will need to provide a postback URL for us to send a GET request to every time a conversion occurs. Your postback URL might look like this:

https://www.my_url.com?user_id={uid}&payout={payout}&mission_id={mission_id}&transaction_id={transaction_id}

By default, we support the following postback macros:

MacrosDescription
{uid}User ID in your application.
{owid}Offerwall ID.
{mission_id}Playfull system ID of the mission that triggered the conversion.
{mission_name}Playfull system name of the mission that triggered the conversion.
{quest_id}Playfull system ID of the quest that triggered the conversion.
{quest_name}Playfull system name of the quest that triggered the conversion.
{payout}Payout in publisher currency by the configuration of the offerwall.
{payout_usd}Payout in dollars.
{clickid}The unique click ID that started the mission.
{session_ip}User IP address that started the mission.
{transaction_id}Transaction ID of the conversion in the Playfull system. Use this identify a conversion in case of an issue or question.
{timestamp}Timestamp of the conversion.
{hash_key}Hash key used for verifying the postback.
{pf_sub1}Use this parameter to track custom parameters assigned by your application.
{pf_sub2}Use this parameter to track custom parameters assigned by your application.
{pf_sub3}Use this parameter to track custom parameters assigned by your application.

We also support the following legacy postback macros for those migrating from our old offerwall system:

MacrosDescription
{aff_sub}User ID in your application (same as {uid}).
{affiliate_id}Offerwall ID (same as {owid}).
{currency}3 digit currency abbreviated (e.g. USD).
{datetime}Timestamp of the conversion (same as {timestamp}).
{goal_id}Playfull system ID of the goal that triggered the conversion (same as {mission_id}).
{goal_name}Playfull system name of the goal that triggered the conversion (same as {mission_name}).
{offer_id}Playfull system ID of the offer that triggered the conversion (same as {mission_id}).
{offer_name}Playfull system name of the offer that triggered the conversion (same as {mission_name}).

IP Whitelisting

The postback will be sent from one of a set of static IP addresses that should be whitelisted on your server. We will provide you with the list of IP addresses during onboarding.

Postback Hashing

For additional security, we will provide a postback hash key for you to verify the validity of the postback. Below are instructions on how to verify the postback hash key:

Instructions for Calculating the Hash Key

  1. Include all provided parameters and their values in the hash key calculation, except for the hash_key itself.
  2. Order these parameter-value pairs alphabetically by parameter name (key).
  3. Concatenate all pairs using an equals sign (=) between each key and value, and an ampersand (&) to separate each pair.
  4. Append this string with another ampersand (&) followed by your API key.
  5. Hash the entire resulting string using the SHA-1 algorithm. The resulting hash_key should be the one included in our postback.

Hash Key Calculation Example

  1. Include all provided parameters and their values in the hash key calculation, except for the hash_key itself.
uid = user1234
payout = 1234
transaction_id = 102b20c6fe823536281e7515add26c
timestamp = 1615057106
  1. Order these parameter-value pairs alphabetically by parameter name (key).
payout = 1234
timestamp = 1615057106
transaction_id = 102b20c6fe823536281e7515add26c
uid = user1234
  1. Concatenate all pairs using an equals sign (=) between each key and value, and an ampersand (&) to separate each pair.
payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234
  1. Append this string with another ampersand (&) followed by your API key.

API Key Example: 0f52fbb3dca243538ce80e33fcf4ad61

payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234&0f52fbb3dca243538ce80e33fcf4ad61
  1. Hash the entire resulting string using the SHA-1 algorithm.

0e8bd720d5761d0441dc7fa74700019216e8cd0e

  1. The resulting hash_key will be included as a separate parameter in the postback request.
GET https://www.my_url.com?payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234&hash_key=0e8bd720d5761d0441dc7fa74700019216e8cd0e