Руководства
Приложения Navo на сайте клиента
Встройте отслеживание контейнеров на сайт, ставки фрахта, расписания рейсов и AI-режим под своим брендом: один тег script и ключ, привязанный к домену.
Вы можете встроить отслеживание контейнеров на собственный сайт клиента, вместе со ставками на перевозку и расписаниями судозаходов. Это те же приложения, которые вы видите на примерном сайте экспедитора: поисковый виджет для главной страницы и отдельная полноценная страница для каждого приложения. Каждое приложение отображается с названием, логотипом и цветом клиента. У каждого представления есть своя ссылка, поэтому посетитель может отправить коллеге один контейнер, один поиск ставки, одну ставку, один рейс, одно судно или один порт, и ссылка откроется на сайте клиента.
На стороне клиента не нужен ни API key, ни сервер. Ключ для встраивания публичный и работает только на доменах, которые мы для него укажем.
Что клиент отправляет нам
| Item | Example | Required |
|---|---|---|
| Название компании в том виде, как его должны видеть посетители | Acme Logistics | Да |
| Домены, на которых будут работать приложения (production, staging) | acme.com, www.acme.com, staging.acme.com | Да |
| Логотип, SVG или PNG, квадратный знак или горизонтальный вариант | https://acme.com/logo.svg | Да |
| Фирменный цвет, одно hex-значение | #0e6ba8 | Да |
| Дополнительные цвета, шрифты, скругления углов | см. Внешний вид | Необязательно |
| E-mail для получения заявок на бронирование | [email protected] | Для ставок |
| Webhook URL для заявок на бронирование (в их CRM/TMS) | https://acme.com/hooks/navo | Необязательно |
| Какие приложения нужны | любое сочетание tracking, freight, schedules; AI mode включен или выключен | Да |
| Лимит использования для каждого приложения, в месяц или в год | tracking: 300 уникальных отправок в месяц | Да |
| Страницы, на которых будет размещено каждое приложение | /track, /rates, /schedules | Рекомендуется |
| “Работает на Navo” показано или скрыто | показано | По умолчанию: показано |
Мы создаем ключ и отправляем фрагменты ниже уже с заполненным ключом.
Что может включать один ключ
Ключ открывает одно или несколько приложений, а AI mode включается отдельным переключателем:
| Package | Apps on the key | What the visitor gets |
|---|---|---|
| Только Tracking | tracking | Страница отслеживания; поисковый виджет показывает поле отслеживания без вкладок и без переключателя AI |
| Tracking с AI | tracking, ai | То же самое, плюс AI mode в поисковом виджете и “Спросить AI” в отправках |
| Ставки и расписания | freight, schedules | Две вкладки в поисковом виджете, страницы ставок и расписаний |
| Все | tracking, freight, schedules, ai | Все три вкладки, AI mode, все страницы |
Виджет строится на основе ключа: вкладка, страница или кнопка AI, которые ключ не открывает, вообще не отрисовываются, а наш сервер не отдает для них данные, даже если кто-то принудительно отправит запрос.
Лимиты использования
У каждого приложения на ключе есть собственный лимит, за календарный месяц или календарный год (UTC). Что считается одной единицей:
| App | One unit | Free repeats |
|---|---|---|
tracking | Одна уникальная отправка (номер контейнера, booking или B/L) | Та же отправка до конца периода |
freight | Один поиск ставки (направление и оборудование) | Тот же поиск в тот же день |
schedules | Один поиск расписания (маршрут, судно или порт) | Тот же поиск в тот же день |
ai | Один вопрос AI-ассистенту | Нет |
Пример: tracking с лимитом 300 уникальных отправок в месяц. Посетители клиента могут открывать и обновлять эти 300 отправок сколько угодно раз в течение месяца; отправка 301 будет отклонена до 1-го числа следующего месяца. Когда приложение достигает лимита, посетители видят “Этот сервис сейчас приостановлен на этом сайте. Пожалуйста, свяжитесь с
Установка
Разместите загрузчик один раз на каждой странице, где показывается приложение:
<script src="https://navo24.com/embed.js" async></script>
Затем добавьте контейнер там, где должно появиться приложение.
Поисковый виджет (hero-блок главной страницы или любая другая страница). Один блок со вкладкой для каждого приложения на ключе (tracking, rates, schedules) и 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 виджет отправляет посетителей на собственные страницы клиента. Без него результат открывается прямо внутри фрейма виджета.
Страница отслеживания (/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), с тремя вкладками: по маршруту, по судну, по порту:
<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, tag manager или свою CRM. События всплывают, поэтому один обработчик на document поймает все приложения на странице.
| 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.
Внешний вид
По умолчанию приложения берут фирменный цвет клиента из ключа. Чтобы точнее попасть в дизайн сайта, добавьте 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 | Кнопки, ссылки, активные вкладки, переключатели, обводка фокуса. Оттенки для hover и pressed рассчитываются от него | "#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 дает pill-форму (по умолчанию) | 6 |
font | Шрифт основного текста. Любое семейство Google Fonts загружается за вас; "system" использует системный шрифт посетителя | "Inter" |
headingFont | Шрифт заголовков, те же правила. Если не задан, заголовки используют font | "Playfair Display" |
fontCss | Ваша собственная таблица стилей шрифта (https:// URL с правилами @font-face), для шрифтов, которых нет в 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"}'
Одна тема для всех страниц. Мы также можем сохранить тему на ключе. Тогда каждый контейнер на каждой странице получит ее без атрибута, а мы сможем позже скорректировать ее без изменений на сайте клиента. data-navo-theme на контейнере все равно имеет приоритет над темой ключа, ключ за ключом.
Тема доходит только до приложения внутри фрейма: она никогда не меняет собственную страницу клиента.
React and Next.js, с индексацией в поиске
Используйте этот вариант, когда сайт клиента построен на React или Next.js, и контент приложения должен индексироваться как страница клиента (например, отдельная страница по направлению, “Shanghai to Hamburg sailing schedule”).
Схема состоит из двух частей:
- Snapshot. Сервер клиента запрашивает у нас данные направления в виде обычного HTML (таблица расписания или ставок, заголовок, краткое описание в одну строку и разметка schema.org) и вставляет их в свою страницу. Поисковые системы индексируют это как контент клиента, на 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 считается одним поиском в лимите приложения; то же направление в тот же день бесплатно. У tracking нет snapshot: отправки являются приватными для посетителя.
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>
)}
</>
);
}
Как это выглядит для поисковой системы: собственные title и description страницы, заголовок и полная таблица рейсов (или ставок) в HTML, с разметкой Dataset. Как это выглядит для посетителя: живое приложение, уже открытое на этом направлении, с теми же результатами в свернутой таблице под ним. Посетители без JavaScript видят открытую таблицу. Таблица свернута, а не скрыта, поэтому страница не показывает краулерам ничего, что посетитель не может открыть.
Snapshot HTML приходит с нашего сервера с экранированием всех значений, поэтому его безопасно вставлять. Если он когда-либо отображается, стилизуйте его классами .navo-snapshot и .navo-snapshot-table.
Другие серверные фреймворки (Remix, Astro, Nuxt, PHP, WordPress) работают так же: получите snapshot на сервере, выведите html на страницу, поставьте контейнер рядом с ним.
Обычный React (без server rendering)
Когда индексация в поиске не важна (страница отслеживания за меню, intranet), достаточно компонента без snapshot:
Загрузчик работает так же в single-page app (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').
Почему фрейм
Загрузчик отрисовывает каждое приложение внутри фрейма с navo24.com. Так же работают Stripe Checkout, встраивания Google Maps и плееры YouTube, по тем же причинам:
- Привязка к домену. Браузер сам отказывается показывать приложение на сайте, которого нет в списке ключа (
frame-ancestors). Скриптовый компонент, загруженный на страницу клиента, так заблокировать нельзя. - Нет конфликтов стилей. CSS клиента не может сломать приложение, а наш CSS не может затронуть их сайт.
- Обновления без клиента. Новые перевозчики, исправления и функции доходят до всех сайтов в тот же день; на стороне клиента ничего обновлять не нужно.
- Поисковые системы. Контент внутри фрейма не индексируется как страница клиента, как и любое встраивание карты или видео. Когда это важно, добавьте snapshot с server-rendering, см. React and Next.js, с индексацией в поиске.
Посетители не входят в аккаунт внутри фрейма, поэтому блокировка сторонних cookies в браузере на него не влияет.
Ссылки на одно точное представление
Пока посетитель работает в приложении, 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 |
| Одна ставка | поиск выше плюс %26quote%3D<id> |
| Поиск рейсов по направлению | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| Один рейс | поиск выше плюс %26sailing%3D<id> |
| Судно | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| Порт | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
Ссылка на ставку или рейс продолжает открываться после того, как элемент ушел из live-результатов; он показывается с датой, на которую были взяты его данные.
Заявки на бронирование
Забронировать на ставке открывает форму заявки (контакт, компания, e-mail, телефон, количество контейнеров, дата готовности груза, груз, примечания). При отправке:
- e-mail уходит на адрес клиента для бронирований, с маршрутом, оборудованием, перевозчиком, ценой, которую видел посетитель, и контактными данными посетителя. Reply-To это посетитель, поэтому клиент отвечает прямо из своего почтового ящика;
- если настроен webhook, та же заявка отправляется в него методом POST как JSON:
{
"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. Оплата не списывается, бронирование у перевозчика не создается: клиент подтверждает место и отвечает сам.
Без e-mail для бронирований или webhook форма остается демонстрационной и сообщает об этом.
Что посетители видят и чего не видят
- Названия и логотипы перевозчиков, цены, transit times, срок действия и что включено в ставку.
- Ставки без указанного перевозчика показываются как ”
Select”, с логотипом клиента. - Источники ставок и платформы никогда не показываются. Они удаляются на нашем сервере до того, как данные попадают в браузер.
Безопасность
Привязка к домену. Страницы приложения отвечают с Content-Security-Policy: frame-ancestors, где перечислены только домены ключа, поэтому браузер отказывается показывать их где-либо еще. Запросы данных передают ключ и хост родительской страницы и отклоняются, если хоста нет в списке. Ключ, скопированный на другой сайт, там не работает.
Лимиты. У каждого приложения на ключе есть собственный месячный или годовой лимит (см. Лимиты использования). Кроме того, у каждого ключа есть защитный лимит 50,000 запросов в месяц, потолок 600 запросов в минуту для всего сайта (чтобы всплеск трафика одного сайта не замедлял приложения для других; поднимается по запросу) и лимиты на посетителя против скриптовых злоупотреблений; при превышении приложение показывает короткое сообщение “попробуйте еще раз” и генерирует navo:limit.
Сообщения. Фрейм и загрузчик общаются через postMessage, и каждая сторона отправляет сообщения только на точный origin другой стороны: фрейм на страницу клиента, загрузчик на navo24.com. Детали поиска никогда не отправляются в *.
Ротация. Если ключ утек или сайт перешел к другому владельцу, мы выпускаем новый ключ, а старый сразу перестает работать.
Тестирование перед запуском
Отправьте нам staging-домен вместе с production-доменом или localhost:<port> для машины разработчика. Оба могут находиться на одном ключе.
Checklist
- Клиент отправляет название, домены, логотип, цвет, e-mail для бронирований, купленные приложения (AI mode включен или выключен) и лимит для каждого приложения (а также, при необходимости, webhook и пути страниц).
- Мы создаем ключ и отправляем фрагменты.
- Клиент добавляет
embed.jsи контейнеры, сначала на staging. - Клиент проверяет: поиск → tracking, rates → details → booking (приходит тестовое письмо), shared link открывается на их сайте. При строгом CSP проверьте консоль браузера на заблокированный
navo24.com. - Клиент добавляет production-домен (если его еще нет в списке) и выходит в live.