How to raise events

$TB.hooks.fireEvent can be called to allow Fresh Relevance to know that an event has occurred on your website, such as a product browse or cart update. You can pass data along to Fresh Relevance, like the product information for a product browse event or the contents of a cart for a cart update event.

Expected parameters

eventName:string

The name of the event that has occurred.

For a list of available events see $TB.hooks.validCallEvents().

data:object

An object containing the data for the event raised. This could be product information, user details, or a cart.

See the events section below for more information.

options:object

An object containing any additional parameters for the event. Additional parameters are listed under each event below.

List what events can be raised

$TB.hooks.validCallEvents returns a list of valid event names that can be raised using $TB.hooks.fireEvent.

Example

Call $TB.hooks.validCallEvents();

[
  "pageChange",
  "productBrowse",
  "productList",
  "cartUpdate",
  "checkout",
  "purchaseComplete",
  "productVariantSelected",
  "userLoggedIn"
]

Raisable events

Detailed below is a list of each event and the data structure they expect to receive.

🚧
Your implementation may vary. If so, contact customer support and detail your expected data structure so that we can accommodate these changes.

pageChange

The pageChange event can be called to notify that the web page is ready for evaluation. Custom code can be developed to analyse your webpage and extract relevant data such as product information.

Data

Not applicable.

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

Call $TB.hooks.fireEvent("pageChange", null, {"sendBeacon": true});

productBrowse

The productBrowse event should be raised when your customer navigates to a product detail page.

Data

Details of the viewed product.

{
  "url": "http://www.example.com/example_product",
  "name": "Example Product",
  "image": "http://www.example.com/example_product.jpg",
  "thumbnail": "http://www.example.com/example_product_tn.jpg",
  "description": "Example Product Description",
  "variants": [
    {
      "url": "http://www.example.com/example_product_blue",
      "name": "Example Product Blue",
      "id": "example_product_blue",
      "stock": 1,
      "image": "http://www.example.com/example_product_blue.jpg"
    },
    {
      "url": "http://www.example.com/example_product_red",
      "name": "Example Product Red",
      "id": "example_product_red",
      "stock": 1,
      "image": "http://www.example.com/example_product_red.jpg"
    }
  ],
  "id": "example_product",
  "sku": "example_product_01",
  "price": 100.00,
  "sale_price": 89.99,
  "categories": [
    "example products",
    "on sale"
  ],
  "extra_data": {
    "example_data": "example extra data",
    "author": "John Doe",
    "style": "polo",
    "color": "red"
  },
  "language": "ENG",
  "brand": "brand",
  "currency": "GBP",
  "stock": 5
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "productBrowse",
    {
        "url" "http://www.example.com/example_product"
        ...
    },
    {
        sendBeacon: true
    }
)

productList

The productList event should be raised when your customer navigates to a product list page. For example, a category page or department page.

Data

An array of products viewed:

[
  {
    "url": "http://www.example.com/example_product",
    "name": "Example Product",
    "image": "http://www.example.com/example_product.jpg",
    "thumbnail": "http://www.example.com/example_product_tn.jpg",
    "description": "Example Product Description",
    "variants": [
      {
        "url": "http://www.example.com/example_product_blue",
        "name": "Example Product Blue",
        "id": "example_product_blue",
        "stock": 1,
        "image": "http://www.example.com/example_product_blue.jpg"
      },
      {
        "url": "http://www.example.com/example_product_red",
        "name": "Example Product Red",
        "id": "example_product_red",
        "stock": 1,
        "image": "http://www.example.com/example_product_red.jpg"
      }
    ],
    "id": "example_product",
    "sku": "example_product_01",
    "price": 100.00,
    "sale_price": 89.99,
    "categories": [
      "example products",
      "on sale"
    ],
    "extra_data": {
      "example_data": "example extra data",
      "author": "John Doe",
      "style": "polo",
      "color": "red"
    },
    "language": "ENG",
    "brand": "brand",
    "currency": "GBP",
    "stock": 5
  },
  {...}
]

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "productList",
    [
        {
            "url" "http://www.example.com/example_product"
            ...
        },
        {...},
    ],
    {
        sendBeacon: true
    }
)

cartUpdate

The cartUpdate event should be raised when your customer interacts with their cart. For example, adding or removing an item, modifying the quantity of an item, or applying a discount code to the cart.

Data

The current cart state.

