Custom ESP

Note: This documentation is still work in progress and subject to change.

Introduction

This document describes a proposal for a new Custom ESP integration that would provide a generic data structure to represent events supported by Fanplayr's ESP stream interface.

Endpoint configuration

This ESP can be configured from the Streams > Endpoints section of the Fanplayr portal. Below is an example of the potential configuration options that will be available:

Post URL

The URL which Fanplayr will stream payloads to via the HTTP POST method. The request body will contain the JSON data structure described later in this document.

  • Type: string

API Key

An optional API key that will be included in the POST request to your URL that can be used for authentication purposes.

Stream configuration

To send data to the endpoint you have defined, you will need to create a stream which is triggered by the desired event you which to capture and has an action which sends data to the endpoint.

The example below triggers on the "Session Expiry" event.

Payload structure

Below is an example of the payload structure that is sent when using the Custom ESP integration. This structure is used to 

{
  "version": "2022-01-01",
  "eventType": "addContact" | "abandonedSession" | "abandonedCart" | "order",
  "sessionKey": "",
  "domain": "",
  "siteCustomerId": "",
  "subscriberEmail": "",
  "subscriberKey": "",
  "date": "2022-01-01T00:00:00Z",
  "customData": {
    "key1": "value1",
    "key2": "value2"
  },
  "abandonedCart": {
    "gross": 0,
    "discount": 0,
    "discountCode": "",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "",
        "sku": "",
        "name": "",
        "url": "",
        "image": "",
        "quantity": 0,
        "category": ""
      }
    ]
  },
  "orderDetails": {
    "id": "",
    "gross": 0,
    "discount": 0,
    "discountCode": "",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "",
        "sku": "",
        "name": "",
        "url": "",
        "image": "",
        "quantity": 0,
        "category": ""
      }
    ]
  },
  "productsViewed": [
    {
      "id": "",
      "sku": "",
      "name": "",
      "url": "",
      "image": "",
      "category": ""
    }
  ],
  "relatedProducts": [
    {
      "id": "",
      "sku": "",
      "name": "",
      "url": "",
      "image": "",
      "category": ""
    }
  ]
}

version

Represents the payload structure format.

  • Type: string

eventType

Specifies the event type which this payload represents.

  • Type: string

  • Details: The event type will be equal to one of the following values:

    • addContact - Triggered when a new email address is captured for a user.

    • abandonedSession - Triggered at the end of the browsing session the user had no products in their shopping cart and did not place an order.

    • abandonedCart - Triggered at the end of the browsing session the user had at least one product in their cart which they abandoned and did not place an order.

    • order - Triggered when an order is captured.

domain

The domain name of the website the user browsed during their Fanplayr session.

  • Type: string

siteCustomerId

Represents the logged in user identifier for the website if available. This value is assigned via Fanplayr's page tracking customerId property or from the $siteCustomerId identity using the Identity Management feature.

  • Type: string | undefined

subscriberEmail

This value will be populated if Fanplayr has associated an email address with the user via a Fanplayr widget during the current session, or in a previous session.

  • Type: string | undefined

subscriberKey

Represents the user's identity when using Fanplayr's Identity Management feature.

  • Type: string | undefined

date

The date the event was created, in GMT, in ISO 8601 format.

  • Type: string

sessionKey

A unique identifier representing the Fanplayr browsing session ID.

  • Type: string

customData

An object containing key-value pairs of any custom data that has been attached to the event via the Fanplayr Stream that was used to trigger and control the event.

interface CustomData {
  [key: string]: string
}

Example

{
  "key1": "value1",
  "key2": "value2"
}

abandonedCart

An object which represents the final state of the shopping cart when one or more products remains in the cart at the end of the session.

interface CartDetails {
  // A currency value representing the total gross amount
  // of all items in the cart.
  gross: number
  // A currency value representing the total discount applied to the cart.
  discount: number
  // Any discount code applied. If there are multiple codes, they will be separated
  // with a comma.
  discountCode?: string
  // A currency value representing the cost of shipping.
  shipping: number
  // A currency value representing any taxes.
  tax: number
  // Represents the ISO 4217 currency code for all currency values.
  currencyCode: string
  // An array of products added to the cart.
  products: CartProduct[]
}

interface CartProduct {
  // The product variant identifier.
  id: string
  // The product group identifier.
  sku: string
  // The product display name.
  name: string
  // The full URL to the product on the website.
  url: string
  // The full URL to the product's primary image if available.
  image?: string
  // The quantity of the product added to the cart.
  quantity: number
  // The product category name if available.
  category?: string
}

Example:

{
  "gross": 120.00,
  "discount": 10,
  "discountCode": "10OFF",
  "shipping": 0,
  "tax": 0,
  "currencyCode": "USD",
  "products": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "quantity": 2,
      "category": "Accessories"
    }
  ]
}

productsViewed

An array of objects representing the details of products which where viewed during the session.

  • Type: ViewedProduct[]

interface ViewedProduct {
  // The product variant identifier.
  id: string
  // The product group identifier.
  sku: string
  // The product display name.
  name: string
  // The full URL to the product on the website.
  url: string
  // The full URL to the product's primary image if available.
  image?: string
  // The product category name if available.
  category?: string
}

Example:

