Manual
Contents
Tracking

The Arta Tracking widget

The Arta Tracking widget is a mobile-friendly javascript package that enables you to present real-time shipping status updates on your site.

It is easy to setup–the only requirements are a publishable API key, an Arta shipment ID, and your own website.

Arta Tracking

Features

Built on top of Arta’s open source TypeScript client SDK, arta-browser, the Tracking widget’s pre-built user interface can be extensively customized. You just provide a shipment ID and a few optional configurations and the arta-browser SDK will do the rest.

From there, your buyers can quickly view the shipment’s details without leaving your site.

  • Quick Setup – Install in your apps with just a few lines of JavaScript using the arta-browser SDK
  • Complete view of the shipment – Presents a complete picture of the shipment lifecycle from pickup to delivery; status history, tracking numbers for multiple packages, any exceptions, and delivery estimates
  • Works across devices – Features a mobile-responsive design that works well across a variety of viewports
  • Configurable –
    • Use custom colors and fonts to match your brand
    • Customize all text served to your customers
    • Control where the widget opens on the screen

Getting started

1. Create a publishable API Key

arta-browser requires a publishable API Key token to run on your site.

Arta API Keys are either publishable or private. Private API keys have access to the full breadth of the Arta API and must be kept secret and used exclusively with server-to-server API calls. Publishable API keys have access to a limited set of API endpoints and are safe to include in your front-end client applications.

You may manage API keys with the Arta dashboard or through the API itself. For our walk through, we’ll create the publishable key via the API.

Using a private key associated with your organization, perform an API call to “the Create an API Key” endpoint to generate a publishable API key for your organization.

curl \
 -X POST https://api.arta.io/api_keys \
 -H "Content-Type: application/json" \
 -H "Authorization: Arta_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"api_key":{"is_public":true}}'

This will create a new, publishable API key and return the token to be used in configuring the arta-browser SDK.

Note that you can optionally also generate publishable test mode API keys and use those with the Tracking widget. When using a test-mode API key token, only test-mode shipments can be presented in the widget.

2. Install arta-browser on your site

The Tracking widget is powered by a JavaScript/TypeScript SDK called arta-browser.

You can install arta-browser with a <script> tag using a free CDN network or as a package through npm.

Installing with a <script> tag

arta-browser is distributed via the jsDelivr Content Delivery Network (CDN). To install arta-browser via the CDN, copy and paste the following snippet before the closing </body> HTML tag wherever you want the Tracking widget available for your users (typically on an order confirmation page):

<script src="https://cdn.jsdelivr.net/npm/@artaio/arta-browser@latest/dist/bundle.js"></script>

And once the above script is loaded the Arta object should be available and you can proceed to “Basic usage” below.

Installing with as a package via npm

Alternatively you install the @artaio/arta-browser package in your JavaScript and TypeScript applications using the npm package manager.

In your project, install the package with

npm install @artaio/arta-browser

And you can then import the Arta object in your project’s files

import Arta from "@artaio/arta-browser";

Basic usage

Once arta-browser is installed, you’ll need to configure the library with the API key you generated in step 1 above.

For example, if you have used the npm distribution strategy above,

Arta.init("<YOUR_API_KEY>");

Then, we’ll initialize an instance of the Tracking widget using the tracking function with a shipment ID from your Arta account.

const tracking = Arta.tracking('<SHIPMENT_ID>');

The first argument to the tracking function may be either a single shipment ID or a list of shipment IDs. If the Tracking widget is initialized with more than one shipment, the widget will provide a summary of each shipment and a link to view the full details.

The tracking function can optionally receive a second argument with additional configuration settings, but we’ll skip that for now.

The next step is to validate the Tracking instance we’ve just configured. The validate function is required and checks your publishable API key, shipment ID, and any options for correctness

A promise is returned and, upon successful validation, your user interface can be updated (for example, to show or enable an “Track” button). Lets use this isReady attribute on the tracking instance to determine whether or not to display a button that triggers the opening of the Arta Tracking widget.

await tracking.validate();

// tracking.open() will render the widget
tracking.isReady && <Button onClick={() => tracking.open()}>Track</button>

Calling the open function in the example above will render the widget on the page.

Clicking the close button on the Arta Tracking interface will automatically close the widget, but you may also close it programatically using the close function.

tracking.close();

Configuration options

The Arta Tracking widget provides a broad set of possible configurations. You can customize the colors, position, animations, all text, the drawer’s width, and more.

The tracking function receives two potential arguments. The first argument is the ID of the Arta shipment for which you are building the widget. The second argument defines optional settings related to the presentation and text of the widget itself.

For reference, you can find the full list of configuration types and their accepted values in in the SDK’s tracking types files.

Here are some of the most common configuration options:

Within the style namespace:

  • color – an object defining the color of elements on Tracking widget; this includes various states of backgrounds, borders, buttons, and text
  • fontFamily – defines the font family to be used in rendering the text in the drawer window
  • position – defines the placement on the page for the drawer window to be rendered on the page; accepts: “right” (default), “left”
  • variant – defines the width and format of the drawer window; accepts: “default” or “minimal” (a more narrow presentation)

Within the text namespace:

  • header.title – defines the title presented in the drawer’s header; defaults to Track Shipment
  • dates – an object defining the labels used for days and months in the widget; useful for localization

Within the navigation namespace:

  • shipmentExceptionMailTo – defines the email address to use as a contact link if there is an exception with the shipment

Customized Example

Here’s a full example highlighting some of the optional settings. It specifies that the widget will slide in and out. Additionally, it overrides the icon and text colors. Lastly, the configuration below sets the header title to “Shipping Status”.

import Arta from '@artaio/arta-browser';

Arta.init('<YOUR_API_KEY>');

const settings = {
  animation: {
    in: {
      type: "slide",
      duration: 500,
      easing: "ease-in-out",
    },
    out: {
      type: "slide",
      duration: 250,
      easing: "ease-in-out",
    },
  },
  style: {
    color: {
      textPrimary: "#000",
      iconPrimary: "blue",
      iconSecondary: "white",
    },
  },
  text: {
    header: {
      title: "Shipping Status",
    },
  },
};

const tracking = Arta.tracking('<SHIPMENT_ID>', settings);

await tracking.validate();

tracking.isReady && <Button onClick={() => tracking.open()}>Track</button>

Multiple Shipments Example

Here’s an example demonstrating how to use the Tracking widget for multiple shipments. The example also demonstrates how to customize the text and estimated delivery date formats presented to the user on the shipment list page.

The text.dates.locale parameter supports valid Intl.Locale strings and the text.dates.formatOptions parameter supports valid Intl.DateTimeFormatOptions objects. More info

import Arta from '@artaio/arta-browser';

Arta.init('<YOUR_API_KEY>');

const settings = {
  text: {
    viewShipmentDetailLabel: "Details",
    viewShipmentsListLabel: "Back",
    dates: {
      locale: "en-US",
      formatOptions: {
        dateStyle: "long",
      },
    },
  },
};

const tracking = Arta.tracking(
  ["<SHIPMENT_ID_1>", "<SHIPMENT_ID_2>", "<SHIPMENT_ID_3>"],
  settings,
);

await tracking.validate();

tracking.isReady && <Button onClick={() => tracking.open()}>Track</button>
Next
Customs (ECD)
Previous
Track
© Arta , 2024 — Update cookie consent , Privacy , Standards , & Terms