Session offers

With an additional simple integration step, Fanplayr can help prevent unauthorized users from claiming discounts on your store.‌

This mechanism aims to solve the problem many online stores have faced from coupon sharing sites such as Coupons.com and RetailMeNot. Fanplayr achieves this by limiting the offers it presents to your users so they are only valid during the current visit.‌

How It Works

‌You devise a way to identify offer codes that are exclusive to Fanplayr in your system.

1. Fanplayr will notify your system when an offer is presented to the user. Your system remembers these offers for the duration of the user's session.

2. When a user attempts to apply a Fanplayr offer code, your system only allows it if it remembers the code from the previous step.

48KB

SessionOfferFlow.pdf

pdf

Example Flow

‌One simple method to identify offer codes that are exclusive to Fanplayr is to prepend a special prefix to them.

1. For example, you might use "FP_" as the prefix and have a free shipping code, "FP_FREESHIP", defined in your system.

2. You provide Fanplayr with a sessionOfferUrl as part of your user tracking implementation.

   For example, the session offer URL might be: https://example.com/allowOffer.php?code=%c​

3. When Fanplayr presents an offer to your users it will invoke the URL (as a GET request) to notify your system that the offer code is valid in the current session.

   Your system must store the offer code in an array that is persisted for the duration of the user session. We'll refer to this as the validSessionCodes array.

   Fanplayr will replace the %c parameter in the URL with the actual offer code. E.g. https://example.com/allowOffer.php?code=FP_FREESHIP​

4. Your system must validate offer codes before applying them to the cart. When attempting to apply an Fanplayr code (e.g. it begins with the "FP_" prefix), it must only be applied to the cart if the code it exists in the validSessionCodes array.

   If a Fanplayr code does not exist in the array, the code must be considered invalid and rejected by the system.

Example Implementation

1. Configuration

The first step in this process is to supply the sessionOfferUrl to the Fanplayr user tracking snippet. This URL will be invoked with each offer code that is presented to the user. The %c parameter will be replaced with the actual offer code.‌

E.g. https://example.com/allowOffer.php?code=%c will become https://example.com/allowOffer.php?code=FP_FREESHIP​‌

This configuration step does not apply for custom Javascript Adaptors built by us. In this case, you will need to provide the sessionOfferUrl to us so we can update your integration.

{
  type: 'st',
  accountKey: '7e43c8cddccade2b95ee5286ba89758a',
  sessionOfferUrl: 'https://example.com/allowOffer.php?code=%c',
  data: {
    // User tracking data
  }
}

2. Storing session offers in your system

‌Next you'll need to implement a new endpoint in your system that captures Fanplayr offer codes as they are presented to your users and adds them to an array for the duration of the user session.‌

The URL you specify in the sessionOfferUrl variable will be invoked as a GET request by the Fanplayr widget.

PHP

// PHP Example
// https://example.com/allowOffer.php

// Initialize the session codes array it if necessary.
if (!is_array($_SESSION['validSessionCodes'])) {
  $_SESSION['validSessionCodes'] = array();
}

// Get the offer code provided by Fanplayr and mark it as valid.
$code = $_REQUEST['code'];
$_SESSION['validSessionCodes'][strtoupper($code)] = true;

JavaScript

// Node.js / Express Example

// Initialize the session codes array it if necessary.
const validSessionCodes = req.session['validSessionCodes'] || {};

// Get the offer code provided by Fanplayr and mark it as valid.
const code = req.query.code;
validSessionCodes[code.toUpperCase()] = true;
req.session['validSessionCodes'] = validSessionCodes;

‌3. Validate offers being applied to the cart

For the final step, you'll need to make a small change to your system so that it validates all offer codes before applying their discounts.‌

We've provided an implementation example of a method that could be used to validate codes that begin with the FP_ prefix. Only the codes that begin with this prefix will be checked to ensure they were actually presented by Fanplayr during the user's session. All other non-prefixed codes will be considered valid immediately.‌

This method should be used throughout your system in any place that an offer code can be applied to the cart.

PHP

// PHP Example
function validate_offer_code($code) {
  // Validate the code if it begins with the Fanplayr prefix.
  if (is_string($code) && stripos($code, 'FP_') === 0) {
    // Ensure that the code exists in the session codes array.
    return is_array($_SESSION['validSessionCodes']) &&
      array_key_exists(strtoupper($code), $_SESSION['validSessionCodes']);
  }
  // The code is not prefixed, so allow it immediately.
  return true;
}

// Part of system that applies user-submitted code to the cart.
// E.g. https://example.com/cart.php
$code = $_REQUEST['coupon_code'];
if (validate_offer_code($code)) {
  // Continue to apply discount.
} else {
  // Notify user the code is invalid.
}

JavaScript

// Node.js / Express Example
function validateOfferCode(code) {
  if (/^FP_/i.test(code)) {
    // Ensure that the code exists in the session codes array.
    const validSessionCodes = req.session['validSessionCodes'] || {};
    return validSessionCodes[code.toUpperCase()];
  }
  // The code is not prefixed, so allow it immediately.
  return true;
}

// Part of system that applies user-submitted code to the cart.
const code = req.query.coupon_code;
if (validateOfferCode($code)) {
  // Continue to apply discount.
} else {
  // Notify user the code is invalid.
}

Using POST (or callback)

‌Sometimes you may not be able to simply hit a URL to set a Session Offer (for example if you are keeping this information in localStorage). In this case you can supply a function to the Fanplayr platform instead of the URL in sessionOfferUrl.

// fanplayr_ready function is called once the main Fanplayr scripts are loaded
window.fanplayr_ready = function(){ 
  window.fanplayr.platform.capabilities.deputizeOffer = function(event) {
    // You can now access event.code
    console.log(event.code);
    // You must return here, and anything other than "false" will be treated
    // as success.
    return; // succeeded
    // OR
    // This means the setting of session offer has failed, and will be retried
    // on a later call
    return false; // failed
  };
}