ガイド
Navo アプリを顧客サイトに埋め込む
Webサイトにコンテナ追跡を埋め込み、運賃、航路スケジュール、AIモードも自社ブランドで提供。1つのscriptタグとドメインロックキーで導入できます。
クライアント自身のWebサイトに、コンテナ追跡、運賃、航海スケジュールを埋め込めます。これは example forwarder site で表示されているアプリと同じものです。トップページ用の検索ウィジェットに加えて、各アプリ用のフルページがあります。いずれもクライアントの名称、ロゴ、カラーで表示されます。すべての表示には個別のリンクがあるため、訪問者はコンテナ、運賃検索、運賃、航海、船舶、港を1件ずつ同僚に送ることができ、そのリンクはクライアントのサイト上で開きます。
クライアント側に API キーやサーバーは不要です。埋め込みキーは公開されるもので、許可リストに登録したドメインでのみ動作します。
クライアントから受け取る情報
| Item | Example | Required |
|---|---|---|
| 訪問者に表示する会社名 | Acme Logistics | Yes |
| アプリを実行するドメイン、本番とステージング | acme.com, www.acme.com, staging.acme.com | Yes |
| ロゴ、SVG または PNG、正方形マークまたは横長 | https://acme.com/logo.svg | Yes |
| ブランドカラー、hex 値を1つ | #0e6ba8 | Yes |
| 追加のカラー、フォント、角丸 | 見た目と操作感 を参照 | Optional |
| ブッキングリクエストを受け取るメールアドレス | [email protected] | For freight rates |
| ブッキングリクエスト用 Webhook URL、CRM/TMS 連携用 | https://acme.com/hooks/navo | Optional |
| 利用したいアプリ | tracking, freight, schedules のいずれか、AI モードのオンまたはオフ | Yes |
| アプリごとの利用上限、月次または年次 | tracking: 300 unique shipments a month | Yes |
| 各アプリを配置するページ | /track, /rates, /schedules | Recommended |
| “Navo 提供” の表示または非表示 | 表示 | Default: shown |
こちらでキーを作成し、キーを埋め込んだ以下のスニペットを返します。
1つのキーで扱える内容
1つのキーで1つまたは複数のアプリを開けます。AI モードは別のスイッチです。
| Package | Apps on the key | What the visitor gets |
|---|---|---|
| Tracking only | tracking | トラッキングページ。検索ウィジェットにはタブも AI スイッチもなく、トラッキングボックスだけが表示されます |
| Tracking with AI | tracking, ai | 上記に加えて、検索ウィジェットに AI モード、シップメントに “AI に質問” が表示されます |
| Rates and schedules | freight, schedules | 検索ウィジェットに2つのタブ、運賃ページとスケジュールページ |
| Everything | tracking, freight, schedules, ai | 3つのタブすべて、AI モード、すべてのページ |
ウィジェットはキーの内容から構築されます。キーで許可されていないタブ、ページ、AI ボタンは一切描画されず、誰かがリクエストを強制しても当社サーバーがデータを拒否します。
利用上限
キー上の各アプリには、カレンダー月またはカレンダー年ごとの独自の上限があります (UTC)。1ユニットとしてカウントされるものは次のとおりです。
| App | One unit | Free repeats |
|---|---|---|
tracking | 1件のユニークなシップメント、コンテナ番号、ブッキング番号、B/L 番号 | 同じ期間内の同じシップメント |
freight | 1件の運賃検索、レーンと機材 | 同じ日の同じ検索 |
schedules | 1件のスケジュール検索、ルート、船舶、港 | 同じ日の同じ検索 |
ai | AI アシスタントへの1件の質問 | なし |
例: tracking が月300件のユニークなシップメントの場合。クライアントの訪問者は、その月の間、300件のシップメントを何度でも開いたり更新したりできます。301件目のシップメントは翌月1日まで拒否されます。アプリが上限に達すると、訪問者には “このサイトでは現在このサービスを一時停止しています。
インストール
アプリを表示するすべてのページに、ローダーを1回だけ配置します。
<script src="https://navo24.com/embed.js" async></script>
次に、アプリを表示する場所にコンテナを置きます。
検索ウィジェット、トップページのヒーローや任意のページ。キー上の各アプリ、tracking、rates、schedules ごとにタブがある1つのボックスで、キーに AI が含まれる場合は AI モードも表示されます。アプリが1つだけの場合、タブは表示されません。
<div
data-navo-app="search"
data-navo-key="nve_YOUR_KEY"
data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>
data-navo-pages を指定すると、ウィジェットは訪問者をクライアント自身のページへ送ります。指定しない場合、結果はウィジェットのフレーム内で直接開きます。
トラッキングページ (/track):
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
運賃ページ (/rates):
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
航海スケジュールページ (/schedules)、ルート別、船舶別、港別の3つのタブがあります。
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
すべてのアプリで同じ data-navo-pages 値を使用してください。これにより、クロスリンク、たとえば航海上の “運賃を表示” やシップメント上の “船舶スケジュール” が、クライアントサイト内の正しいページに遷移します。
オプション
| Attribute | What it does |
|---|---|
data-navo-app | search, tracking, freight, schedules のいずれか。 |
data-navo-key | サイトの埋め込みキー。 |
data-navo-pages | アプリからクライアントサイト上のページパスへの JSON マップ。 |
data-navo-height | px 単位の固定高さ。デフォルトではフレームはコンテンツに合わせて伸びます。tracking はフルマップで、680 px です。 |
data-navo-sync | off にすると、訪問者が操作してもページ URL を変更しません。 |
data-navo-theme | カラー、フォント、角丸を含む JSON。見た目と操作感 を参照。 |
Content Security Policy があるサイト
サイトが Content-Security-Policy ヘッダー、または <meta http-equiv> を script-src または frame-src 付きで送信している場合は、両方に navo24.com を追加してください。追加しないと、ブラウザーがローダーまたはフレームをブロックし、コンテナは空のままになります。
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
frame-src ではなく child-src を使っている場合は、そこに追加します。他に必要な設定はありません。アプリは当社のポリシーの下で、データ、フォント、マップをフレーム内に読み込みます。不足しているものがある場合、ブラウザーコンソールにブロックされたディレクティブが表示されます。
アナリティクスと CRM 用イベント
訪問者が操作するとコンテナが DOM イベントを発火するため、サイト側で Google Analytics、タグマネージャー、CRM に送信できます。イベントはバブリングするので、document に1つリスナーを置けばページ上のすべてのアプリを捕捉できます。
| 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>
訪問者の連絡先情報はイベントには含まれません。ブッキングメールと Webhook にのみ送信されます。
見た目と操作感
デフォルトでは、アプリはキーに設定されたクライアントのブランドカラーを使用します。サイトにより近づけるには、コンテナに 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 | What it changes | Example |
|---|---|---|
accent | ボタン、リンク、アクティブなタブ、スイッチ、フォーカスリング。ホバー時と押下時の色はここから計算されます | "#e4002b" |
text | メインテキスト | "#1a1a1a" |
muted | セカンダリテキスト、ラベル、ヒント、日付 | "#6b7280" |
heading | 見出し、キャリア名と船舶名、マップ線 | "#002f6c" |
background | アプリのページ背景。"transparent" にするとクライアント自身の背景が透けて表示されます | "#ffffff" |
surface | カード、入力欄、テーブルの縞 | "#f5f7fa" |
border | ボーダーと区切り線 | "#e5e7eb" |
success | ポジティブな状態、配達済み、定刻、最安 | "#15803d" |
radius | カードとパネルの角丸、px (0 to 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"}'
すべてのページで1つのテーマ。 テーマをキーに保存することもできます。その場合、すべてのページのすべてのコンテナに属性なしで適用され、後からクライアントのサイトを変更せずに調整できます。コンテナ上の data-navo-theme は、キー単位でキーのテーマより優先されます。
テーマはフレーム内のアプリにのみ届きます。クライアント自身のページを変更することはありません。
React と Next.js、検索インデックス対応
クライアントのサイトが React または Next.js で構築されており、アプリのコンテンツをクライアントのページとしてインデックスさせたい場合に使用します。たとえば、レーンごとのページ、“Shanghai to Hamburg sailing schedule” などです。
これは2つの部分で構成されます。
- スナップショット。 クライアントのサーバーがレーンのデータをプレーンな HTML として当社から取得します。スケジュール表または運賃表、見出し、1行の要約、schema.org マークアップを含みます。それを自社ページに挿入します。検索エンジンは、クライアントの URL 上にあるクライアントのコンテンツとしてインデックスします。
- アプリ。 ブラウザーでは、インタラクティブなアプリがその上にマウントされます。検索、フィルター、詳細、ブッキングが使えます。スナップショットはアプリの下に折りたたみ可能なテーブルとしてページに残るため、クローラーと訪問者は同じコンテンツを見られます。
スナップショットエンドポイント
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> と meta description には title と description を使い、本文には html を使います。レスポンスは30分間キャッシュできます (Cache-Control: max-age=1800)。スナップショットはアプリの上限に対して1検索としてカウントされます。同じ日の同じレーンは無料です。Tracking にはスナップショットはありません。シップメントは訪問者にとって非公開の情報だからです。
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>
)}
</>
);
}
検索エンジンから見ると、このページにはページ自身のタイトルと説明、見出し、航海または運賃の完全なテーブルが HTML 内にあり、Dataset マークアップも含まれます。訪問者から見ると、ライブアプリがそのレーンであらかじめ開かれており、同じ結果が折りたたまれたテーブルとして下に表示されます。JavaScript をオフにしている訪問者には、開いたテーブルが表示されます。テーブルは非表示ではなく折りたたみなので、訪問者が開けないものをクローラーだけに見せることはありません。
スナップショット HTML は当社サーバーから返され、すべての値がエスケープ済みなので、安全に挿入できます。表示される可能性がある場合は、.navo-snapshot と .navo-snapshot-table クラスでスタイルを設定してください。
他のサーバーフレームワーク、Remix, Astro, Nuxt, PHP, WordPress でも同じです。サーバーでスナップショットを取得し、html をページに出力し、その横にコンテナを置きます。
プレーン React、サーバーレンダリングなし
検索インデックスが重要でない場合、メニュー配下のトラッキングページやイントラネットなどでは、スナップショットなしのコンポーネントで十分です。
ローダーはシングルページアプリ、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 ではクライアントコンポーネント ('use client') に置きます。
フレームを使う理由
ローダーは navo24.com からのフレーム内に各アプリを描画します。これは Stripe Checkout、Google Maps 埋め込み、YouTube プレイヤーと同じ仕組みで、理由も同じです。
- ドメインロック。 キーのリストにないサイト上では、ブラウザー自身がアプリの表示を拒否します (
frame-ancestors)。クライアントページに読み込まれるスクリプトコンポーネントでは、この方法でロックできません。 - スタイル衝突なし。 クライアントの CSS がアプリを壊すことはなく、当社の CSS がクライアントのサイトに影響することもありません。
- クライアント作業なしで更新。 新しいキャリア、修正、機能は同じ日にすべてのサイトへ届きます。クライアント側でアップグレードするものはありません。
- 検索エンジン。 フレーム内のコンテンツは、地図や動画の埋め込みと同様、クライアントのページとしてはインデックスされません。それが重要な場合は、サーバーレンダリングされたスナップショットを追加してください。React と Next.js、検索インデックス対応 を参照してください。
訪問者はフレーム内でログインしないため、ブラウザーによるサードパーティ Cookie のブロックは影響しません。
正確な表示へのリンク
訪問者がアプリを操作している間、ページ URL は操作に追従します: ?navo_app=<app>&navo=<view>。アプリ内の リンクをコピー ボタンも同じ種類のリンクを生成します。クライアントページ /rates での例:
| View | Link |
|---|---|
| コンテナ | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| レーンでの運賃検索 | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| 1件の運賃 | 上記の検索に %26quote%3D<id> を追加 |
| レーンでの航海検索 | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| 1件の航海 | 上記の検索に %26sailing%3D<id> を追加 |
| 船舶 | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| 港 | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
共有された運賃または航海は、ライブ結果から外れた後も開けます。そのデータが取得された日付とともに表示されます。
ブッキングリクエスト
運賃上の Book を押すと、リクエストフォームが開きます。連絡先、会社、メール、電話、コンテナ本数、貨物準備日、貨物、メモを入力します。送信時:
- クライアントのブッキングアドレスにメールが送信されます。ルート、機材、キャリア、訪問者が見た価格、訪問者の連絡先情報が含まれます。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" }
}
}
訪問者には参照番号付きの確認画面が表示されます。課金は行われず、キャリアへのブッキングも作成されません。クライアントがスペースを確認し、返信します。
ブッキングメールまたは Webhook がない場合、フォームはデモのままとなり、その旨を表示します。
訪問者に表示されるもの、表示されないもの
- キャリア名とロゴ、価格、トランジットタイム、有効期限、運賃に含まれる内容。
- キャリア名がない運賃は、クライアントのロゴ付きで ”
Select” と表示されます。 - 運賃のソースやプラットフォームは一切表示されません。データがブラウザーに届く前に、当社サーバー上で削除されます。
セキュリティ
ドメインロック。 アプリページは、キーのドメインだけを列挙した Content-Security-Policy: frame-ancestors で応答するため、ブラウザーはそれ以外の場所での表示を拒否します。データリクエストにはキーと親ページのホストが含まれ、ホストがリストにない場合は拒否されます。別のサイトにコピーされたキーは、そこで動作しません。
上限。 キー上の各アプリには、それぞれ月次または年次の上限があります。利用上限 を参照してください。さらに、すべてのキーには月50,000リクエストの安全上限、サイト全体で1分600リクエストの上限があります。これにより、あるサイトのトラフィック急増が他のサイトのアプリを遅くすることを防ぎます。リクエストに応じて引き上げ可能です。また、スクリプト化された悪用に対して訪問者ごとのレート制限があります。これらを超えると、アプリは短い “もう一度お試しください” メッセージを表示し、navo:limit を発火します。
メッセージ。 フレームとローダーは postMessage で通信し、それぞれが相手の正確な origin にのみ送信します。フレームはクライアントページへ、ローダーは navo24.com へ送信します。検索詳細が * に送られることはありません。
ローテーション。 キーが漏えいした場合、またはサイトの所有者が変わった場合は、新しいキーを発行し、古いキーは即座に停止します。
公開前のテスト
本番ドメインとあわせてステージングドメインを送ってください。開発者マシン用には localhost:<port> でも構いません。どちらも同じキーに登録できます。
チェックリスト
- クライアントが、名称、ドメイン、ロゴ、カラー、ブッキングメール、購入したアプリ、AI モードのオンまたはオフ、各アプリの上限を送信します。任意で Webhook とページパスも送信します。
- 当社がキーを作成し、スニペットを送信します。
- クライアントが
embed.jsとコンテナを追加します。まずはステージングに追加します。 - クライアントが確認します: 検索 → tracking、rates → details → booking、テストメールが届くこと、共有リンクが自社サイト上で開くこと。厳格な CSP がある場合は、ブラウザーコンソールでブロックされた
navo24.comを確認します。 - クライアントが本番ドメインを追加し、まだリストにない場合、公開します。