Documentation

Tracking Widget Integration

The Tracking Widget should be integrated into a website owned and managed by the Merchant. The most common approach involves creating a dedicated Tracking Page within the Merchant's domain specifically designed to accommodate the Tracking Widget. The End Customer can then be provided with a link to said Tracking Page, which includes the embedded Tracking Widget.

Embedding Delivery Tracking Widget

  1. Load Tracking Widget code:
<script src="https://cdn.ingrid.com/delivery-tracking/bootstrap.js"></script>
  1. Select which element of the page should be the Tracking Widget container and give it a unique id. For example:
<div id="delivery-tracking-widget"></div>
Widget dimentions

The Delivery Tracking Widget has a minimum width of 320px to guarantee readability. It lacks a maximum width, allowing it to stretch and fill its container entirely. The widget's height adjusts dynamically based on its content.

Widget modes

There are two ways to initialize the Tracking Widget: search mode and private mode. Search mode is used to display a search form where the end user can look up their package. Private mode displays full information about the given package.

  1. After the script is loaded, initialize the Tracking Widget using JavaScript.

    To initialize search mode use the renderSearchMode method:

    window.IngridDeliveryTrackingWidgetApi.renderSearchMode({
      containerId: "delivery-tracking-widget",
      locale: "<LOCALE>",
      siteId: "<YOUR_SITE_ID_FROM_IMP>",
    });

    To render in private mode, use the renderPrivateMode method:

    window.IngridDeliveryTrackingWidgetApi.renderPrivateMode({
      containerId: "delivery-tracking-widget",
      locale: "<LOCALE>",
      siteId: "<YOUR_SITE_ID_FROM_IMP>",
      identifier: "<IDENTIFIER>",
      contact: "<EMAIL>",
    });

  2. Following a method call to render mode, the Tracking Widget should appear on the page.

IngridDeliveryTrackingWidgetApi

Search mode

IngridDeliveryTrackingWidgetApi.renderSearchMode function expects as argument an options object with 2 required properties:

Optional properties are:

Private mode

IngridDeliveryTrackingWidgetApi.renderPrivateMode function expects as argument an options object with 4 required properties:

Optional property is:

Passing arguments to IngridDeliveryTrackingWidgetApi

It is up to you how you pass arguments to IngridDeliveryTrackingWidgetApi, but we recommend that you take identifier and contact from query parameters.

For example, the link to your site can look like this:

https://tracking/?identifier=<TRACKING_NUMBER>&contact=<CONTACT>

Then you can extract identifier and contact from query paramaters. Example in Search mode:

const params = new URLSearchParams(window.location.search);
const identifier = params.get("identifier");
const contact = params.get("contact");

window.IngridDeliveryTrackingWidgetApi.renderSearchMode({
  containerId: "delivery-tracking-widget",
  siteId: "<YOUR_SITE_ID_FROM_IMP>",
  locale: "<LOCALE>",
  prefillIdentifier: identifier,
  prefillContact: contact,
});

Example in Private mode:

const params = new URLSearchParams(window.location.search);
const identifier = params.get("identifier");
const contact = params.get("contact");

// or for private mode
window.IngridDeliveryTrackingWidgetApi.renderPrivateMode({
  containerId: "delivery-tracking-widget",
  siteId: "<YOUR_SITE_ID_FROM_IMP>",
  locale: "<LOCALE>",
  identifier,
  contact,
});

Listening to events emitted by Tracking Widget

Currently we provide a mode_change event when the user switches from search mode to private mode and vice versa. You can use following snippet to listen to mode_change:

window.IngridDeliveryTrackingWidgetApi.on("mode_changed", containerId, (event) => {
  console.log(`Mode changed for ${containerId} with event:`, event);
});

The on function takes 3 arguments:

  1. event_type - currently only mode_change is supported
  2. containerId - HTML id of Tracking Widget container (the same you use to embed Tracking Widget)
  3. event handler - function with one argument of {to: 'search|private'} object that indicates to what Tracking Widget mode user switched

Integration Example

Tracking Widget Integration Example

Last updated: Fri, Dec 20, 06:15 AM