指南
在客户网站嵌入 Navo 应用
在您的网站嵌入集装箱追踪,并加入运价、船期和 AI 模式。一个 script 标签和域名锁定密钥,即可呈现自有品牌体验。
你可以把集装箱跟踪、运价和船期嵌入到客户自己的官网中。这些应用与 示例货代网站 上看到的是同一套:一个用于首页的搜索组件,以及每个应用各自的完整页面。每个应用都会显示为客户的名称、Logo 和品牌颜色。每个视图都有自己的链接,因此访客可以把某个集装箱、某次运价搜索、某条运价、某个船期、某条船或某个港口发给同事,对方打开后仍然是在客户的网站上查看。
客户侧不需要 API key,也不需要服务器。嵌入 key 是公开的,但只会在我们为它配置的域名上生效。
What the client sends us
| Item | Example | Required |
|---|---|---|
| 访客看到的公司名称 | Acme Logistics | Yes |
| 应用运行所在的域名(生产、预发布) | acme.com, www.acme.com, staging.acme.com | Yes |
| Logo,SVG 或 PNG,方形标识或横版 | https://acme.com/logo.svg | Yes |
| 品牌色,一个 hex 值 | #0e6ba8 | Yes |
| 更多颜色、字体、圆角 | 见 外观和风格 | Optional |
| 接收订舱请求的 e-mail | [email protected] | For freight rates |
| 订舱请求的 Webhook URL(到他们的 CRM/TMS) | https://acme.com/hooks/navo | Optional |
| 他们需要哪些应用 | tracking、freight、schedules 中任意组合,AI mode 开或关 | Yes |
| 每个应用的使用额度,按月或按年 | tracking: 300 unique shipments a month | Yes |
| 每个应用所在页面 | /track, /rates, /schedules | Recommended |
| 显示或隐藏“由 Navo 提供支持” | 已显示 | Default: shown |
我们会创建 key,并把下面的代码片段填入 key 后发回。
What one key can carry
一个 key 可以开启一个或多个应用,AI mode 是单独的开关:
| Package | Apps on the key | What the visitor gets |
|---|---|---|
| 仅 Tracking | tracking | Tracking 页面,搜索组件只显示 tracking 输入框,没有标签页,也没有 AI 开关 |
| Tracking with AI | tracking, ai | 同上,另外搜索组件中有 AI mode,shipment 页面上有“询问 AI” |
| Rates and schedules | freight, schedules | 搜索组件中有两个标签页,rates 和 schedules 页面 |
| Everything | tracking, freight, schedules, ai | 全部三个标签页、AI mode、全部页面 |
组件会根据 key 生成:如果 key 没有开启某个标签页、页面或 AI 按钮,就完全不会渲染出来,即使有人强行发起请求,我们的服务器也会拒绝返回数据。
Usage limits
key 上每个应用都有自己的额度,按自然月或自然年(UTC)计算。一次用量的定义如下:
| App | One unit | Free repeats |
|---|---|---|
tracking | 一个唯一 shipment(container、booking 或 B/L number) | 同一个 shipment 在本周期内后续免费 |
freight | 一次运价搜索(lane 和 equipment) | 同一天内相同搜索免费 |
schedules | 一次船期搜索(route、vessel 或 port) | 同一天内相同搜索免费 |
ai | 向 AI assistant 提一个问题 | None |
示例:tracking 每月 300 个唯一 shipments。客户的访客可以在整个月内任意打开和刷新这 300 个 shipments;第 301 个 shipment 会被拒绝,直到下个月 1 日。当某个应用达到额度时,访客会看到“此网站上的该服务目前已暂停。请联系
Install
在每个展示应用的页面上放一次 loader:
<script src="https://navo24.com/embed.js" async></script>
然后在应用应出现的位置放一个容器。
Search widget(首页主视觉区域,或任意页面)。一个搜索框,会为 key 上的每个应用(tracking、rates、schedules)显示对应标签页,如果 key 包含 AI,也会显示 AI mode。只有一个应用时不显示标签页:
<div
data-navo-app="search"
data-navo-key="nve_YOUR_KEY"
data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>
有 data-navo-pages 时,组件会把访客带到客户自己的页面。没有它时,结果会直接在组件的 frame 内打开。
Tracking page(/track):
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
Freight rates page(/rates):
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
Sailing schedules page(/schedules),包含三个标签页:按 route、按 vessel、按 port:
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
每个应用都使用相同的 data-navo-pages 值,这样跨链接(例如 sailing 上的“显示运价”,或 shipment 上的“船舶船期”)会落到客户网站上的正确页面。
Options
| Attribute | What it does |
|---|---|
data-navo-app | search, tracking, freight 或 schedules。 |
data-navo-key | 站点的嵌入 key。 |
data-navo-pages | 应用到客户站内页面路径的 JSON 映射。 |
data-navo-height | 固定高度,单位 px。默认情况下 frame 会随内容增长;tracking 是完整地图,680 px。 |
data-navo-sync | off 表示访客点击切换时不改变页面 URL。 |
data-navo-theme | 包含颜色、字体和圆角的 JSON,见 外观和风格。 |
Sites with a Content Security Policy
如果站点通过 Content-Security-Policy header(或 <meta http-equiv>)设置了 script-src 或 frame-src,需要把 navo24.com 加到两者中,否则浏览器会拦截 loader 或 frame,容器会保持为空:
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
如果使用的是 child-src 而不是 frame-src,也加在那里。除此之外不需要其他配置:应用的数据、字体和地图都会在 frame 内加载,并受我们自己的策略控制。如果缺少某项,浏览器控制台会显示被拦截的 directive 名称。
Events for analytics and CRM
当访客执行操作时,容器会触发 DOM events,站点可以把它们发送到 Google Analytics、tag manager 或 CRM。事件会冒泡,因此在 document 上放一个 listener,就能捕获页面上的所有应用事件。
| Event | When | event.detail |
|---|---|---|
navo:search | 搜索返回结果 | app(tracking, freight, schedules)以及查询:ref,或 origin, destination, container |
navo:booking | 已发送订舱请求 | reference, origin, destination, container, quantity, carrier, price, currency |
navo:limit | 额度阻止了一次搜索 | app, code(例如 site_busy, rate_limited) |
<script>
document.addEventListener('navo:search', (e) => gtag('event', 'navo_search', e.detail));
document.addEventListener('navo:booking', (e) => gtag('event', 'generate_lead', { value: e.detail.price, currency: e.detail.currency, transaction_id: e.detail.reference }));
</script>
访客联系方式不会出现在事件中:它们只会发送到订舱 e-mail 和 webhook。
Look and feel
默认情况下,应用会从 key 中读取客户的品牌色。为了更贴合站点,可以在容器上添加 data-navo-theme:颜色、字体、圆角和深色模式。
<div
data-navo-app="freight"
data-navo-key="nve_YOUR_KEY"
data-navo-theme='{"accent":"#e4002b","text":"#1a1a1a","heading":"#002f6c","font":"Inter","radius":6,"buttonRadius":6}'
></div>
每个 key 都是可选的。无效值会被忽略,其余配置仍然生效。
| Key | What it changes | Example |
|---|---|---|
accent | 按钮、链接、激活标签页、开关、焦点环。Hover 和 pressed 色阶会基于它计算 | "#e4002b" |
text | 主文本 | "#1a1a1a" |
muted | 次要文本:标签、提示、日期 | "#6b7280" |
heading | 标题、carrier 和 vessel 名称、地图线路 | "#002f6c" |
background | 应用的页面背景。"transparent" 会透出客户自己的背景 | "#ffffff" |
surface | 卡片、输入框、表格条纹 | "#f5f7fa" |
border | 边框和分隔线 | "#e5e7eb" |
success | 正向状态:已送达、准点、最便宜 | "#15803d" |
radius | 卡片和面板圆角,px(0 到 40) | 8 |
buttonRadius | 按钮和输入框圆角,px。999 会得到胶囊形(默认值) | 6 |
font | 正文字体。任何 Google Fonts 字体族都会为你加载;"system" 使用访客的系统字体 | "Inter" |
headingFont | 标题字体,规则相同。不设置时标题使用 font | "Playfair Display" |
fontCss | 你自己的字体样式表(带 @font-face 规则的 https:// URL),用于不在 Google Fonts 上的字体。之后 font 和 headingFont 可引用该文件中的字体族名称 | "https://acme.com/fonts/brand.css" |
mode | 面向深色设计站点的 "dark" | "dark" |
颜色使用 hex:#rgb, #rrggbb 或 #rrggbbaa。
可直接使用的起点:
<!-- Corporate: square corners, navy headings -->
data-navo-theme='{"accent":"#003a70","heading":"#003a70","font":"Source Sans 3","radius":2,"buttonRadius":2}'
<!-- Soft: rounded, light grey cards -->
data-navo-theme='{"accent":"#0f766e","surface":"#f3f4f6","font":"Nunito","radius":16,"buttonRadius":999}'
<!-- Dark site -->
data-navo-theme='{"mode":"dark","accent":"#f59e0b","background":"#0b1220","surface":"#111a2e","border":"#1f2a44","text":"#e5e7eb","muted":"#94a3b8"}'
<!-- Blend into the page: the app draws no background of its own -->
data-navo-theme='{"background":"transparent","font":"system"}'
所有页面使用同一个主题。 我们也可以把主题存储在 key 上。这样每个页面上的每个容器即使没有该属性,也会自动获得主题,而且我们之后可以调整它,客户网站无需修改。容器上的 data-navo-theme 仍然会按 key 覆盖 key 上的主题。
主题只会作用于 frame 内的应用:永远不会改变客户自己的页面。
React and Next.js, with search indexing
当客户站点使用 React 或 Next.js 构建,并且应用内容应该作为客户页面被索引时使用这种方式(例如按航线生成页面,“Shanghai to Hamburg sailing schedule”)。
它分为两部分:
- Snapshot. 客户服务器从我们这里获取该 lane 的数据,格式为普通 HTML(schedule table 或 rate table、heading、一行摘要和 schema.org markup),然后放入自己的页面。搜索引擎会把它作为客户 URL 上的客户内容索引。
- App. 在浏览器中,交互式应用会挂载在它上方,提供搜索、筛选、详情和订舱。snapshot 会作为一个可折叠表格保留在应用下方,因此爬虫和访客看到的是同一份内容。
Snapshot endpoint
GET https://api.navo24.com/v1/demo/embed/snapshot
?key=nve_YOUR_KEY
&app=schedules schedules | freight
&origin=CNSHA UN/LOCODE
&destination=DEHAM UN/LOCODE
&container=40HC freight only: 20GP | 40GP | 40HC
&host=acme.com the client's domain, must be on the key
&format=html optional: the HTML block only
没有 format=html 时,返回 JSON:
{
"data": {
"app": "schedules",
"title": "Sailing schedule Shanghai to Hamburg",
"description": "153 sailings from Shanghai (CNSHA) to Hamburg (DEHAM) in the next 6 weeks, 10 carriers, transit from 34 days.",
"items": [{ "carrier": "Yang Ming", "vessel": "MSC OLIVIA", "voyage": "GL642W", "etd": "2026-10-24T00:00:00", "eta": "2026-12-03T00:00:00", "transit_days": 40, "direct": true }],
"html": "<section class=\"navo-snapshot\">…</section>",
"as_of": "2026-10-22T08:52:51Z"
}
}
使用 title 和 description 作为页面的 <title> 和 meta description,使用 html 作为正文。响应可缓存 30 分钟(Cache-Control: max-age=1800)。一次 snapshot 会计为该应用额度中的一次搜索;同一天相同 lane 免费。Tracking 没有 snapshot:shipments 对访客是私有的。
Next.js (App Router)
// app/schedules/[lane]/page.tsx e.g. /schedules/cnsha-deham
import NavoApp from './NavoApp';
const KEY = 'nve_YOUR_KEY';
const API = 'https://api.navo24.com/v1/demo/embed/snapshot';
async function snapshot(lane: string) {
const [origin, destination] = lane.toUpperCase().split('-');
const q = new URLSearchParams({ key: KEY, app: 'schedules', origin, destination, host: 'acme.com' });
const r = await fetch(`${API}?${q}`, { next: { revalidate: 1800 } });
return r.ok ? (await r.json()).data : null;
}
export async function generateMetadata({ params }: { params: { lane: string } }) {
const s = await snapshot(params.lane);
return s ? { title: `${s.title} | Acme Logistics`, description: s.description } : {};
}
export default async function Page({ params }: { params: { lane: string } }) {
const s = await snapshot(params.lane);
const [origin, destination] = params.lane.toUpperCase().split('-');
return (
<main>
<NavoApp
app="schedules"
embedKey={KEY}
view={{ origin, destination }}
snapshotHtml={s?.html}
theme={{ accent: '#e4002b', font: 'Inter' }}
/>
</main>
);
}
// app/schedules/[lane]/NavoApp.tsx
'use client';
import { useEffect, useRef, useState } from 'react';
const SRC = 'https://navo24.com/embed.js';
function loadNavo(): Promise<void> {
const w = window as any;
if (w.NavoEmbed) return Promise.resolve();
return new Promise((ok) => {
let s = document.querySelector<HTMLScriptElement>(`script[src="${SRC}"]`);
if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
s.addEventListener('load', () => ok(), { once: true });
});
}
type Props = {
app: 'search' | 'tracking' | 'freight' | 'schedules';
embedKey: string;
view?: Record<string, string>; // opens this lane right away
pages?: Record<string, string>;
theme?: Record<string, string | number>;
snapshotHtml?: string; // server-rendered data for search engines
};
export default function NavoApp({ app, embedKey, view, pages, theme, snapshotHtml }: Props) {
const box = useRef<HTMLDivElement>(null);
const [live, setLive] = useState(false); // until the app is up, the table is open
useEffect(() => {
if (view && !new URLSearchParams(location.search).get('navo')) {
const u = new URL(location.href);
u.searchParams.set('navo_app', app);
u.searchParams.set('navo', new URLSearchParams(view).toString());
history.replaceState(history.state, '', u);
}
loadNavo().then(() => { (window as any).NavoEmbed.mount(); setLive(true); });
}, [app, embedKey]);
return (
<>
<div
ref={box}
data-navo-app={app}
data-navo-key={embedKey}
data-navo-pages={pages ? JSON.stringify(pages) : undefined}
data-navo-theme={theme ? JSON.stringify(theme) : undefined}
/>
{snapshotHtml && (
<details open={!live}>
<summary>All results as a table</summary>
<div dangerouslySetInnerHTML={{ __html: snapshotHtml }} />
</details>
)}
</>
);
}
搜索引擎看到的是:页面自己的标题和描述、一个 heading、HTML 中完整的 sailings(或 rates)表格,并带有 Dataset markup。访客看到的是:实时应用,已经打开在该 lane 上,下方有同样结果的折叠表格。关闭 JavaScript 的访客会看到展开的表格。表格是折叠而不是隐藏,所以页面不会向爬虫展示访客无法打开的内容。
snapshot HTML 来自我们的服务器,每个值都已转义,因此可以安全插入。如果它需要展示,可以用 .navo-snapshot 和 .navo-snapshot-table classes 来设置样式。
其他服务端框架(Remix、Astro、Nuxt、PHP、WordPress)也以同样方式工作:在服务器上获取 snapshot,把 html 输出到页面中,并把容器放在旁边。
Plain React (no server rendering)
当搜索索引不重要时(菜单后的 tracking 页面、内网),不带 snapshot 的组件就足够了:
loader 在单页应用(React、Vue、Svelte)中的工作方式相同:渲染容器,然后调用 window.NavoEmbed.mount()。
import { useEffect } from 'react';
const SRC = 'https://navo24.com/embed.js';
function loadNavo() {
if (window.NavoEmbed) return Promise.resolve();
return new Promise((ok) => {
let s = document.querySelector(`script[src="${SRC}"]`);
if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
s.addEventListener('load', ok, { once: true });
});
}
export function NavoApp({ app, embedKey, pages }) {
useEffect(() => { loadNavo().then(() => window.NavoEmbed.mount()); }, [app, embedKey]);
return (
<div
data-navo-app={app}
data-navo-key={embedKey}
data-navo-pages={pages ? JSON.stringify(pages) : undefined}
/>
);
}
// <NavoApp app="tracking" embedKey="nve_YOUR_KEY" pages={{ tracking: '/track' }} />
在 Next.js 中,把它放到 client component('use client')里。
Why a frame
loader 会在来自 navo24.com 的 frame 内绘制每个应用。Stripe Checkout、Google Maps 嵌入和 YouTube 播放器也是这样工作的,原因相同:
- 域名锁定。 浏览器本身会拒绝在不在 key 列表中的站点上显示应用(
frame-ancestors)。加载到客户页面中的脚本组件无法用这种方式锁定。 - 没有样式冲突。 客户的 CSS 不会破坏应用,我们的 CSS 也不会影响他们的站点。
- 无需客户操作即可更新。 新 carrier、修复和功能会在当天覆盖到所有站点;客户侧不需要升级。
- 搜索引擎。 frame 内的内容不会作为客户页面被索引,这一点与任何地图或视频嵌入相同。如果这很重要,请添加服务端渲染的 snapshot,见 React and Next.js, with search indexing。
访客不会在 frame 内登录,因此浏览器对第三方 cookie 的拦截不会影响它。
Links to one exact view
当访客在应用中操作时,页面 URL 会跟随变化:?navo_app=<app>&navo=<view>。应用内的 Copy link 按钮也会生成同类型链接。以下示例位于客户页面 /rates:
| View | Link |
|---|---|
| 一个 container | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| 某条 lane 上的运价搜索 | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| 一条运价 | 上面的搜索再加 %26quote%3D<id> |
| 某条 lane 上的船期搜索 | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| 一个 sailing | 上面的搜索再加 %26sailing%3D<id> |
| 一条 vessel | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| 一个 port | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
共享的 rate 或 sailing 即使已不在实时结果中,也仍然会打开;页面会显示其数据采集日期。
Booking requests
在某条 rate 上点击 Book 会打开请求表单(contact、company、e-mail、phone、number of containers、cargo-ready date、cargo、notes)。提交时:
- 一封 e-mail 会发送到客户的订舱地址,包含 route、equipment、carrier、访客看到的 price,以及访客联系方式。Reply-To 是访客,所以客户可以直接从自己的邮箱回复;
- 如果设置了 webhook,同一个请求会以 JSON 形式 POST 到该地址:
{
"type": "booking.requested",
"data": {
"reference": "BR-261020-4F2A1",
"received_at": "2026-10-20T14:05:11Z",
"site": "acme.com",
"contact": { "name": "…", "company": "…", "email": "…", "phone": "…" },
"shipment": { "origin": "Shanghai (CNSHA)", "destination": "Hamburg (DEHAM)", "container": "40ft HC", "quantity": "2", "ready_date": "2026-11-03", "cargo": "…", "notes": "…" },
"rate": { "id": "…", "carrier": "…", "price": 2140, "currency": "USD", "transit_days": 34, "departure": "2026-11-06", "valid_until": "2026-11-15" }
}
}
访客会看到带 reference 的确认信息。不会扣费,也不会向 carrier 下正式 booking:客户会确认舱位并回复。
如果没有 booking e-mail 或 webhook,表单会保持为 demo,并明确说明这一点。
What visitors see, and what they do not
- Carrier 名称和 Logo、价格、运输时间、有效期以及 rate 包含的内容。
- 未注明 carrier 的 rates 会显示为“
Select”,并使用客户的 Logo。 - Rate sources 和 platforms 永远不会显示。数据到达浏览器前,我们会在服务器端移除它们。
Security
域名锁定。 应用页面会返回 Content-Security-Policy: frame-ancestors,其中只列出该 key 的域名,因此浏览器会拒绝在其他任何地方显示它们。数据请求会携带 key 和父页面 host,当 host 不在列表中时会被拒绝。把 key 复制到另一个站点上也无法使用。
额度。 key 上每个应用都有自己的月度或年度额度(见 使用额度)。除此之外,每个 key 还有每月 50,000 次请求的安全上限、整个站点每分钟 600 次请求的峰值上限(避免某个站点流量激增拖慢其他站点的应用,可按需提高),以及针对脚本滥用的访客级 rate limits;超过这些限制时,应用会显示简短的“稍后重试”消息,并触发 navo:limit。
消息。 frame 和 loader 通过 postMessage 通信,并且双方都只发送到对方的精确 origin:frame 发到客户页面,loader 发到 navo24.com。搜索详情永远不会发送给 *。
轮换。 如果 key 泄露,或站点更换所有者,我们会签发新 key,旧 key 会立即停止工作。
Testing before launch
请把预发布域名和生产域名一起发给我们,或者提供开发机上的 localhost:<port>。两者可以放在同一个 key 上。
Checklist
- 客户发送名称、域名、Logo、颜色、booking e-mail、购买的应用(AI mode 开或关)以及每个应用的额度(可选提供 webhook、页面路径)。
- 我们创建 key,并发送代码片段。
- 客户添加
embed.js和容器,先放到预发布环境。 - 客户检查:search → tracking、rates → details → booking(一封测试 e-mail 到达)、共享链接能在他们站点上打开。如果使用严格 CSP,检查浏览器控制台是否有被拦截的
navo24.com。 - 客户添加生产域名(如果还不在列表中),然后上线。