Safecube makes it easy to embed live container tracking into your own platform, customer portal, or internal tools using a simple iframe
.
This guide will help you get started quickly and confidently.
✅ Why Use This?
- 📍 Display real-time shipment tracking inside your own interface
- 🔗 Use public sharing links – no login required
- 🧩 Offer a seamless branded experience with optional White Labeling
🧰 Prerequisites
Before you begin, ensure you have access to the required features:
-
Create a Safecube Account
Sign up at safecube.ai and retrieve your API key from your account. -
Request Premium Feature Access
You must contact us to enable:- ✅ Safecube Shipment Management API
- ✅ Iframe Embedding Authorization (we whitelist your domain)
🔁 Workflow Overview
- Create a Shipment using the API
- Retrieve the Public Sharing Link
- Embed the Link into your app or site using an
iframe
🛠️ Step-by-Step Guide
1. Create the Shipment
Make a request to:
POST https://api.sinay.ai/safecube/api/v1/public/shipments
Headers
API_KEY: your-api-key
Content-Type: application/json
Body Example
{
"shipments": [
{
"shipmentNumber": "GCXU5630216",
"scac": "COSU"
}
]
}
2. Get the Public Sharing Link
Use the following endpoint to retrieve the public link for embedding:
POST https://api.sinay.ai/safecube/api/v1/public/shipments/search
Headers
API_KEY: your-api-key
Content-Type: application/json
Body Example
{
"shipmentNumbers": ["GCXU5630216"]
}
Sample Response
{
"results": [
{
"shipmentNumber": "GCXU5630216",
"link": "https://app.safecube.ai/shared/shipment?token=abc123..."
}
]
}
This is the URL you’ll embed inside your iframe.
3. Embed in Your Website or Tool
Now that you have the link
, embed it using a standard HTML iframe
:
<iframe
src="https://app.safecube.ai/shared/shipment?token=abc123..."
width="100%"
height="600"
style="border: none;"
allowfullscreen
></iframe>
💡You can adjust width/height and styling as needed.
🧩 Simplified Views: Embed Only What You Need
By default, the public link returned by the Shipment Management API embeds the full shipment tracking experience (including header and tabs).
However, if you prefer to embed only a specific part of the shipment data (like just the map or the event timeline), Safecube provides alternate views you can use — with the same token.
Just extract the token
from the standard public URL and use one of the dedicated simplified view URLs below.
🔗 Example Base Public URL
This is the standard public link returned by the API: https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3
🎯 Alternative View URLs (just replace the token)
View Type | URL Format |
---|---|
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 |
🧪 Regex Helper (for devs)
To convert the public link automatically to a simplified view, you can extract the token using a simple regex and build the new URL.
Here’s a JavaScript example:
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);
}
✅ Why Use Simplified Views?
- Embed only what's relevant for your use case
- Reduce visual clutter for users
- Keep your interface clean and focused
These simplified views are ideal for integrations in dashboards, CRMs, or customer-facing portals where a full application-like UI is unnecessary.
Note: All views are still read-only and public — no login is required.
🧩 Bonus: Build a Shipment Lookup Widget
You can go beyond just displaying a shipment by building a simple input box where users enter their container or booking number. Behind the scenes, you’ll:
- Use their input to call the Create Shipment endpoint.
- Then fetch the Public Link.
- Finally, embed the tracking view dynamically in an
iframe
.
🔧 Example Flow
- User enters:
GCXU5630216
- You
POST
to/public/shipments
with that number. - Then
POST
to/public/shipments/search
to get the link. - Display the
iframe
with the returned public URL.
This gives your users the full tracking experience—without needing to sign in or contact support.
💡 Why This is Awesome
- 🕐 Saves time for your team and your users
- 🎯 Turns any page into a live tracking portal
- 🔒 Keeps everything secure and read-only via the public token
🔧 Full Self-Service Tracking Widget (Optional Advanced Integration)
If you want to go a step further, you can build a fully dynamic shipment tracking widget on your site.
This allows your users to enter their container, booking, or Bill of Lading number, and immediately see the Safecube tracking page — embedded right into your interface.
No logins, no external navigation — just instant tracking, fully integrated.
⚙️ How It Works
- User enters their shipment number.
- Your website calls Safecube’s API to:
- Create the shipment
- Fetch the public tracking link
- You embed that link in an
iframe
, on the fly.
Here’s a ready-to-use HTML/JavaScript snippet that does all of this for you:
<!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"; // 🔐 Replace with your actual 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 searchRes = 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 searchRes.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 (err) {
console.error(err);
errorDiv.textContent = "An error occurred while tracking the shipment.";
}
}
</script>
</body>
</html>
🎨 Optional: White Label Integration
You can further personalize the experience by replacing:
- The Safecube subdomain (
app.safecube.ai
) with your own subdomain (yourbrand.safecube.ai
) - The Safecube logo with your company logo
👉 This is part of our White Label Premium Feature.
Contact us to get it set up: Request Branding Access
🚀 You're All Set!
You’ve now embedded live container tracking into your own environment—with no login required and full flexibility.
Need help? Reach out to our team — we're happy to support you!