Embed a shipment in an iframe
Safecube shipment tracking can be embedded live in your own platform, customer portal or internal tools with a standard HTML iframe. The embedded page is the public sharing link of the shipment, returned by the Shipment Management API: it requires no login, and its branding can be replaced with yours through the white label option.
Prerequisites
- A Safecube account and API key — sign up at safecube.ai and retrieve your API key in the Safecube web application, under Developers > API Credentials.
- Iframe embedding authorization — iframe embedding is part of the white label pack and is enabled on request, because Safecube must authorize the domain of the pages that embed the iframe. Request it from the Safecube team, with that domain. The Shipment Management API itself is included in every Safecube plan and needs no request.
Workflow
- Create the shipment with the Shipment Management API.
- Retrieve its public sharing link.
- Embed the link in your application or website with an
iframe.
Step 1: create the shipment
Call POST /public/shipments with the shipment number and, optionally, the SCAC code of the shipping line:
POST https://api.sinay.ai/safecube/api/v1/public/shipments
API_KEY: <your API key>
Content-Type: application/json
{
"shipments": [
{
"shipmentNumber": "GCXU5630216",
"sealine": "COSU"
}
]
}
Step 2: get the public sharing link
Call POST /public/shipments/search with the shipment number:
POST https://api.sinay.ai/safecube/api/v1/public/shipments/search
API_KEY: <your API key>
Content-Type: application/json
{
"shipmentNumbers": ["GCXU5630216"]
}
The link field of each result is the public sharing link, the URL to embed in the iframe:
{
"results": [
{
"shipmentNumber": "GCXU5630216",
"link": "https://app.safecube.ai/shared/shipment?token=abc123..."
}
]
}
Step 3: embed the link
Embed the public sharing link with a standard HTML iframe, and adjust its width, height and style to your layout:
<iframe
src="https://app.safecube.ai/shared/shipment?token=abc123..."
width="100%"
height="600"
style="border: none;"
allowfullscreen
></iframe>
Simplified views
By default, the public sharing link embeds the full shipment tracking page, header and tabs included. To embed only part of it — the map or the event timeline — use one of the simplified views, with the same token as the public sharing link.
A public sharing link has the form https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3. Extract its token and build the URL of the view you need:
| View | URL |
|---|---|
| Details view | https://app.safecube.ai/iframe/shipment/details?token=YOUR_TOKEN |
| Map only | https://app.safecube.ai/iframe/shipment/map?token=YOUR_TOKEN |
| Event list only | https://app.safecube.ai/iframe/shipment/schedules?token=YOUR_TOKEN |
This JavaScript extracts the token from a public sharing link and builds the three simplified view URLs:
const publicLink = 'https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3'
const tokenMatch = publicLink.match(/token=([a-f0-9-]+)/)
if (tokenMatch) {
const token = tokenMatch[1]
const mapViewUrl = `https://app.safecube.ai/iframe/shipment/map?token=${token}`
const detailsViewUrl = `https://app.safecube.ai/iframe/shipment/details?token=${token}`
const scheduleViewUrl = `https://app.safecube.ai/iframe/shipment/schedules?token=${token}`
console.log('Map view:', mapViewUrl)
console.log('Details view:', detailsViewUrl)
console.log('Schedule view:', scheduleViewUrl)
}
Simplified views embed only what is relevant to your use case and keep your interface free of clutter. They suit dashboards, CRMs and customer-facing portals, where a full application-like interface is unnecessary. Every view, full or simplified, is read-only and public: no login is required.
Self-service tracking widget
The three steps combine into a tracking widget: your users enter a container, booking or bill of lading number on your site, and the Safecube tracking page appears embedded in your interface, with no login and no navigation away.
- The user enters a shipment number, such as
GCXU5630216. - Your website calls
POST /public/shipmentsto create the shipment. - Your website calls
POST /public/shipments/searchto retrieve its public sharing link. - Your website displays the public sharing link in an
iframe.
The HTML and JavaScript page below implements the widget:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Track Your Shipment</title>
<style>
body { font-family: sans-serif; padding: 2rem; }
input, button { padding: 0.5rem; margin-right: 0.5rem; }
iframe { width: 100%; height: 600px; margin-top: 2rem; border: 1px solid #ccc; }
</style>
</head>
<body>
<h1>Track Your Shipment</h1>
<p>Enter your container, booking, or BL number:</p>
<input type="text" id="shipmentNumber" placeholder="e.g. GCXU5630216" />
<button onclick="trackShipment()">Track</button>
<div id="error" style="color: red; margin-top: 1rem;"></div>
<iframe id="trackingIframe" style="display: none;"></iframe>
<script>
const API_KEY = 'your-api-key'
const API_BASE = 'https://api.sinay.ai/safecube/api/v1'
async function trackShipment() {
const shipmentNumber = document.getElementById('shipmentNumber').value.trim()
const errorDiv = document.getElementById('error')
const iframe = document.getElementById('trackingIframe')
errorDiv.textContent = ''
iframe.style.display = 'none'
if (!shipmentNumber) {
errorDiv.textContent = 'Please enter a shipment number.'
return
}
try {
// Step 1: create the shipment
await fetch(`${API_BASE}/public/shipments`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', API_KEY: API_KEY },
body: JSON.stringify({ shipments: [{ shipmentNumber }] }),
})
// Step 2: search for the public link
const searchResponse = await fetch(`${API_BASE}/public/shipments/search`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', API_KEY: API_KEY },
body: JSON.stringify({ shipmentNumbers: [shipmentNumber] }),
})
const data = await searchResponse.json()
if (data.results && data.results.length > 0 && data.results[0].link) {
iframe.src = data.results[0].link
iframe.style.display = 'block'
} else {
errorDiv.textContent = 'Shipment created, but no link found. Try again shortly.'
}
} catch (error) {
console.error(error)
errorDiv.textContent = 'An error occurred while tracking the shipment.'
}
}
</script>
</body>
</html>
White label
The embedded tracking can carry your brand instead of Safecube's:
- your own subdomain, such as
yourbrand.safecube.ai, replacesapp.safecube.ai; - your company logo replaces the Safecube logo.
White label is a premium feature: request it from the Safecube team.