Custom API

Introduction

We may not yet support your platform for getting data into Fanplayr 360, so we offer a powerful API to work directly with our system to add data.

You can use the Custom API to send data from a server, or a mobile app. The options a limitless.

The JavaScript API uses exactly the same calls under the hood.

Sending Messages

Once you have created a Custom Integration before starting, to get a WRITE_KEY and ENDPOINT which you can then use to send data to Fanplayr 360.

Calling the API is as simple as making an HTTPS request with the following details:

• URL: https://<ENDPOINT>/v1/collect

• Method: POST

• Headers

  • content-type: application/json

  • x-api-key: <WRITE_KEY>

• Body: A JSON string containing an array of Messages.

Example Request

cURL

curl 'https://<ENDPOINT>/v1/collect' \
  -H 'x-api-key: <WRITE_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '[<JSON_MESSAGE>, <JSON_MESSAGE>]'

NodeJS

fetch("https://<ENDPOINT>/v1/collect", {
  "headers": {
    "x-api-key": "<WRITE_KEY>",
    "content-type": "application/json"
  },
  "body": "[<JSON_MESSAGE>, <JSON_MESSAGE>]",
  "method": "POST"
});

The API can only handle messages of ~250kb, so we calling the API with no more than 20 Messages in one call.

Message Structure

Each message you send to Fanplayr 360 needs to contain a basic set of data.

Basic Message

Interface

interface Message {
  messageId: string
  writeKey: string
  timestamp: string
  type: 'track' | 'identify' | 'userDataOps', 'consent' | 'page'
  userId: string
  sessionId: string
  pageId: string
  context?: Context,
  properties?: Properties,
  identities?: Identities,
  operations?: Operations
}

Example

This example is for a "Product Viewed" event.

{
  "messageId": "e807330e-548f-48d3-a085-1916cf60c8f9",
  "writeKey": "6Zwh5IambQViWaflO4Lbc",
  "timestamp": "2022-11-15T04:34:48Z",
  "type": "track",
  "userId": "5.xYO1xcnVEwkbcw6J9HS.1658486855",
  "sessionId": "22f74b648fc794768db4659ce2e634a7",
  "pageId": "22f74b648fc794768db4659ce2e634a7-3",
  "event": "Product Viewed",
  "context": {
    "page": {
      "url": "https://www.mystore.com/product1/",
      "referrer": "https://www.mystore.com/home/",
      "type": "product"
    },
    "ipAddress": "127.0.01",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Mobile/15E148 Safari/604.1"
  },
  "properties": {
    "showFP": "1",
    "$product": {
      "id": "A0528",
      "sku": "A0528",
      "name": "Stretch Satin Ribbon",
      "price": 7.5,
      "salePrice": 7.5,
      "url": "https://www.mystore.com/product1/",
      "imageUrl": "https://cdn1.mystore.com/image/395x526/product1.jpg",
      "categories": []
    }
  }
}

• messageId - Every message you send must include a unique identifier. We suggest using a UUID, nanoID or ulid.
• writeKey - The WRITE_KEY that is sent through in the x-api-key must also be supplied here.

• timestamp - The time the event happened in ISO-8601 format and UTC time zone ie "2023-01-23T15:34:48Z".
• type - The type of the message.

• userId - A unique identifier for this user. If the same userId is supplied in a different session the messages will be treated as if they were from the same user. This is separate from managing identify using identify calls.
• sessionId - A unique identifier for a session. See Handling Sessions for more details.
• pageId - A unique identifier for the current page / screen view. This is used to tie events together. See Tracking Page Views.

The basic message structure may or may not include context, properties, identities and operations depending on the type being sent.

• context - can be used in any message type

• properties - should only be used in track or page type

• identities - should only be used in identify type

• operations - should only be used in userDataOps and consent type

Context

Context is used to track information about the page, or screen, the user is on, and their IP address for location, and userAgent to track browser or device type.

Interface

interface Context {
  page: {
    url: string
    referrer: string
    type: string
    title: string
  },
  ipAddress: string
  userAgent: string
}

Example

{
    "page": {
      "url": "https://www.mystore.com/product1/",
      "referrer": "https://www.mystore.com/home/",
      "type": "product"
    },
    "ipAddress": "127.0.01",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Mobile/15E148 Safari/604.1"
  }

• page

  • url - the URL of the page, if tracking on a website.

  • referrer - the URL of the referring page, if tracking on a website.

  • type - a string representing the page. Any value can be used here, but some values will add functionality - see JavaScript API / Track Pages. Can also be used to represent "screens" in a mobile app.
  • title - the page title of the website or app screen.

• ipAddress - the IP address of the users device, or the server / device that this message was sent from. It is used to generate extra attributes such as $country .
• userAgent - the User Agent string from a browser, or defined for a device type such as a mobile phone. It is used to generate extra attributes such as $device .

Properties

Properties are any key / value pair, or Semantic Object, which you want to track along with the event. This should only be used with track or page type Messages.

Interface

interface Properties {
  [key:string]: string | number | boolean | SemanticObject
}

Example

This data would track two custom attributes and a single Semantic Object.

{
  "customAttribute": "Custom Value",
  "Another Custom Attribute: 10,
  "$product": {
    "id": "BX54Y",
    "name": "Great Red Shoes",
    "price": 12.99
  }
}

The key for a property can be any string value. It is a suggestion to not start the value with a "$" as this may override generated attributes. It may also be good practice to use either camel-case keys such as "myKeyName", and stay away from non-ASCII characters as some systems you export data to may otherwise have problems.

Although you can send in string , number or boolean types all data is stored as strings in Fanplayr 360.

Identities

Identities are key / value pairs that let the system know how to identify and merge users and sessions. This should only be provided for the message type identify.

Interface

type Identities = {
  [key:string]: string
}

Example

An example which identifies a user by both email and phone number.

{
  "email": "[e-mail]",
  "phone": "5555555555"
}

Operations

Operations should only be used with the userDataOps and consent type messages. The properties supported are different for each.

userDataOps

Interface

interface Operation {
  type: 'set' | 'setOnce' | 'unset' | 'increment'
  key: string
  value: string | number | boolean
  expiresOn?: number,
}

type Operations = Array<Operation>

Example

An example of an operation which could be used with userDataOps message type to set the user profile property $age to 47, and increment numberOfTimesSignedIn by 1.

[
  {
    "type": "set",
    "key": "$age",
    "value": 47
  },
  {
    "type": "increment",
    "key": "numberOfTimesSignedIn",
    "value": 1
  }
]

consent

Interface

interface Operation {
  type: 'set' 'unset'
  key: string
  value: string
  purpose?: Array<{
    type: string
    topics:? Array<string>
  }>
}

type Operations = Array<Operation>

Example

What next?

Read on to understand how to use each message type, along with examples.

• Handling Sessions
• Tracking Page Views
• Tracking Events
• Managing Identity
• Managing Consent