Menu

Publisher Integration Guide

Setup

Integration Checklist

Basic technical integration takes place in five steps:

  • Create your account in the Publisher Dashboard and await a notification email that your account has been approved.
  • Log in to the Publisher Dashboard and submit your billing information.
  • Select Add Application to add the details of your site and get your Application ID and Application Key.
  • Integrate with Peanut Labs using one or multiple deployments.
  • Configure your callback script to receive notifications from Peanut Labs.

All of the above can be done in an afternoon or less. If you have questions please don't hesitate to contact us:
publisher.integration@peanutlabs.com

Create your Peanut Labs account and add a new application

If you haven't already, please submit an application to become a Peanut Labs publisher:
http://www.peanutlabs.com/publisher

An Account Manager will review your information and notify you that your account has been activated, at which time you can log in and get started!

When you are logged into the Publisher Dashboard, it should look something like this:

Click Complete Billing Information to set up your preferred payment method. Then click Add Application:

 

In the My Apps section, click Add Application to add an app to our system:

 

On the Add Application screen you have several values you need to configure:

Before you can hit the Save button, you'll need to enter an Application Name, your processing script, name your virtual currency, set your virtual-currency-to-USD exchange rate, and set an optional Screenout Reward (0 must be entered if you do not want to give users a small reward for disqualifying from a survey).

  • Application Name

    This is the name of your application in our system. It is for internal use only, users will not see this name.

  • Processing Script

    This is the URL where we will send automatic notifications to each time one of your users is rewarded.

    You must include http or https in your processing script URL for it to work properly. We highly recommend you to use https.
  • Virtual Currency Name

    The display name for your virtual currency. This name will be listed everywhere in our system where we refer to the value of a transaction.

  • Exchange Rate

    How many points is a dollar worth? Currency rewards to your users will always be an integer (positive for a successful transaction, negative if a transaction must be reversed). However, your net revenue is a floating point value. This means a higher exchange rate will reduce the rounding error when we convert your net revenue to an integer for the currency reward. Confused? It's a common question; the virtual currency rewarded to the user follows this formula:

     

    Currency Reward = Your Net Revenue * Your Currency Exchange Rate

     

    However if you would like to give non-integer currency rewards to your users, please email us and we will support a floating point currency reward amount for you.

    We round currency rewards based on standard rounding rules for integers. If a payout is equivalent to 1.5 virtual currency points, we will reward 2 points. If a payout is 1.49 virtual currency points, we will reward 1 point.
  • Integration Colors

    Here you can customize the color scheme of your integration. If you do not choose to customize the the default scheme will be used.

  • Screenout Reward

    If a user is screened out, you can thank them with some virtual currency and encourage the user to try again. Peanut Labs does NOT pay for this reward, but many publishers choose to set a reward to help foster a positive user experience. Learn more about Screenout Rewards. If you prefer not to have one, set the Screenout Reward to 0.

Integrating our Products

Our products can be integrated via HTML, iOS or Android.

In the following sections, we will walk you through the process by which an integration URL is generated, after which we will dive into the syntax for HTML, iOS and Android which you can then use to integrate our products into your application.

Get Application ID and Key

Once you've created your new application you will need to take note of your Peanut Labs Application ID and Peanut Labs Application Key in the dashboard. These two values are used in the remaining steps.

You can find it on this screen:

Generating the Peanut Labs userId

Sample userId: 11701396-600-cbc2104c7a consists of three parts:

  • endUserId

    (ex. 11701396) the user’s id within your system (alphanumeric)

  • Peanut Labs ApplicationId

    (ex. 600) generated when you add an application to your account. Listed as ID in Manage Apps

  • userGo

    (ex. cbc2104c7a) this is a hash generated by the following formula:

    userGo = substr( md5( endUserId . applicationId . applicationKey ), 0, 10 );

Take the same endUserId and Peanut Labs applicationId as above but also add your Peanut Labs applicationKey.

You will take the first 10 characters of the MD5 hash of endUserId, applicationId and applicationKey concatenated.

