Manual Integration

Introduction

This method of integration involves creating a small HTTPS API on your domain which Fanplayr can interact with via its JavaScript to store and retrieve the user identifier.

Reading the value stored in the server-side user identity cookie.

When Fanplayr needs to read the user identity cookie it will execute a request to the web server. Each of the points in the diagram above are described here:

• Read cookie request (1) — Fanplayr's JavaScript executes a GET request from the browser to your web server at the location defined by the connect.endpoint property in the Fanplayr JavaScript configuration. If the user's identity has been previously stored in the cookie and it still exists, the browser will include the cookie in the request to the server.

• Read cookie response (2) — If the cookie is available, the web server should read the cookie value and respond with the decoded value to the browser. This value will be a JSON object.

Updating the value stored in the server-side user identity cookie.

When Fanplayr needs to update the value stored in the user identity cookie it will execute a GET request with a data parameter with the value to store. Each of the numbered points in the diagram above are described here:

• Write cookie request (3) — Fanplayr's JavaScript makes a GET request from the browser to your web server at the location defined by the connect.endpoint property in the Fanplayr JavaScript configuration.

• Write cookie response (4) — The server responds to the request with a Set-Cookie header that instructs the bowser to store the new value in the cookie for up to 1 year at the base path of the website. Implementation details are included later in this document. Finally the server includes the decoded cookie value as the response body.

How it works

You will need to define a small HTTPS API on your server which will read or write to a secure cookie on your domain. Fanplayr's JavaScript library will invoke this API from the browser when it needs to retrieve or update the user identifier.

Defining your API url in the page tracking snippet Define the connect property for both page tracking and order tracking code as an object with the following values:

• endpoint

  • Type: string

  • Required

  • Details: The full url of the custom API you implemented

• baseDomain

  • Type: string

  • Details: If the cookie needs to be stored

{
  accountKey: '...',
  connect: {
    endpoint: 'https://store.com/api/connect.php',
    baseDomain: 'store.com'
  }
}

Storing the user identifier When Fanplayr needs to store the user identifier it will make a request to your API including a data query parameter with the value to store. This value will be a URL encoded JSON string. For example:

https://store.com/api/connect.php?data=%7B%22value%22%3A%221234%22%7D

• Your API should write the value to a secure cookie (with a name of your choice) with the following attributes:

  • Expires: (1 year from current time)

  • HttpOnly

  • Secure

  • SameSite: Strict

  • Path: /

• Your API should also return the decoded JSON value like so:

{"value":"1234"}

Retrieving the user identifier When Fanplayr needs to retrieve the user identifier it will make the same API request but without the data query parameter, for example: https://store.com/api/connect.php

• Your API should read the value from your cookie defined in the previous step and return the decoded JSON value like so:

{"value":"1234"}

Example code

The following code examples demonstrate storing and retrieving the user identifier using a cookie named _fphu:

PHP

<?php
// The `data` parameter is a url-encoded JSON string, but this gets
// automatically decoded in $_GET variable.
$data = $_GET["data"];
$cookieName = "_fphu";
if (!empty($data)) {
  // Store the encoded value in the cookie.
  $encoded = urlencode($data);
  header("Set-Cookie: ${cookieName}=${encoded}; Path=/; Max-Age=31536000; HttpOnly; SameSite=Strict; Secure", false);
  // Respond with the decoded JSON data.
  echo $data;
} else {
  // Otherwise retrieve the data from the cookie and respond with it.
  echo $_COOKIE[$cookieName];
}

JSP

<%@ page import="java.net.URLEncoder" %>
<%@ page import="java.net.URLDecoder" %>
<%
  String data = request.getParameter("data");
  String cookieName = "_fphu";
  if (data != null) {
    // Store the value in the secure cookie for 1 year.
    try {
      String encodedData = URLEncoder.encode(data, "UTF-8");
      response.setHeader("Set-Cookie", cookieName + "=" + encodedData + "; Path=/; Max-Age=31536000; SameSite=Strict; HttpOnly; Secure");
    }
    catch(Exception e) {
    }
  } 
  else {
    Cookie[] cookies = request.getCookies();
    if (cookies != null) {
      for (int i = 0; i < cookies.length; i++) {
        if (cookies[i].getName().equals(cookieName)) {
          data = cookies[i].getValue();
          if (data != null) {
            data = URLDecoder.decode(data, "UTF-8");
          }
          break;
        }
      }
    }
  }
  if (data != null) {
    out.print(data);
  }
%>

Node/Express

// This is an example of how you would implement this feature using
// the Express.js framework and assuming you wanted to store the data
// in a cookie named "_fphu".
const cookieName = '_fphu'
app.get('/api/connect', (req, res) => {
  const data = req.query.data
  if (data) {
    // Store the data for 1 year.
    res.cookie(cookieName, data, {
      path: '/',
      maxAge: 31536000000,
      httpOnly: true,
      sameSite: 'Strict',
      secure: true
    })
    res.send(data)
  } else {
    // Retrieve the data.
    res.send(req.cookies[cookieName])
  }
})

If you are hosting this API on a subdomain that is separate to the domain which Fanplayr's tracking code is on, you will need to ensure that the API is compatible with CORS requests.

This can generally be achieved by outputting the following headers in your API response:

• Access-Control-Allow-Origin: https://store.com Note: you will need to replace "https://store.com" with your domain, or ensure that the value is the same as the value of the incoming Origin request header.

• Access-Control-Allow-Methods: OPTIONS, GET

• Access-Control-Allow-Headers: Origin

• Access-Control-Allow-Credentials: true