Documentation

Multiple widgets

Outline

This document explains how to load multiple widgets on a single checkout page. It covers only details relevant to the users of this feature.

Step 1: session.create or session.get

Create one session per every widget using snippet_configuration top-level field of session.create payload:

  "snippet_configuration": {
"container_id": "string",
"object_id": "string"
}

container_id - HTML element ID assigned to widget's container element. Default value is shipwallet-container . It can be used to add CSS to widget's container.

object_id - ID of the widget instance, used to differentiate between widgets simultaneously loaded in the user's browser. If widget's API (i.e. suspend and resume methods) are used, object_id is used to specify target widget. Default value is _sw.

Duplicate ids

Make sure to choose unique container_id for each widget, it is required for widgets to work properly. If you are using shipwallet-container id on any element on your page, then pass custom container_id in snippet configuration to prevent id collision.

Request

POST /v1/siw/session.create HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
"purchase_country": "SE",
"purchase_currency": "SEK",
"locales": [
"sv-SE"
],
"search_address": {
"postal_code": "11239",
"country": "SE"
},
"cart": {
"total_value": 129900,
"currency": "SEK",
"items": [
{
"sku": "SKU12345",
"name": "Saucony Shadow 6000",
"quantity": 1,
"attributes": [
"shoes",
"indigo",
"class_one"
]
}
]
},
"snippet_configuration": {
"container_id": "widget-container-1",
"object_id": "widget_1",
}
}

Uniqueness of object_id and container_id

object_id does not have to be globally unique. object_id must only be unique in browser context of a given user. Example: user A goes to checkout with two orders from different vendors in his cart, so they get to see two widgets, one is widget_1, the other is widget_2 . The second one can have any object_id other than widget_1 . User B (different machine and browser context) goes to checkout and also has two widgets, widget_1 and widget_2.

container_id is an HTML element ID and therefore there cannot be two same IDs in one HTML page, otherwise it's not valid HTML.

session.get

session.get does not accept snippet_configuration, instead session remembers the configuration it has been created with and session.get will return html_snippet with previous object_id and container_id.

However, it is not straightforward to extract container_id and object_id from html_snippet. Instead, snippet_configuration should be saved and kept track of, just like session_id. For example, if session_id is kept in cart object, then snippet_configuration can also be kept there.

Step 2: embed html_snippets to render multiple widgets

Rendering one or more widgets works the same way. Embed html_snippets returned from session.create or session.get in your checkout page.

The snippet_configuration is reflected in the html_snippet:

<div id="{% container_id %}">
<script>
(function(window, objectId, containerId, document) {
...
})(window, {% object_id %}, {% container_id %}, document);
</script>
</div>

Step 3: (optional) suspend/resume

Each widget instance gets its own global variable in the browser's context named after its object_id . For object_id == "widget_1" , the variable will be named widget_1 and thus will be accessible as window.widget_1 or window["widget_1"] . So call to suspend would look like this:

window["widget_1"]((api) => api.suspend());

Last updated: Thu, Jun 30, 06:15 AM