{
  "cart_value": 89.99,
  "cart_quantity": 1,
  "cart_currency": "GBP",
  "extra_data": {
    "example": "extra_data"
  },
  "products": [
    {
      "url": "http://www.example.com/example_product",
      "name": "Example Product",
      "image": "http://www.example.com/example_product.jpg",
      "thumbnail": "http://www.example.com/example_product_tn.jpg",
      "description": "Example Product Description",
      "variants": [
        {
          "url": "http://www.example.com/example_product_blue",
          "name": "Example Product Blue",
          "id": "example_product_blue",
          "stock": 1,
          "image": "http://www.example.com/example_product_blue.jpg"
        },
        {
          "url": "http://www.example.com/example_product_red",
          "name": "Example Product Red",
          "id": "example_product_red",
          "stock": 1,
          "image": "http://www.example.com/example_product_red.jpg"
        }
      ],
      "id": "example_product",
      "sku": "example_product_01",
      "price": 100.00,
      "sale_price": 89.99,
      "categories": [
        "example products",
        "on sale"
      ],
      "extra_data": {
        "example_data": "example extra data",
        "author": "John Doe",
        "style": "polo",
        "color": "red"
      },
      "language": "ENG",
      "brand": "brand",
      "currency": "GBP",
      "stock": 5
    },
    {...}
  ]
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

inPage

Type: boolean

Default: false

If the cart being captured is from an in-page or mini cart then the inPage flag can be used to indicate this.

📘
If this flag is not set the system identifies the page as a cart page.

Example

$TB.hooks.fireEvent(
    "cartUpdate",
    {
        cart_value: 89.99,
        cart_quantity: 1,
        cart_currency: "GBP",
        extra_data: {
            "example": "extra_data"
        },
        products: [
            {...}
        ]
    },
    {
        "sendBeacon": true,
        inPage: false
    }
)

checkout

The checkout event should be raised when your customer customer navigates to a checkout page.

Data

The current cart state.

{
  "cart_value": 89.99,
  "cart_quantity": 1,
  "cart_currency": "GBP",
  "extra_data": {
    "example": "extra_data"
  },
  "products": [
    {
      "url": "http://www.example.com/example_product",
      "name": "Example Product",
      "image": "http://www.example.com/example_product.jpg",
      "thumbnail": "http://www.example.com/example_product_tn.jpg",
      "description": "Example Product Description",
      "variants": [
        {
          "url": "http://www.example.com/example_product_blue",
          "name": "Example Product Blue",
          "id": "example_product_blue",
          "stock": 1,
          "image": "http://www.example.com/example_product_blue.jpg"
        },
        {
          "url": "http://www.example.com/example_product_red",
          "name": "Example Product Red",
          "id": "example_product_red",
          "stock": 1,
          "image": "http://www.example.com/example_product_red.jpg"
        }
      ],
      "id": "example_product",
      "sku": "example_product_01",
      "price": 100.00,
      "sale_price": 89.99,
      "categories": [
        "example products",
        "on sale"
      ],
      "extra_data": {
        "example_data": "example extra data",
        "author": "John Doe",
        "style": "polo",
        "color": "red"
      },
      "language": "ENG",
      "brand": "brand",
      "currency": "GBP",
      "stock": 5
    },
    {...}
  ]
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "checkout",
    {
        cart_value: 89.99,
        cart_quantity: 1,
        cart_currency: "GBP",
        extra_data: {
            "example": "extra_data"
        },
        products: [
            {...}
        ]
    },
    {
        sendBeacon: true,
        inPage: false
    }
)

purchaseComplete

The purchaseComplete event should be raised when your customer completes purchase of a cart.

Data

The order number.

{
	"orderNumber": "1234567"
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "purchaseComplete",
    {
        orderNumber: "1234567",
    },
    {
        sendBeacon: true
    }
)

productVariantSelected

The productVariantSelected event should be raised when your customer selects a product variant on a product browse page or similar.

Data

The product variant details:

{
  "url": "http://www.example.com/example_product_orange",
  "name": "Orange Example Product",
  "vid": "orange",
  "stock": 1,
  "image": "http://www.example.com/example_product_orange.jpg",
  "parent_prid": "product0"
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "productVariantSelected",
    {
        url: "http://www.example.com/example_product_orange",
        name: "Orange Example Product",
        vid: "orange",
        stock: 1,
        image: "http://www.example.com/example_product_orange.jpg"
    },
    {
        sendBeacon: true
    }
)

userLoggedIn

The userLoggedIn event should be raised when your customer logs in or signs up.

Data

The logged in user details:

{
  "email": "jane_doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe"
}

Options

sendBeacon

Type: boolean

Default: true

The sendBeacon flag indicates whether you want the data recorded to be sent back to Fresh Relevance for processing.

Example

$TB.hooks.fireEvent(
    "userLoggedIn",
    {
        email: "jane_doe@example.com",
        firstName: "Jane",
        lastName: "Doe"
    },
    {
        sendBeacon: true
    }
)