Track Order Widget

The Track Order widget adds a Track Order button to your page, such as an order confirmation or account page. When a customer clicks it, the widget looks up the order and shows its delivery progress as a series of steps.

Prerequisites

• Your DigitalGenius widget ID.
• Your region: eu or us.
• A DigitalGenius flow that handles track order requests. The widget sends a track_order event with the order number and email address, and the flow must reply with the order's tracking status.
• Access to edit the HTML of the page the widget is displayed on.

Installation

Add the following code to your page, at the position where the widget should appear. Replace your-widget-id with your widget ID, and update env to match your region if required.

<div id="track-order"></div>

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        targetDOMNode: '#track-order',
        type: 'trackOrder',
        config: {
          orderNumber: 'HB-614357',
          email: '[email protected]',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

The widget is rendered inside the <div id="track-order"></div> container.

Configuration

The following properties are set on each entry in components.

Providing order details

The widget needs the order number and the customer's email address to look up an order. retrievalMethod controls where they come from.

Example: values in the configuration

With retrievalMethod set to 'config' (the default), orderNumber and email are the values themselves. Use this when your page template can output the order details into the script, for example on an order confirmation page:

<div id="track-order"></div>

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        targetDOMNode: '#track-order',
        type: 'trackOrder',
        config: {
          retrievalMethod: 'config',
          // replace with the order details output by your page template
          orderNumber: 'HB-614357',
          email: '[email protected]',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

Example: values read from the page

With retrievalMethod set to 'selector', orderNumber and email are CSS selectors for elements already on the page, and the widget reads the order details from them. Use this when the order details are displayed on the page but can't easily be added to the script:

<h1>Order <span id="order-number">HB-614357</span></h1>
<p id="customer-email">[email protected]</p>

<div id="track-order"></div>

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        targetDOMNode: '#track-order',
        type: 'trackOrder',
        config: {
          retrievalMethod: 'selector',
          orderNumber: '#order-number',
          email: '#customer-email',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

The values are read when the customer clicks the button, so elements rendered after the widget loads are supported. For form fields (input, select and textarea) the field's value is used; for other elements, their text content is used, with surrounding spaces removed.

Layout

The delivery progress can be displayed in two layouts:

• horizontal (default): the steps are displayed side by side, joined by a line. This suits the main content area of a page.
• vertical: the steps are stacked, with each step's marker on the left and its label on the right, joined by a line. This suits narrow spaces, such as a sidebar, where the steps would not fit side by side.

Both layouts show the same information: a marker and label for each step.

config: {
  orderNumber: 'HB-614357',
  email: '[email protected]',
  layout: 'vertical',
},

Order statuses

orderStatuses defines the steps in the delivery progress. Each step has:

• status: the tracking status returned by your flow, for example In Transit. Matching ignores case and surrounding spaces.
• label: the text shown to the customer for that step.

Steps before the order's current status are shown as complete, the current status is highlighted, and later steps are shown as upcoming.

If orderStatuses is omitted, the following steps are used. The labels below are the British English defaults. Other locales use their own wording, which you can override with lang. See Customising text.

For example, to add an extra step and use your own wording:

orderStatuses: [
  { status: 'Order Placed', label: 'Order placed' },
  { status: 'Ready for Shipment', label: 'Order processing' },
  { status: 'Ready for Pickup', label: 'Awaiting pick-up' },
  { status: 'In Transit', label: 'Shipped' },
  { status: 'Delivered', label: 'Delivered' },
],

If the flow returns a status that isn't in orderStatuses, no step is highlighted and an error is logged to the browser console.

Behaviour

• Clicking the button: the button is replaced by a loading indicator and lang.loadingText while the order is looked up.
• Tracking found: the delivery progress is shown in place of the loading indicator.
• Tracking not found: if the order number or email is missing, sending the request fails, or no response is received within 30 seconds, the button is shown again with lang.errorText below it, so the customer can try again.

Localisation

The widget is displayed in British English by default. To change the language, set locale in your configuration:

window.DG_SDK_CONFIG = {
  locale: 'fr-FR',
  components: [
    {
      widgetId: 'your-widget-id',
      env: 'eu',
      targetDOMNode: '#track-order',
      type: 'trackOrder',
      config: {
        orderNumber: 'HB-614357',
        email: '[email protected]',
      },
    },
  ],
};

The following locales are supported: cs-CZ, da-DK, de-DE, en-GB, en-LU, en-US, es-ES, et-EE, fi-FI, fr-FR, it-IT, ja-JP, ko-KR, lt-LT, lv-LV, nl-NL, no-NO, pl-PL, pt-PT, ro-RO, sk-SK, sv-SE, zh-CN and zh-TW. Unsupported locales fall back to British English.

Customising text

The text listed below can be customised using a lang object in the app's config. Only the properties you specify are overridden; all other text uses the default wording for the selected locale.

window.DG_SDK_CONFIG = {
  components: [
    {
      widgetId: 'your-widget-id',
      env: 'eu',
      targetDOMNode: '#track-order',
      type: 'trackOrder',
      config: {
        orderNumber: 'HB-614357',
        email: '[email protected]',
        lang: {
          buttonLabel: 'Track my order',
          errorText: 'We could not find this order.',
        },
      },
    },
  ],
};

Styling

The widget renders inside a shadow DOM, so the styles on your page don't affect it directly. By default it inherits your page's font and text colour, and uses a transparent background. Sizes are set in em, so the widget scales with your font size.

To change the colours or width, use config.style:

config: {
  orderNumber: 'HB-614357',
  email: '[email protected]',
  style: {
    accentColor: '#1f9d55',
    inactiveColor: '#d4d4d4',
    maxWidth: '32rem',
  },
},

Troubleshooting

If the widget does not appear, check that:

• The <div id="track-order"></div> container is on the page and placed before the scripts.
• targetDOMNode matches the container, including the # prefix.
• type is set to 'trackOrder'.
• widgetId is correct and env matches your region.

If the error message is shown after clicking the button, check the browser console. When retrievalMethod is 'selector', an error is logged if a selector doesn't match an element on the page.