Make sure the md5 hash returned is all lower-case.

Generating the userGo is typically the most difficult part of hosting the Reward Center. If you're having trouble: publisher.integration@peanutlabs.com and cc your Account Manager (the person who contacted you to activate your account).

Here is a step by step example that will walk you through the process.

There are three components needed to generate the userGo:

  • endUserId

    This is the user's Id generated in your system. For this example, let's say endUserId = user1

  • ApplicationId

    This is found in the "my Apps" section in the dashboard. For New Awesome Company, the ApplicationId = 0000

  • ApplicationKey

    Found next to the Application Id. For New Awesome Company, the ApplicationKey = d755913ed731c335656a9578be648aa0

 

The userGo hash will be generated by the following formula:

userGo = substr( md5( endUserId.applicationId.applicationKey), 0, 10)

This means that you will take the first 10 characters of the md5 encryption of endUserId applicationId applicationKey concatenated.

 

In this example, the formula will look like this:

userGo = substr(md5(user10000d755913ed731c335656a9578be648aa0), 0, 10)

md5(user10000d755913ed731c335656a9578be648aa0) = aa3ad2272592b73a06cbaa35cc6fb155

 

Then, we take the first 10 characters:

aa3ad22725 (This is your UserGo - make sure it is lower-case)

 

The resulting UserID then is:

user1-0000-aa3ad22725

Deploy

Reward Center (iFrame)

Parameters to Maximize Revenue

You can increase your revenue potential by up to 30% by providing these optional variables. These help us offer better suited reward opportunities to users. Note, that however it is better to omit these values if you don’t have accurate information, as inaccurate information will lead to negative results.

  • dob

    User’s complete date of birth in the MM-DD-YYYY format

  • sex

    1 for male, 2 for female

Custom URL Parameters

Before using a custom parameter please contact your account manager. There are some specific behaviors for this system that may not match your expectations.

You can add your own custom parameters to the Reward Center SRC. Define your parameter name in var_key_X and parameter value in var_key_X (where X can be 1, 2,3). You may chain 3 custom parameters.

Example Custom Parameters:

...&var_key_1=abc&var_val_1=xyz&...

Would give you the following in the post back:

..&abc=xyz&..

 

Multiple Custom Parameters:

...&var_key_1=firstName&var_val_1=bob&var_key_2=lastName&var_val_2=smith…

Would give you the following in the post back:

&firstname=bob&lastname=smith

Desktop

The DOB and sex parameters are optional, but strongly encouraged. They help us with offer targeting for first time users, and enable us to show users more videos and high quality offers.

The width and height Reward Center attributes determine the size of our Reward Center in your app. Our standard layout is flexible, but will break down if it is much narrower than 650px.

$userId is a placeholder for a Peanut Labs encoded User ID.

Call the following URL inside an iFrame (URL parameters are case sensitive):

<iframe src="https://www.peanutlabs.com/userGreeting.php?userId=$userId&dob=MM-DD-YYYY&sex=X" width="880" height="2500" frameborder="0" scrolling="no" frameborder="0" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"> </iframe>

Due to the varying screen sizes and practices across mobile platforms and websites, the Reward Center works best as a standalone tab on mobile instead of inside an iFrame. However, you don't need to change your integration for mobile users. Whenever an embedded iFrame loads the Reward Center on a mobile device, the user is automatically indicated to click a button that re-opens the same Reward Center URL in a separate tab. This renders the Reward Center with the most usable mobile experience, utilizing all the screen space. If your website is a mobile-only site with a mobile-only audience that usually loads in a mobile web browser, you can choose to directly open the Reward Center URL in a new tab instead of inside an iFrame.

iOS

You can simply use our Reward Center's URL inside a UIWebView (https://www.peanutlabs.com/userGreeting.php?userId=Peanut-Labs-User-Id) for an iOS device. Use your generated Peanut Labs User Id for the userId parameter.

