Publisher Partner Integration

Step 1: Account Creation and Configuration

First, you can create an account with us using this sign up form (opens in a new tab). Also please send us the following information so we can configure your account:

Currency name (e.g. "coins")
Currency exchange rate (e.g. $1 = 1,000 coins)
Currency icon URL (25x25 or greater resolution recommended)
Postback URL (when you have it, see "Step 3" below for details)

Once your account is created and approved, you will be able to log in at partners.playfull.com (opens in a new tab) to view your dashboard, including your offers and performance reports.

Then we will approve your account for you. You should then receive an email with the subject “Your Playfull, LLC account has been activated.” with login instructions

Step 2: Offerwall Integration

Once your account is set up, we will provide you with a direct link to our offerwall where you will redirect your users, supplying the offerwall ID and the user's ID on your system. The link should look like this:

https://wall.playfull.com/offers?owid=1234&uid={user_id}

We will provide you with your offerwall ID and your system will provide the user ID for each user.

Optionally, you can also integrate using an iframe. Below is an example of a full screen iframe using the same link:

<iframe src="https://wall.playfull.com/offers?owid=1234&uid={user_id}" style="position:fixed; top:0px; left:0px; bottom:0px; right:0px; width:100%; height:100%; border:none; margin:0; padding:0; overflow:hidden; z-index:999999;">Your browser doesn't support iframes</iframe>

You can optionally supply additional information if you would like to track it, including:

Parameters	Type	Status	Description
owid	string	required	This parameter specifies the unique identifier for the offerwall that should be displayed to the user. This URL parameter, or more likely an API parameter depending on the integration method, acts as an identifier. It tells the system which specific offerwall the user should see. Offerwalls are promotional sections within apps or websites that present users with various third-party offers in exchange for in-app rewards or virtual currency. By including this parameter, you ensure the user gets directed to the correct offerwall campaign you have set up.
uid	string	required	This parameter represents the internal User ID used in your application, which identifies the user for the purpose of attributing virtual currency to their account using the request. It is important to note that this User ID must remain constant in order to prevent users from completing an offer more than once.
clickid	string	optional	Use this parameter to track unique click IDs generated by your application. This option is typically used when you want to pass information back to your system for conversion tracking. This unique click ID will then be recognized by your system and matched with the original visit.
country	string	optional	Use this URL parameter to specify the user's country location using a two-letter ISO country code. This follows the ISO 3166-1 alpha-2 standard, which assigns unique two-letter codes to represent countries and territories. Examples include "US" for the United States, "FR" for France, or "JP" for Japan.
pf_c	string	optional	This URL parameter is used to identify and track a specific marketing campaign name.
pf_c_id	string	optional	This URL parameter is used to identify and track a specific marketing campaign ID.
pf_adset	string	optional	This URL parameter allows you to specify the name assigned to a particular adset within your campaign. An adset acts as an intermediate level between your overall campaign goal and the individual ads users see.
pf_adset_id	string	optional	This URL parameter allows you to specify the ID assigned to a particular adset within your campaign.
pf_ad	string	optional	This URL parameter allows you to specify the name assigned to a particular ad within your campaign.
pf_ad_id	string	optional	This URL parameter allows you to specify the ID assigned to a particular ad within your campaign.
pf_site	string	optional	This URL parameter allows you to specify the name assigned to a particular site within your campaign.
pf_site_id	string	optional	This URL parameter allows you to specify the ID assigned to a particular site within your campaign.
pf_ip	string	optional	This optional parameter, pf_ip, allows you to specify the user's device IP address, if available.
pf_sub3	string	optional	Use this parameter to track custom parameters assigned by your application. This option is typically used to pass information for statistics or to pass it back to your application for conversion tracking purposes.
pf_sub4	string	optional	Use this parameter to track custom parameters assigned by your application. This option is typically used to pass information for statistics or to pass it back to your application for conversion tracking purposes.
pf_ad_type	string	optional	Use the following naming convention: text: an ad unit containing only text, for example a search result banner: a basic format that appears at the top or bottom of the device screen interstitial: a full-page ad that appears during breaks in the current experience video: a standard video, that is non-rewarded playable: an ad unit containing an interactive preview of the app experience sponsored_content: a link included in a piece of sponsored content, like an advertorial article audio: an audio ad
source	string	optional	This optional parameter allows you to specify the user's source.

Step 3: 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}&goal_id={goal_id}&transaction_id={transaction_id}

By default, we support the following parameters:

Parameters	Status	Description
uid	required	User ID in your application
payout	required	Payout in publisher currency by the configuration of the offerwall
goal_id	required	Playfull system ID of the goal that triggered the conversion
payout_usd	optional	Payout in dollars
transaction_id	recommended	Transaction ID of the conversion in the Playfull system, use this identify a conversion in case of an issue or question
offer_id	optional	Use this parameter if you want to know which offer was converted by the user
hash_key	Default parameter when secure postback is enabled	Providing hash key that generated during the postback by using publisher private key
timestamp	Default parameter when secure postback is enabled	Timestamp of the conversion
clickid	optional	Use this parameter to track unique click IDs generated by your application.
owid	optional	Offerwall ID
pf_sub3	optional	Use this parameter to track custom parameters assigned by your application.
pf_sub4	optional	Use this parameter to track custom parameters assigned by your application.

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 the API key provided by us.
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 the API key provided by Playfull.

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 should be included as a separate parameter in the update request.

GET https://www.my_url.com?payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234&hash_key=0e8bd720d5761d0441dc7fa74700019216e8cd0e

Closing Thoughts

That's it! If you encounter any issues during the integration or have any questions, please don't hesitate to reach out to your account manager or our support team at support@playfull.com.

Thanks for choosing Playfull! We look forward to working with you.

Advertiser Integration Concepts