Drop-in Web Tracking Embedding: How to White-Label Ocean Container Tracking

The engineering cost of custom tracking interfaces

Every freight forwarder, 3PL, and customs broker wants to give customers self-service shipment visibility on their website. Providing that experience from scratch presents substantial engineering hurdles. A complete container tracking frontend requires:

• Multi-source carrier connectivity: Managing integrations across dozens of ocean container lines, each with distinct request formats, reference numbering rules, and error conditions.
• Event normalization: Converting diverse carrier status vocabularies into standard milestones like gate-in, vessel departure, transhipment discharge, and delivery.
• Geospatial mapping: Rendering responsive vessel route maps, plotting automated geographic coordinates, and updating live vessel positions without heavy client-side bundle overhead.
• Exception handling: Managing carrier connection retries, rate limits, and network errors gracefully on user screens.

Maintaining these components requires continuous developer attention. Web embedding solves this problem by packaging Panvaya's normalized carrier tracking pipeline and responsive user interface into an embeddable component that runs securely within any web application.

Two deployment modes: public versus private access

Different logistics portals serve different audiences. Panvaya supports two operational modes to balance public reach and corporate data confidentiality.

The public mode suits marketing websites, freight quote pages, and open track-and-trace tools. In this mode, visitors can enter container numbers, bills of lading, or booking references directly into the widget search field. Administrators configure allowed websites (origin restrictions) so that only your approved domains can embed the iframe. You can also enforce an approved reference list, restricting lookups strictly to your active shipments, and set a daily credit budget that resets at 00:00 UTC to prevent budget overruns.

The private mode is engineered for authenticated client portals and TMS dashboards where clients must view only their own cargo. In a shared portal, origin restrictions alone are insufficient because any visitor could enter arbitrary container numbers. Private access solves this by combining client authentication with server-side authorization tokens.

How private access protects customer cargo data

Private embedding ensures that end users cannot search unauthorized shipments, while keeping your secret API keys safely on your backend server. The launch lifecycle follows four structured steps:

• Customer authentication: The client logs into your portal using their existing account credentials. Your backend verifies their identity and looks up their assigned shipments.
• Single-use launch request: Your server calls the Panvaya launch API using an organization administrator API key, passing the allowed website origin and the specific references authorized for that customer.
• Temporary launch code: Panvaya returns a one-time launch code with a strict 60-second expiration window.
• Session exchange: Your portal immediately loads the iframe URL containing the launch code in the URL fragment. The widget exchanges the launch code for a 15-minute reference-scoped session and strips the fragment from browser history.

Because the session is strictly scoped to the references specified during launch, the visitor cannot look up unrelated containers. Permanent API keys never touch client-side browser code, network inspectors, or local storage.

White-label customization and brand appearance

The embedded widget adapts naturally to your brand identity. Through the dashboard console, administrators can configure:

• Custom display name: Replace generic headings with your company name or custom portal title.
• Brand accent colour: Set a primary hex colour that matches your brand palette for buttons, milestone progress bars, and route highlights.
• Responsive layout: The iframe automatically adjusts its content structure between mobile screens and desktop layouts, ensuring clear visibility across phones, tablets, and wide monitors.
• Hosted fallback: Enable an optional hosted tracking link for customers who prefer opening tracking records in a standalone browser tab.

Managing approved references programmatically

For teams using restricted access mode, managing approved references does not require manual dashboard editing. Panvaya provides dedicated endpoints to synchronize references with your transport management system:

• Read approved references: Call GET on the widget references endpoint to review the current active allowlist of up to 500 references.
• Batch updates: Send PATCH requests with add and remove arrays to keep reference lists synchronized as new bookings open and completed shipments discharge.
• Document scoping: You can approve an entire bill of lading to display all associated containers, or append a specific container number to restrict visibility to a single box within a multi-container booking.

Predictable metering and billing

Web embedding connects directly to your organization API balance. Page views, iframe loading, reference allowlist updates, and failed tracking lookups are completely free. Credits are deducted only upon a successful tracking response.

Built-in idempotency ensures that network interruptions do not result in duplicate billing. If a visitor retries a completed tracking request, the system detects the completed transaction and returns the result without initiating another carrier query or deducting extra credits.

The bottom line

Delivering modern shipment tracking on your logistics website no longer requires building complex data pipelines and custom mapping interfaces. Panvaya web embedding gives freight forwarders and shippers a secure, white-label tracking widget that can be configured in minutes. By choosing between public origin-restricted tools and private token-authorized sessions, you can provide your clients with reliable container visibility while keeping your proprietary systems and credentials safe.