We suggest giving users basic navigation controls over your UIWebView like back and forward buttons, as well as a button to go back to the Reward Center for when they have left it to take a survey or an offer (labelled “Done” in our SDK). These controls are automatically included when using the SDK. (If you prefer to just use our iOS SDK, please find instructions here). However, not providing your user with them can result in a poor user experience.

Android

You can simply use our Reward Center's URL inside a WebView (https://www.peanutlabs.com/userGreeting.php?userId=Peanut-Labs-User-Id). Use your generated Peanut Labs User Id for the userId parameter.

We suggest giving users basic navigation controls over your WebView like back and forward buttons, as well as a button to go back to the Reward Center for when they have left it to take a survey or an offer (labelled “Done” in our SDK). These controls are automatically included when using the SDK. (If you prefer to just use our iOS SDK, please find instructions here). However, not providing your user with them can result in a poor user experience.

Mobile SDKs

iOS

Our SDK allows you to launch the Peanut Labs Reward Center as an overlay on top of your application from anywhere in the application. We recommend using our SDK because it comes with the basic navigation controls a user would need to go between, surveys, offers and our Reward Center.

A Peanut Labs iOS SDK is provided via Github containing Objective-C code files. These files need to be added to your project, ideally inside a group. We support all iOS devices except iPhones below iPhone 4.

The SDK can be downloaded here. Once the SDK has been added to your project, implement the following technical steps.

The first version of Peanut Labs SDK assumes ARC support and would not work if you don’t have ARC enabled. This will be supported in a future version soon.

 

  1. Generate the Peanut Labs User ID on your server side and pass that on to the client side app.

  2. In the view controller which will have the action for the Reward Center button, place the following import statement:

    #import "PeanutLabsManager.h"

  3. In the same view controller, use the following code to initialize and open the rewards center:

    PeanutLabsManager *plManager = [PeanutLabsManager getInstance];
    plManager.delegate = self; #optional
    [plManager setUserId:@"USER_ID_HERE"];
    [plManager openRewardsCenter];

  4. Your view controller needs to implement the PeanutLabsManagerDelegate delegate in order to perform actions on the opening and closing of the rewards center.

    - (void)peanutLabsManager:(PeanutLabsManager *)peanutlabsManager
    rewardsCenterDidOpen:(NSString *)userId {
      //Do things like stop sound
      NSLog(@"Rewards center opened");
    }

    - (void)peanutLabsManager:(PeanutLabsManager *)peanutlabsManager
    rewardsCenterDidClose:(NSString *)userId {
      //Resume sound
      NSLog(@"Back from the Rewards center");
    }

We recommend generating userId on the server side and passing it to the client side since placing the Peanut Labs Application Key on the app itself can be prone to exposure. However, if you must generate the userId client side, the SDK offers a method to make it easier to do so but if you use that, you must use the Transaction Key in addition to Application Key to validate all reward callbacks.

[plManager setAppId:1111];
[plManager setAppKey:@"APP_KEY_HERE"];
[plManager setEndUserId:@"END_USER_ID_HERE"];

For iOS 9: Apple has introduced a new feature in iOS 9 called App Transport Security. This introduces a default setting requiring all connections between your App and Web services to be made using at least TLS 1.2 (Transport Layer Security). In order to ensure the Peanut Labs iOS SDK functions correctly, please disable ATS.
You can do so by adding the code from 'examples' to your Apps Info.plist.

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Android

Our SDK allows you to launch our Reward Center as an overlay on top of your application, from anywhere in the application. We recommend using our SDK because it comes with the navigation controls a user would need to go between, surveys, offers and our Reward Center.

