Publisher White-label Integration

Step 1: Account Creation and Configuration

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

Step 2: Dashboard Access

Once your account is set up, 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:

Parameters	Type	Status	Description
uid	string	required	User ID in your application.
pf_sub1	string	optional	Custom parameter assigned by your application.
pf_sub2	string	optional	Custom parameter assigned by your application.
pf_sub3	string	optional	Custom 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:

Macros	Description
uid	User ID in your application
owid	Offerwall ID
mission_id	Playfull system ID of the mission that triggered the conversion
quest_id	Playfull system ID 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.
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:

Macros	Description
goal_id	Playfull system ID of the goal that triggered the conversion (same as `mission_id`)
offer_id	Playfull system ID of the offer that triggered the conversion (same as `mission_id`)

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

Include all provided parameters and their values in the hash key calculation, except for the hash_key itself.
Order these parameter-value pairs alphabetically by parameter name (key).
Concatenate all pairs using an equals sign (=) between each key and value, and an ampersand (&) to separate each pair.
Append this string with another ampersand (&) followed by your API key.
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

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

Order these parameter-value pairs alphabetically by parameter name (key).

payout = 1234
timestamp = 1615057106
transaction_id = 102b20c6fe823536281e7515add26c
uid = user1234

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

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

Hash the entire resulting string using the SHA-1 algorithm.

0e8bd720d5761d0441dc7fa74700019216e8cd0e

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

Integration API Integration