Display tracking information on your website

To make it easy for you to help your customers track their shipments, we have created a widget that you can embed on your website.

The widget is currently in beta and may be subject to changes in the future.

Implementation
1. Add the helper script to your website
To use the widget, you need to add the following script to your website.
This script will handle the communication between the widget and your website.
<script src="https://tracking-widget.skrym.com/client-script.js" defer></script>

2. Get the URL for the widget
The widget is meant to be implemented as an iframe on your website.
To get the URL to use for the iframe, you will first need to make a request to the following API.


You need to be  with your API key to use this endpoint. To avoid exposing your API key to the public, please ensure that you make this request from your backend and not the client's browser.

This URL will include the necessary authentication to display the tracking information in the widget.
The authenticated session is valid for 24 hours, after which a new widget URL is needed.
3. Embed the widget on your website
Once you have the URL, you can embed the widget on your website using an iframe.
<iframe src="URL_FROM_API" id="skrym-tracking-widget"></iframe>

With the script added above, the iframe will be automatically resized to fit the content of the widget.
All you need to do is to set the width as you desire, and the height will be adjusted dynamically.

By default, an iframe has a border around it. This can easily be removed by setting the CSS property `border` to `none`.
If you still want a border on the iframe, you can style it as you like using CSS. However, please ensure that the box-sizing CSS property is set to content-box, as it might otherwise break the auto-height functionality of the widget.

Configuration
To get the widget to look and work as you want it, there are a few configuration options available.
To learn more, see the .

Widget

Get the widget to look and work as you want It

To make the widget look and work as you want it, there are a few configuration options available.
Colors
Currently, Skrym allows you to set the primary and secondary colors of the widget.
This is done by going into the  and setting the colors there.

We are working on improving the customization options for the widget to allow for more advanced customization.

Dark mode
There are two ways to decide what theme to use on the widget. You can either set it in the URL or call the setTheme function from the helper script.
The widget supports three themes: light, dark and system.
The system theme will use the user's  option to decide which theme to use.
Via API
When fetching the widget URL, you can specify the theme. If not specified, the default theme is system.

Via helper script
You can also set the theme client-side by calling the setTheme function, available via the helper script.
Similar to the API, you can set the theme to light, dark or system.
Example usage:
SkrymTrackingWidget.setTheme('dark');

Language
The widget supports multiple languages.
Similar to the theme, you can set the language in the URL or call the setLanguage function from the helper script.
Via API
When fetching the widget URL, you can specify the language.
If not specified, the widget will check for a user's preferred language or default to english.

Via helper script
You can also set the theme client-side by calling the setLanguage function, available via the helper script.
Similar to the API, you can set the language to en, sv, no or fi.
Example usage:
SkrymTrackingWidget.setLanguage('sv');


Configuration

Learn how the tracking widget works and how to develop it

Since the widget needs to run on our customer's website and not directly in the browser, it's a bit trickier to set it up.
For this, there are four parts that need to work together:

The customer's website

The customer needs to embed the widget and the helper script on their website
See installation guide for more information


The widget itself

Nextjs application hosted on Vercel
Responsible for displaying the tracking information


Our backend

Responsible for generating the widget URL
Provides data to the widget


Helper script on the customer's website

Responsible for communication between the widget and the customer's website
Handles the dynamic height resizing of the iframe
Can be used for more features in the future, such as letting the customer's website listen for events from the widget



Authentication
To get the widget URL, the customer needs to be authenticated with their API key as the would be for any other API call. Note that it's important that the customer does not make the fetch from the browser with their API key since it will expose their API key. They should make it from their backend and then pass the URL to the frontend.
The widget URL itself is authenticated with a JWT token that is included as a search parameter in the URL. This token is valid for 24 hours, after which a new widget URL is needed. The widget can then read this token and use it to authenticate with our backend to get the tracking information.
Since this token is exposed, we've also setup a secret that the widget and the backend share. When using the widget token, the backend will verify that the token is valid and that the secret is correct. This way, the backend knows that the request comes from the widget and who the customer is. Note that this limits us to only doing server-side api calls from the widget.
Widget to Website communication
By design, iframes are meant to be rendered independently of the parent website. However, we can use the  to send information between the widget and the customer's website.
This is for example done to get around the limitation that the widget can't control the size of the iframe. With regular intervals, the widget gets the height of the body, and sends it to the customer's website. The customer's website then sets the height of the iframe to the height of the body.
To avoid having the customer implement this themselves, we provide a helper script that the customer can include on their website. This script is compiled just before the widget is and is then hosted using .
Developing and testing the widget locally
Widget
Since it's just a Nextjs application you can run it locally with pnpm dev as normal and then access it on http://localhost:3002. To get a url (including token), you can use the GetWidgetURL endpoint in the backend.
To test how it would look in a real iframe, you can use the helper-page /iframe-test which will show the widget in an iframe. This page also includes the helper script, so you can test that out as well.
Helper script
Normally, Nextjs does a lot of the heavy lifting when it comes to compilation, bundling, optimization, file serving, reloading etc. However, since the helper script is not part of the Nextjs application, we need to do this ourselves.
Currently, we use  to take care of this. To compile the script, run pnpm run compile-script, and to automatically build when something changes, run pnpm run compile-script:watch. Note that hot reloading is not supported for external script like this in Nextjs, meaning that you will have to reload the page manually.