A Peanut Labs Android SDK is provided via Github containing the source code in android library project. The library needs to be added to your project. We support android 4.1+ (Jelly Bean and above). The Android SDK can be downloaded here. After adding the library reference to your project, implement the following technical steps.

  1. Generate the Peanut Labs User ID on your server side and pass that on to the client side app.

  2. In the Activity which will have the action for the Reward Center button, place the following import statement:

    import com.peanutlabs.plsdk.*;

  3. In the same Activity, use the following code to initialize and open the rewards center:

    PeanutLabsManager plManager = PeanutLabsManager.getInstance();
    plManager.setRewardsCenterEventsHandler(this); #optional
    plManager.setUserId("USER_ID_HERE");
    plManager.openRewardsCenter(this);

  4. Your Activity needs to implement the IRewardsCenterEventsHandler interface in order to perform actions on the opening and closing of the rewards center.

    @Override
    public void onRewardsCenterOpened() {
      //Do things like stop sound
      Log.d("PLSDK", "Rewards center opened");
    }

    @Override
    public void onRewardsCenterClosed() {
      //Resume sound
      Log.d("PLSDK", "Back from the Rewards center");
    }

  5. Declare the Reward Center Activity in your AndroidManifest.xml under the application section.

    <activity android:name="com.peanutlabs.plsdk.RewardsCenterActivity"
      android:configChanges="keyboard|keyboardHidden|screenSize|orientation">
    </activity>

  6. Provide internet permission in AndroidManifest.xml if it’s not already been defined.

    <uses-permission android:name="android.permission.INTERNET" />

We recommend generating userId on the server side and passing it to the client side since placing the Peanut Labs Application Key on the app itself can be prone to exposure. However, if you must generate the userId client side, the SDK offers a method to make it easier to do so but if you use that, you must use the Transaction Key in addition to Application Key to validate all reward callbacks.

plManager.setApplicationId(1111);
plManager.setApplicationKey("APP_KEY_HERE");
plManager.setEndUserId(“END_USER_ID_HERE”);

Unity

Our Plugin allows you to launch the Peanut Labs Reward Center as an overlay on top of you application from anywhere within the application. We recommend using our Plugin because it comes with the basic navigation controls a user would need to go between, surveys, offers and our Reward Center. A Peanut Labs Unity iOS and Android Plugin is provided via Github containing the publisher_unity_sdk.unitypackage file. This package needs to be imported into your project.

