# 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.

# 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: 11/23/2021, 9:15:27 AM