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.

Load Tracking Widget code:

<script src="https://cdn.ingrid.com/delivery-tracking/bootstrap.js"></script>

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.

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>",
});

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:

containerId: HTML id of the container to inject the Tracking Widget into
siteId: Id of the site (use IMP to get your siteId)

Optional properties are:

locale: Adjusts the language - by default, the Tracking Widget will use en-US. See Supported Languages.
prefillIdentifier: either tracking number for parcel or external id for order. Used to prefill the form
prefillContact: An email address used to prefill the form
consent: An array of consent types collected from the user for third‑party use. Currently, we support only ['statistical'], which gathers usage data to help us improve the widget.

Private mode

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

containerId: HTML id of the container to inject the Tracking Widget into
siteId: Id of the site (use IMP to get your siteId)
identifier: either tracking number for parcel or external id for order
contact: a customer email

Optional properties are:

locale: Adjusts the language - by default, the Tracking Widget will use en-US. See Supported Languages.
consent: An array of consent types collected from the user for third‑party use. Currently, we support only ['statistical'], which gathers usage data to help us improve the widget.

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,
});

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:

event_type - currently only mode_change is supported
containerId - HTML id of Tracking Widget container (the same you use to embed Tracking Widget)
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: Wed, Oct 29, 06:15 AM

Embedding Delivery Tracking Widget

IngridDeliveryTrackingWidgetApi

Search mode

Private mode

Passing arguments to IngridDeliveryTrackingWidgetApi

Listening to events emitted by Tracking Widget

Integration Example