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.

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());