Skip to content
Navo24Navo24

指南

在客户网站嵌入 Navo 应用

在您的网站嵌入集装箱追踪,并加入运价、船期和 AI 模式。一个 script 标签和域名锁定密钥,即可呈现自有品牌体验。

你可以把集装箱跟踪、运价和船期嵌入到客户自己的官网中。这些应用与 示例货代网站 上看到的是同一套:一个用于首页的搜索组件,以及每个应用各自的完整页面。每个应用都会显示为客户的名称、Logo 和品牌颜色。每个视图都有自己的链接,因此访客可以把某个集装箱、某次运价搜索、某条运价、某个船期、某条船或某个港口发给同事,对方打开后仍然是在客户的网站上查看。

客户侧不需要 API key,也不需要服务器。嵌入 key 是公开的,但只会在我们为它配置的域名上生效。

What the client sends us

ItemExampleRequired
访客看到的公司名称Acme LogisticsYes
应用运行所在的域名(生产、预发布)acme.com, www.acme.com, staging.acme.comYes
Logo,SVG 或 PNG,方形标识或横版https://acme.com/logo.svgYes
品牌色,一个 hex 值#0e6ba8Yes
更多颜色、字体、圆角见 外观和风格Optional
接收订舱请求的 e-mail[email protected]For freight rates
订舱请求的 Webhook URL(到他们的 CRM/TMS)https://acme.com/hooks/navoOptional
他们需要哪些应用tracking、freight、schedules 中任意组合,AI mode 开或关Yes
每个应用的使用额度,按月或按年tracking: 300 unique shipments a monthYes
每个应用所在页面/track, /rates, /schedulesRecommended
显示或隐藏“由 Navo 提供支持”已显示Default: shown

我们会创建 key,并把下面的代码片段填入 key 后发回。

What one key can carry

一个 key 可以开启一个或多个应用,AI mode 是单独的开关:

PackageApps on the keyWhat the visitor gets
仅 TrackingtrackingTracking 页面,搜索组件只显示 tracking 输入框,没有标签页,也没有 AI 开关
Tracking with AItracking, ai同上,另外搜索组件中有 AI mode,shipment 页面上有“询问 AI”
Rates and schedulesfreight, schedules搜索组件中有两个标签页,rates 和 schedules 页面
Everythingtracking, freight, schedules, ai全部三个标签页、AI mode、全部页面

组件会根据 key 生成:如果 key 没有开启某个标签页、页面或 AI 按钮,就完全不会渲染出来,即使有人强行发起请求,我们的服务器也会拒绝返回数据。

Usage limits

key 上每个应用都有自己的额度,按自然月或自然年(UTC)计算。一次用量的定义如下:

AppOne unitFree 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 日。当某个应用达到额度时,访客会看到“此网站上的该服务目前已暂停。请联系 。”key 上的其他应用会继续工作。我们可以查看每个应用的用量,并且可以随时提高额度,客户网站无需修改。

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

AttributeWhat it does
data-navo-appsearch, tracking, freight 或 schedules。
data-navo-key站点的嵌入 key。
data-navo-pages应用到客户站内页面路径的 JSON 映射。
data-navo-height固定高度,单位 px。默认情况下 frame 会随内容增长;tracking 是完整地图,680 px。
data-navo-syncoff 表示访客点击切换时不改变页面 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,就能捕获页面上的所有应用事件。

EventWhenevent.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 都是可选的。无效值会被忽略,其余配置仍然生效。

KeyWhat it changesExample
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”)。

它分为两部分:

  1. Snapshot. 客户服务器从我们这里获取该 lane 的数据,格式为普通 HTML(schedule table 或 rate table、heading、一行摘要和 schema.org markup),然后放入自己的页面。搜索引擎会把它作为客户 URL 上的客户内容索引。
  2. 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 的拦截不会影响它。

当访客在应用中操作时,页面 URL 会跟随变化:?navo_app=<app>&navo=<view>。应用内的 Copy link 按钮也会生成同类型链接。以下示例位于客户页面 /rates:

ViewLink
一个 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

  1. 客户发送名称、域名、Logo、颜色、booking e-mail、购买的应用(AI mode 开或关)以及每个应用的额度(可选提供 webhook、页面路径)。
  2. 我们创建 key,并发送代码片段。
  3. 客户添加 embed.js 和容器,先放到预发布环境。
  4. 客户检查:search → tracking、rates → details → booking(一封测试 e-mail 到达)、共享链接能在他们站点上打开。如果使用严格 CSP,检查浏览器控制台是否有被拦截的 navo24.com。
  5. 客户添加生产域名(如果还不在列表中),然后上线。