Integration Guide
Ingrid provides a upsellWidgetBootstrap.js
file stage production 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 production.
- Subscribe to Events (
ready
orfree_shipping_reached
) bycalling 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 matchingid
. -
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
}