[
  {
    "id": "RDB1-A2",
    "sku": "RDB1",
    "name": "Rifiano Duffel Bag",
    "url": "https://store.com/products/rdb1",
    "image": "https://cdn.store.com/products/rdb1-01.jpg",
    "category": "Accessories"
  },
  {
    "id": "VDD-1",
    "sku": "VDD",
    "name": "Vintage Denim Dress",
    "url": "https://store.com/products/vdd1",
    "image": "https://cdn.store.com/products/vdd1-01.jpg",
    "category": "Womens > Clothing"
  }
]

relatedProducts

An array of objects representing the details of products which are related to the event.

  • Type: RelatedProduct[]

  • Details: This property will only exist in the payload if product recommendations were added to the event (configured via the Stream).

interface RelatedProduct {
  // The product variant identifier.
  id: string
  // The product group identifier.
  sku: string
  // The product display name.
  name: string
  // The full URL to the product on the website.
  url: string
  // The full URL to the product's primary image if available.
  image?: string
  // The product category name if available.
  category?: string
}

Example:

[
  {
    "id": "BFF-3",
    "sku": "BFF",
    "name": "Bali Flip Flop",
    "url": "https://store.com/products/bff",
    "image": "https://cdn.store.com/products/bff-01.jpg",
    "category": "Womens > Shoes"
  }
]

orderDetails

An object representing the transaction details of orders captured. These details are only available in for the "order" event type.

interface OrderDetails {
  // The unique order identifier as provided by your integration.
  id: string
  // A currency value representing the total gross amount
  // of all items in the cart.
  gross: number
  // A currency value representing the total discount applied to the cart.
  discount: number
  // Any discount code applied. If there are multiple codes, they will be separated
  // with a comma.
  discountCode?: string
  // A currency value representing the cost of shipping.
  shipping: number
  // A currency value representing any taxes.
  tax: number
  // Represents the ISO 4217 currency code for all currency values.
  currencyCode: string
  // An array of products included in the order.
  products: OrderProduct[]
}

interface OrderProduct {
  // The product variant identifier.
  id: string
  // The product group identifier.
  sku: string
  // The product display name.
  name: string
  // The full URL to the product on the website.
  url: string
  // The full URL to the product's primary image if available.
  image?: string
  // The quantity of the product included in the order.
  quantity: number
  // The product category name if available.
  category?: string
}

Example:

{
  "id": "34783495",
  "gross": 120.00,
  "discount": 10,
  "discountCode": "10OFF",
  "shipping": 0,
  "tax": 0,
  "currencyCode": "USD",
  "products": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "quantity": 2,
      "category": "Accessories"
    }
  ]
}

Example payloads

Add contact event

Below is an example of the payload structure which represents a user's email address being captured.:

  • The action property is set to addContact to represent a new email being captured.

  • The subscriberKey is equal to the email address captured.

  • Additional data such as any products viewed during the user's browsing session will may also be present.

{
  "version": "2022-01-01",
  "eventType": "addContact",
  "sessionKey": "02941605ef4048c832f272b13b1a2d4e",
  "domain": "store.com",
  "subscriberKey": "email@domain.com",
  "date": "2022-01-01T00:00:00Z",
  "productsViewed": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "category": "Accessories"
    }
  ]
}

Abandoned session event

An example of the session abandon event where the user has no products added to the shopping cart at the end of the session.

{
  "version": "2022-01-01",
  "eventType": "abandonedSession",
  "sessionKey": "02941605ef4048c832f272b13b1a2d4e",
  "domain": "store.com",
  "date": "2022-01-01T00:00:00Z",
  "productsViewed": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "category": "Accessories"
    }
  ]
}

Abandoned cart event

{
  "version": "2022-01-01",
  "eventType": "abandonedCart",
  "sessionKey": "02941605ef4048c832f272b13b1a2d4e",
  "domain": "store.com",
  "date": "2022-01-01T00:00:00Z",
  "productsViewed": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "category": "Accessories"
    }
  ],
  "abandonedCart": {
    "gross": 120.00,
    "discount": 10,
    "discountCode": "10OFF",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "RDB1-A2",
        "sku": "RDB1",
        "name": "Rifiano Duffel Bag",
        "url": "https://store.com/products/rdb1",
        "image": "https://cdn.store.com/products/rdb1-01.jpg",
        "quantity": 2,
        "category": "Accessories"
      }
    ]
  }
}

Order event

An example of an order event which is triggered via the "Order Received" stream trigger.

{
  "version": "2022-01-01",
  "eventType": "order",
  "sessionKey": "02941605ef4048c832f272b13b1a2d4e",
  "domain": "store.com",
  "date": "2022-01-01T00:00:00Z",
  "productsViewed": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "category": "Accessories"
    }
  ],
  "order": {
    "id": "234897349",
    "gross": 120.00,
    "discount": 10,
    "discountCode": "10OFF",
    "currencyCode": "USD",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "RDB1-A2",
        "sku": "RDB1",
        "name": "Rifiano Duffel Bag",
        "url": "https://store.com/products/rdb1",
        "image": "https://cdn.store.com/products/rdb1-01.jpg",
        "quantity": 2,
        "category": "Accessories"
      }
    ]
  }
}
PreviousMailup

Last updated