We support all Android devices 4.1+ (Jelly Bean and above) and all iOS devices except those below iPhone 4.

  1. Generate the Peanut Labs User ID on your server side and pass that on to the client side app.

  2. Import publisher_unity_sdk.unitypackage into your project:

    From Unity go to Assets menu → Import package → Custom package → choose our unity package.

  3. Once you imported our package make sure our plugin files are in your project structure:

    Project_path/Plugins/PeanutLabsManager.cs
    Project_path/Plugins/iOS/PeanutLabsManagerWrapper
    Project_path/Plugins/SDK/* IF Android
    Project_path/Plugins/PeanutLabsManager.cs
    Project_path/Plugins/Android/AndroidManifest
    Project_path/Plugins/Android/plsdk Project_path/Plugins/res/*

  4. Open Rewards Center with User Id:

    PeanutLabsManager.openRewardsCenterWithUserId(“USER_ID_HERE”);

Our Plugin will not show you the results you expect unless you build it and run it in an iOS or Android environment simulator or device. Simply open the ExamplePublisher.cs file and see example calls of opening our Reward Center package within our Unity package.

Marmalade

Our SDK allows you to integrate our Reward Center within your Marmalade application for iOS. This is the first Beta release so if you see any issues, please use the Github issues to report them. The SDK and further instructions can be found here.

  1. Clone the following github repository.

  2. Include the subproject "peanutlabs" in your project's MKB file, for example:

    subprojects
    {
      iwutil
      /path/to/this/repo/peanutlabs
    }

  3. Include the extension header's file in your source code.

  4. Call the method "openRewardCenter" with the generated userID as a parameter. Example:

    openRewardsCenter("END_USER_ID-APPID-HASH")

  5. You will need the following application plist file in order for the system to work for iOS 9:

    <key>NSAppTransportSecurity</key>
      <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
      </dict>

  6. Run peanutlabs_android.mkb and then peanutlabs_android_java.mkb to build android extensions.

  7. You will need the following activity to your Manifest.xml file in order to run android application with the reward center:

    <activity
      android:name="com.peanutlabs.plsdk.RewardsCenterActivity"
      android:configChanges="keyboard|keyboardHidden|screenSize|orientation"
      android:label="@string/title_activity_rewards_center" >
    </activity>

Cordova

Our SDK allows you to integrate our Reward Center within your Cordova application for Android. The Cordova Plugin only supports Android at the moment, though we do plan on supporting iPhone in the near future. If you see any issues, please use the Github issues to report them. The SDK and further instructions can be found here.

  1. To add plugin:

    cordova plugin add https://github.com/peanut-labs/publisher-cordova-plugin.git

  2. To remove plugin:

    cordova plugin remove PeanutlabsLib

  3. Include the following line in your js file where you want to use our plugin:

    <script type="text/javascript" src="plugins/PeanutlabsLib/www/peanutplugin.js"></script>

  4. Call the following methods with appropriate parameters to open Reward Center:

    PeanutlabsPlugin.openRewardsCenterWithAppId(YOUR_APP_ID, YOUR_APP_KEY, USER_ID, YOUR_DOB, GENDER, CUSTOM_PARAM, success, error);

    PeanutlabsPlugin.openRewardsCenterWithAppId(YOUR_GENERATED_USER_ID, YOUR_DOB, GENDER, CUSTOM_PARAM, success, error);

  5. See example project in github for more details.

Sending user profiles

You can encrypt your user’s profile and send it using payload parameter on the query string. User will not be asked any attributes that are sent with the payload. Please refer to profile attributes document to map your user’s profile attributes to our profile attributes.

Please map as many of your user’s attributes to Peanut Labs attributes for better targeted survey for your users. Invalid user profiles will be rejected.

 

JSON profile payload before encryption:

  • user_id
    mandatory
    string

    Three part user id. See Generating the Peanut Labs user id.

  • cc
    mandatory
    string

    ISO ALPHA-2 code

     

  • dob
    mandatory
    date

    YYYY-MM-DD

     

  • sex
    mandatory
    integer

    Panelist gender (1 for male, 2 for female)

  • postal
    mandatory
    string

    Zip/postal code

     

    See Profile attributes document for the valid regex format per country.

    Peanut Labs derives user’s country based on the browser user agent.
  • profile_data
    hash; each key in the hash is the attribute_id of that attribute

    Collection of key-value pair of other profiling attributes.

    • Show child attributes
    • attribute_id as key array

      List of option attribute_id as values.

      Profile attributes document lists all our profile attribute. You should map all your user’s attributes to our attributes to improve your user’s experience.
Example for mapping your profile attributes and generating encrypted payload
  1. Map your user attributes to Peanut Labs attributes using the Profile attributes document. Here’s an example of sample mapping.

    • User info in your database

      User info translated to Peanut Labs format

    • user001

      user_id: user001-1001-2389d74882

      See Generating the Peanut Labs user id

    • From United States

      cc: US

    • Male

      sex: 1

    • Born on April 10, 1990

      dob: 1990-04-10
      Format: YYYY-MM-DD

    • Lives near zip code 94104

      postal: 94104

    • Owns a residence

      q122: qx122-0

    • Doesn’t own a car

      q159: qx159-1

    • Annual household income of $125K

      q102: qx102-105

    • Self employed

      q158: qx158-3

    • Have Bachelor's degree

      q101: qx101-2

    • Have 3 children

      q157: 3

    • Male child was born in April of 2004

      ch-m: 4-2004
      Format: (MM-YYYY)

    • Female children were born on Oct 1998 and Nov 1999

      ch-f: 10-1998, 11-1999
      Format: (MM-YYYY)

  2. Construct mapped attributes into a JSON payload. For the above sample mapping, the following will be the JSON payload:

    {"user_id":"user001-1001-2389d74882","cc":"US","sex":1,"dob":"1990-04-10","postal":"94104","profile_data":{"q122":["qx122-0"],"q159":["qx159-1"],"q102":["qx102-105"],"q158":["qx158-3"],"q101":["qx101-2"],"q157":["3"],"ch-m":["4-2004"],"ch-f":["10-1998","11-1999"]}}

  3. Generate a random iv and encrypt the payload using the iv using the following PHP code:

    <?php

    $jsonPayload = '{"user_id":"user001-1001-2389d74882","cc":"US","sex":1,"dob":"1990-04-10","postal":"94104","profile_data":{"q122":["qx122-0"],"q159":["qx159-1"],"q102":["qx102-105"],"q158":["qx158-3"],"q101":["qx101-2"],"q157":["3"],"ch-m":["4-2004"],"ch-f":["10-1998","11-1999"]}}';

    $applicationKey = 'abcdef0123456789abcdef0123456789';

    function getInitVector() {
    $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
    $iv = urlencode(base64_encode(mcrypt_create_iv($iv_size, MCRYPT_RAND)));
    return $iv; // Store $iv and pass it while encrypting payload
    }

    // Add AES padding
    // Used in encryptJSONPayload
    function addAESPadding($payload) {
    $block_size = mcrypt_get_block_size( MCRYPT_RIJNDAEL_128 ,MCRYPT_MODE_CBC);
    $pad = $block_size - (strlen($payload) % $block_size);
    return $payload . str_repeat(chr($pad), $pad);
    }

    // Encrypts and encodes profile payload
    // Pass the init vector generated by getInitVector
    function encryptJSONPayload($payload, $applicationKey, $iv) {
    $payload = addAESPadding($payload);
    $applicationKey = pack('H*', $applicationKey);
    $payload = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $applicationKey, $payload, MCRYPT_MODE_CBC , base64_decode(urldecode($iv)));
    $payload = base64_encode($payload);
    $final_payload = urlencode($payload);
    return $final_payload;
    }

    $iv = getInitVector(); // This is the iv to pass with the user
    $payload = encryptJSONPayload($jsonPayload, $applicationKey, $iv); // This is the encrypted payload to pass with the user
    print ($iv);
    print ($payload);

    ?>

  4. Invoke the redirect URL for your user:

    https://dlink.peanutlabs.com/direct_link/?pub_id=xxxx&user_id=xxxx&sub_id=xxxx&iv=xxxx&payload=xxxx

Common Deployment Steps

We highly recommend that you whitelist our IPs to ensure all valid callbacks are coming from our system. This will vastly decrease any fraudulent activity. If the list of IPs is to change, you will be notified via email prior to the change so that you may make the proper updates in your system. This full lists of IPs can also be found at the bottom of this guide.

 

 

Your Callback URL is specified in your Application Setup (see screenshot):

When one of your users completes a survey or offer, Peanut Labs will send a notification to the processing script at the address specified above.

 

Callback Parameters:

  • cmd

    will always be transactionComplete

  • userId

    Peanut Labs userId as generated earlier.

  • amt

    amount paid in dollars to you for this particular transaction. In rare cases we may pass a negative value to indicate a chargeback. (See more on chargebacks below)

  • offerInvitationId

    enables you to remember for which offer a user has been rewarded for.

  • status

    F - user screened out of survey, the required number of responses from this demographic has already been met.

    C - user successfully completed the transaction.

    P - user screened out of survey, does not have the relevant attributes needed.

  • oidHash

    32 character hex string = md5(concat(offerInvitationId, applicationKey))

    You should verify oidHash upon receipt of the callback by recomputing it with the callback offerInvitationId and your ApplicationKey. This will secure against users faking their own id and passing it in if by some chance they come across the script.
  • currencyAmt
    integer (default) or float (on request)

    Indicates how many points the user should get in your site’s virtual currency. Based on your configured conversion rate on the control panel. Negative values indicate chargebacks.

  • transactionId
    string

    Unique ID representing a single user participating in a single survey/offer.

  • txnHash
    string

    32 character hex string = md5(concat(transactionId, current TransactionKey)) You can find your TransactionKey in your Application list.

    You should verify txnHash upon receipt of the callback by recomputing it with the callback transactionID and your current Transaction Key. This will secure against users faking their own id and passing it in if by some chance they come across the processing script and Application Key. The Transaction Key may be regenerated for this reason. If you would like to regenerate your Transaction Key please contact your Account Manager.
  • offerTitle
    string

    Title of the survey or offer. Spaces replaced with '+'.

  • profiler
    deprecated

    By default there is no notification sent when a user completes a profiler.

  • useragent
    string

    This value is provided for backwards compatibility. It will always say 'Peanut+Labs+Media'.

  • currencyName
    string

    We will return the name of the currency that you've set in the Application Setup. This is the name of the currency that you are rewarding to the user.

  • offerType

    Survey or Offer

  • Program
    string

    If you have multiple currency support on your app, this field will include will include the id for the currency for a given transaction. Contact your PL account manager to learn more about multiple currency support.

Your Response to the Peanut Labs Callback

Upon successfully processing the user’s reward, your callback script should respond with:

  • 1

    acknowledged. Notification successfully processed

  • 0

    user does not exist or reward not successfully awarded for some other reason

Your script should simply return 0 or 1. Any other markup will cause Peanut Labs to assume 0.

The notification will be retried up to 5 times. If you are receiving multiple callbacks from Peanut Labs for the same transaction the most likely reason is we are not getting a '1' response from you.

The timeout for our notifications is 5 seconds. If we don't receive a response within the timeout we assume a '0' response and will attempt a re-notification.

Example Peanut Labs Callback (GET request)

https://yoursite.com/process.php?cmd=transactionComplete&userId=SampleUser-xxxx-xxxx&amt=1&offerInvitationId=xxx&status=X&oidHash=xxxxx&currencyAmt=100&transactionId=1234&txnHash=xxxxx&endUserId=SampleUser&offerTitle=Your+Offer&useragent=Peanut+Labs+Media&profiler=&currencyName=Coins&offerType=Survey&txnHash=xxxxxx&program=Coins

Callback Testing

We highly recommend testing notifications with the ‘Invoke Test Call’ feature in Application Setup. The fields will be populated with some template test values that you may edit if you choose. All you need to do is select the status of the transaction you wish to test the callback for.

Upon invoking a test call, you will be shown the response received from your processing script. You will also see the Sample Call that was made with all parameters in order.

Contact your PL Account Manager to help set up some test surveys. These test surveys are easy/very quick to complete and will help you test the callbacks.

IPs to Whitelist

The following list contains all our IPs that should be whitelisted for callbacks:

75.101.154.153
54.243.235.176
54.243.210.15
54.243.204.6
54.243.150.156
54.243.150.126
54.243.149.248
54.243.149.247
54.243.146.21
54.243.143.97
50.19.92.139
50.17.194.132
50.17.193.185
50.17.191.62
50.17.191.143
50.17.190.69
50.17.190.174
50.17.189.251
50.17.189.201
50.17.189.138
50.17.187.32
50.17.187.218
50.17.187.192
50.17.187.145
50.17.186.7
50.17.186.39
50.17.184.98
50.17.184.153
50.17.182.38
50.17.182.19
50.17.182.17
50.17.181.130
50.17.181.118
50.17.181.11
50.16.250.192
50.16.249.58
50.16.249.162
50.16.245.185
50.16.243.67
50.16.241.60
50.16.239.186
50.16.236.39
23.21.123.40
184.73.254.159
184.73.254.133
184.73.250.161
184.73.249.128
184.73.244.77
184.73.196.208
184.73.166.67
184.73.158.48
184.73.153.111
184.72.230.119
184.72.222.51
184.72.222.104
184.72.221.219
174.129.37.199
174.129.242.30
174.129.240.137
174.129.238.17
174.129.237.1
174.129.22.190
174.129.219.230
174.129.209.23
174.129.209.2
107.22.164.69
107.22.164.67
107.22.164.59
107.22.164.55
107.22.164.53
107.22.164.5
107.22.162.83
107.22.160.89
107.22.160.31
107.22.160.14
107.20.248.88
107.20.246.140
107.20.235.89
107.20.201.76
107.20.152.198

Engage

Customize your Deployment

You may customize the look of your deployments in Application Setup.

Here you can choose the palette of your deployment if you’d like the color scheme to be consistent with your website or application. If you do not wish to customize your deployments, the default color palette you see will be the one used.

Here you can choose the palette of your Reward Center if you’d like the color scheme to be consistent with your website or application. If you do not wish to customize your Reward Center, the default color palette you see will be the one used.

The importance of having a Screenout Reward

Screenouts occur when a user answers a few questions in a survey and receives a message telling them that they do not qualify. Market researchers often require candidates for their survey who fit certain criteria. They are banned from retaining any responses of a user who they screen out, and Peanut Labs does not receive payment either. However, the user does lose a few minutes of their time.

Though Peanut Labs at the moment does not pay for screen out rewards, as a publisher it’s always a good idea to give a very small reward to users encouraging them to try again. If they are assured that they will get something even if they don’t get the full payout, users are far more likely to keep trying, hence increasing your revenue. Data from across our publisher network has proven that a minimal screenout reward is the most effective tool in a publisher’s arsenal to increase revenue and user engagement.

Monetization API

The Monetization API allows you to access the Peanut Labs system even when your user is not on the Reward Center.

  • API Endpoint

    https://api.peanutlabs.com/publisher/api/v1/

  • Request

    HTTP or HTTPS

    We highly recommend using HTTPS.
  • Response

    JSON or JSONP

Error Handling

API requests that result in an error will have a diagnosis code in the returned object.

Error codes

  • 1

    JSON Error

  • 2

    Publisher ID Invalid

  • 3

    User is Banned.

    This may be temporary or permanent depending on the severity of the infraction.
  • 4

    User ID Invalid

  • 5

    Required Parameters Missing

Example
{
  "errorInfo": {
    "error": "Invalid User Id", 
    "reset": 1, 
    "code": 4
  }
}

Campaigns Summary

The campaigns summary is used to retrieve a count of surveys and offers are available for a user, along with potential reward they could earn from completing them. A successful request will return an object containing a surveys object and an offers object, with each of those reporting their count and total potential reward. The object will also vary depending on your specific publisher configurations and request parameters.

Resource URL

https://api.peanutlabs.com/publisher/api/v1/campaigns_summary

Parameters

  • User ID

    user_id

  • User IP Address
    optional

    user_ip

 

The User IP address parameter is an optional parameter. By default the campaign summary method uses the IP address of the caller to determine GeoIP. If your servers are going to make a request to the API on behalf of a user, you can pass their ip address to us with the optional user_ip parameter.

Example Call

https://api.peanutlabs.com/publisher/api/v1/campaigns_summary?user_id=avdempsey-8711-2dc2f9fe98

Campaign Summary Object Attributes

Attributes

  • count

    The number of surveys or offers available for the user.

    Users have a daily limit of 15 survey attempts per day and a maximum of 9 surveys per Reward Center load, so these will affect the count returned in the surveys object
  • total_reward

    The total amount of virtual currency a user could potentially receive if they complete all the surveys or offers.

  • status

    This is only returned in the surveys object and indicates if is profiled or not. If the user is already profiled it will be set to profiled, if they are not profiled and there is a profiler available in their country it will be profiler_available and if there is no profiler available it will be set to non_profiled. For more details on the profiler survey, see the section in the campaigns method section.

Example
{
  "surveys": {
    "status": "profiled", 
    "count": 3, 
    "total_reward": 10
  }, 
  "offers": {
    "count": 12, 
    "total_reward": 64
  }
}
Using Campaign Summary as a Survey Alert

One of the great examples of how the campaign summary method can be used is our open source Survey Alert project.

A Survey Alert notifies your users whenever they have surveys available from any section of your site. It has proven to be one of the best tools to improve revenue with Peanut Labs.

To implement the Survey Alert, check out our open source Survey Alert project:
https://github.com/peanut-labs/survey-alert