How widgets work

A widget is a small Nash component you host on your own web page — a live map, an arrival-time chip, a delivery list, a delivery-details panel — that shows your customers the live status of a delivery without sending them anywhere else. This article is about what has to be true for one to actually render, and why the setup looks the way it does: the three separate things a widget needs before it will serve, how your backend turns a long-lived secret into the short-lived session a browser can safely use, and where a widget ends and Nash's own tracking page begins. For the object itself — where the settings live, what's in the catalog — start with widgets. For the click-by-click setup, see embed a Nash widget on your site; this article is the model underneath those steps.

What a widget is

Think of a widget as a read-only window onto one delivery's live state, opened inside a page you own. Nash serves what goes in the window — the courier's position, the planned route, the arrival time, the current status — and keeps it current as the delivery moves. Your page decides where the window sits and how the surrounding page looks. Nothing in a widget changes a delivery or issues an instruction; it only displays state that already exists. The delivery it shows is being dispatched by Nash and carried out by a provider or your own fleet — the widget is the view, not the vehicle.

Because a widget is a view onto real delivery data on a public web page, Nash doesn't just hand that data to any page that asks. It serves a widget only when you've set up the pieces that prove the request is coming from a page you control. That's what the rest of this article is about.

The three pieces that gate each other

A widget serves on a page only when all three of these are true at once. Miss any one and the widget simply won't render — there's no partial state where two out of three is enough.

1. The widget is turned on. You switch it on in the catalog on the Widgets settings page. Off means Nash won't serve it anywhere, no matter how the rest is configured. See turn widgets on and off.
2. The page's exact origin is allowed. You add the exact web origin of every page that will embed a widget to the allowed-origins list. Nash serves a widget only to a page whose origin is on that list; anything else is refused. See allow the sites that can embed your widgets.
3. Your backend holds a credential. Your server holds a long-lived secret, issued from the Widgets page, that it exchanges for the session a browser needs. No credential, no session, no widget. See issue and manage embed credentials.

These three are independent switches that happen to be wired in series. Turning a widget on doesn't allow any origins; allowing an origin doesn't issue a credential; holding a credential doesn't turn anything on. You set each one separately, and the widget renders only where all three lines up on the same page.

From credential to session

The third piece — the credential — is worth understanding on its own, because it's the part that keeps live delivery data from leaking out of a public page. It works in two layers, and the split is deliberate.

The credential is a long-lived secret that lives only on your server. It never goes into page code and never reaches a browser. Its one job is to let your backend ask Nash for a session.

The embed session is what a browser actually uses. It's short-lived — it expires quickly and is meant to be re-minted, not stored — and it carries only enough to render the specific delivery in front of the customer. When a customer loads a page with a widget on it, your backend presents its long-lived credential to Nash, Nash mints a fresh short-lived session, and your page hands that session to the widget. The widget uses the session to render; the long-lived secret stays on your server the whole time.

The point of the two layers is that the thing exposed in the browser is always the disposable one. If a session is ever scraped from a page, it expires on its own and grants only that narrow view — the durable secret that could mint more sessions was never there to take. And the allowed-origins list from the previous section is checked at the moment a session is minted: Nash only mints a session for a page on an origin you've allowed, so a copied snippet dropped onto some other site can't get a session in the first place. That's why all three pieces have to agree — the origin check and the credential exchange happen together, every time a widget loads.

You don't operate any of this by hand. Turning the credential into a session is a one-time piece of backend wiring your developers set up once; after that, it runs on every page load without anyone in the portal touching it. The settings page is where you issue, rotate, and revoke the credential that wiring depends on — see issue and manage embed credentials for the lifecycle.

Which widgets you can embed today

The catalog lists several widgets, but only one is ready to drop into a page right now. Live Map is the only widget with a copy-paste embed snippet today — turn it on, allow your origin, issue a credential, and you have a working embed. ETA Chip, Delivery List, and Delivery Details can be switched on and saved, but none of them produce a snippet yet, so there's nothing to paste into a page for them — turning one on doesn't give you an embed. Nash Agent isn't embedded from this catalog at all; its embeds are set up per agent, on that agent's own Embed tab, and aren't affected by the switch here — see what Nash Agent is.

So when this article talks about a widget rendering on your page, the one you can build end-to-end today is Live Map. The three-pieces model and the credential-to-session flow are the same for every widget, but Live Map is the one that has a snippet to embed.

A widget is not the tracking page

It's easy to blur a widget together with Nash's hosted customer tracking page, because both show a customer where a delivery is. They're different surfaces, and it's worth keeping them straight.

The Live Map widget is your component, on your page, under your domain. You turn it on, allow your origins, hold the credential, and place it in your own layout — it's part of your site. Nash's customer tracking page is a page Nash hosts and serves — the link a customer opens from a tracking notification. You don't embed it; you point customers to it, and you brand it from the tracking side of the portal, not from here. See send customers a tracking link for that surface.

They can show related delivery state, but they're set up in completely different places and reached in completely different ways — one is embedded and credential-gated on your site, the other is a link Nash hosts. This article, and the Widgets page as a whole, is only about the embedded widget. Branding and setup for the tracking page live entirely under tracking, not under Widgets.

What affects this

A couple of things outside your own three switches can change whether a widget serves, and they're worth knowing about.

• Nash can temporarily pause a widget. If Nash pauses a widget for your organization, its catalog row shows a Paused by Nash badge and the widget stops serving until Nash lifts the pause. Your own On/Off setting is left untouched — a pause doesn't flip your switch, and when it's lifted the widget goes back to whatever you had it set to. You can't clear a pause yourself; the row points you to Nash support. See turn widgets on and off for what the paused state looks like.
• Whether a widget is available to your organization can depend on your setup. The Widgets page itself opens for people with organization-management permissions — that's who can see and edit it. If a specific widget doesn't appear for you, reach out to Nash.

And the honest bottom line under all of it: a widget shows delivery state — it doesn't perform the delivery. Nash dispatches the order, a provider or your own fleet carries it out, and the widget is the live view of that in progress on your own page. If a widget isn't rendering, it's one of the three pieces — the widget is off, the page's origin isn't allowed, or the backend isn't holding a working credential — or Nash has paused it; it's never because the widget itself "stopped delivering."