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>

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

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

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

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 property is:

• locale: Adjusts the language - by default, the Tracking Widget will use en-US. See Supported Languages.

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