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
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.
interfaceCustomData { [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.
interfaceCartDetails {// 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[]}interfaceCartProduct {// 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}
An array of objects representing the details of products which where viewed during the session.
Type: ViewedProduct[]
interfaceViewedProduct {// 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}
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).
interfaceRelatedProduct {// 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}
An object representing the transaction details of orders captured. These details are only available in for the "order" event type.
interfaceOrderDetails {// 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[]}interfaceOrderProduct {// 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}
