# Integration Guide

Ingrid provides a upsellWidgetBootstrap.js file stage (opens new window) production (opens new window) that on load exposes methods on the window object that can be used to show the Upsell Widget and allow back and forth communication.

Using addListener you can register callbacks that will be called when Upsell Widget emits events like for example free_shipping_reached.

After you subscribe to events with your callbacks, you can use render method to render an iframe with the widget in a specified container. Along with that channels of communications are set up, allowing to send an updated cart value whenever user adds more to the cart or removes items from the cart, using updateCart method.

After updateCart method is used and cart value is eligible for free shipping, then widget will emit free_shipping_reached event and invoke your callbacks.

Integration steps:

  • Embed bootstrap script from our CDN stage (opens new window) production (opens new window).
  • Subscribe to Events (ready or free_shipping_reached ) by calling window._ingridUpsellWidgetApi.addListener.
  • Call window._ingridUpsellWidgetApi.render to initialize and show Upsell Widget.

# API overview

Note: all the model definitions like for example CartState, can be found on the bottom of the page.

window._ingridUpsellWidgetApi exposes these methods:

  • render(id, config) - used to initialize upsell widget. After calling it, iframe with Upsell Widget will be injected into the element with matching id.

  • updateCart(config) - used whenever the value of the cart has hanged, it will make widget call Ingrid servers to check if the new cart value offers free shipping and update its UI accordingly.

  • addListener(event, listener) - available events: ready, free_shipping_reached.

# Authorization

During the integration, you should post an inquiry for an authorization token to Ingrid's Customer Success. Ingrid will get back to you with the authorization token structured the following way:

ingrid-http-auth-token:********-****-****-****-************

You have to specify the token in the field auth_token in the config used by the render method.

# Events Overview

  • ready - emitted when widget rendered itself and fetched configuration from Ingrid servers.
  • free_shipping_reached - emitted when the cart value is eligible for free shipping.

# Models & Types Reference

Config:

{
  "auth_token": string
  "cart": CartState
  "locales": []string
  "country": string
}

CartState:

{
  "currency": string,
  "attributes": string[]
  "items": CartItem[],
  "total_value": number,
}

CartItem:

{
  "attributes": string[],
  "name": string,
  "price": number,
  "quantity": number,
  "sku": string
}
Last Updated: 11/23/2021, 9:15:27 AM