# Integration Guide

# Authentication and authorization

In order to load the widget with a certain resource, i.e. a tracking number or external ID you will need an auth token. This token authenticates the widget and authorizes its access to the resource

To get your token send POST request to service-tokenauth (endpoint: https://api.ingrid.com/v1/tokenauth/token.ensure) with following headers:

  • Bearer ${TOKEN} where TOKEN is base64 encoded site private key
  • x-site-id ${SITE_ID} where SITE_ID is site id of given site

and body: { "site_id": ${SITE_ID}, "resource": ${RESOURCE} } where:

  • SITE_ID is id of given site
  • RESOURCE is resource to generate token - (trackingNumber / external ID)

In response you get:

{ "token": ${AUTH_TOKEN}}

Use AUTH_TOKEN inside widget when adding the widget.

# Adding the widget

Flow for the merchant:

  • Inject our tracking widget JavaScript code from respective CDN:
Environment Link
development https://cdn-development.ingrid.com/IngridTrackingWidget.js.gz(opens new window)
stage https://cdn-stage.ingrid.com/IngridTrackingWidget.js.gz(opens new window)
production https://cdn.ingrid.com/IngridTrackingWidget.js.gz(opens new window)
  • Select which element of the page should be the widget container and give it a unique id. For example: <div id="trackingWidget"></div>

  • Initialize tracking widget using JavaScript:

window.IngridTrackingWidget.config({
  elementId: string,
  trackingNumber: string,
  externalId: string
  siteId: string,
  locale: string,
  authToken: string,
  methodRef: string,
  features: {}
});
  • config function expects an object with 4 required properties:

    • elementId: HTML ID of the container to inject the tracking widget into

    • siteId: Id of the site

    • authToken: Authorization token from https://api.ingrid.com/v1/tokenauth/token.ensure

      Resource: either trackingNumber or externalId. Passing both of them at the same time will result in an error

    • trackingNumber: The number that we will fetch the tracking events for

    • externalId: The ID of the order provided by the merchant

  • Optional properties for config are:

    • methodRef: Shipping method reference that allows the tracking widget to show external tracking link in case of unsupported tracking-number
    • features: object that contains feature flags for widget:
      • statusBasedHeader: enables status based header
    • locale: Adjusts the language - by default the widget will use en-US. Other options are:
      • sv-SE
      • en-US
      • en-GB
      • fr-FR
  • After calling the config() function the widget should appear in the specified container

Last Updated: 12/2/2020, 3:19:01 PM