Посібники
Застосунки 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 увімкнений або вимкнений | Так |
| Ліміт використання для кожного застосунку, на місяць або на рік | tracking: 300 унікальних відправлень на місяць | Так |
| Сторінки, на яких буде розміщено кожен застосунок | /track, /rates, /schedules | Рекомендовано |
| “Працює на Navo” показувати чи приховувати | показувати | За замовчуванням: показувати |
Ми створюємо ключ і надсилаємо фрагменти нижче, уже із заповненим ключем.
Що може містити один ключ
Ключ відкриває один або кілька застосунків, а режим AI є окремим перемикачем:
| Package | Apps on the key | What the visitor gets |
|---|---|---|
| Лише tracking | tracking | Сторінка відстеження; пошуковий віджет показує поле відстеження без вкладок і без перемикача AI |
| Tracking з AI | tracking, ai | Те саме, плюс режим AI у пошуковому віджеті та “Запитати AI” у відправленнях |
| Rates and schedules | freight, schedules | Дві вкладки в пошуковому віджеті, сторінки тарифів і розкладів |
| Усе | tracking, freight, schedules, ai | Усі три вкладки, режим AI, усі сторінки |
Віджет будується з ключа: вкладка, сторінка або кнопка AI, яку ключ не відкриває, взагалі не відмальовується, а наш сервер відхиляє її дані, навіть якщо хтось примусово надішле запит.
Ліміти використання
Кожен застосунок на ключі має власний ліміт, на календарний місяць або календарний рік (UTC). Що рахується як одна одиниця:
| App | One unit | Free repeats |
|---|---|---|
tracking | Одне унікальне відправлення (номер контейнера, бронювання або B/L) | Те саме відправлення до кінця періоду |
freight | Один пошук тарифу (напрямок і обладнання) | Той самий пошук у той самий день |
schedules | Один пошук розкладу (маршрут, судно або порт) | Той самий пошук у той самий день |
ai | Одне запитання до AI асистента | Немає |
Приклад: tracking на 300 унікальних відправлень на місяць. Відвідувачі клієнта можуть відкривати й оновлювати ці 300 відправлень скільки завгодно разів протягом місяця; відправлення 301 буде відхилене до 1 числа наступного місяця. Коли застосунок досягає ліміту, відвідувачі бачать “Зараз цей сервіс призупинено на цьому сайті. Зверніться до
Встановлення
Додайте loader один раз на кожну сторінку, де показується застосунок:
<script src="https://navo24.com/embed.js" async></script>
Потім додайте контейнер там, де має з’явитися застосунок.
Пошуковий віджет (hero на головній сторінці або будь-яка інша сторінка). Один блок із вкладкою для кожного застосунку на ключі (tracking, rates, schedules) і режимом AI, якщо ключ його має. Якщо застосунок один, вкладок немає:
<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 до обох, інакше браузер заблокує loader або фрейм, а контейнер залишиться порожнім:
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
Якщо замість frame-src використовується child-src, додайте його туди. Більше нічого не потрібно: застосунки завантажують свої дані, шрифти й мапи всередині фрейму, під нашою власною політикою. Консоль браузера показує заблоковану директиву, якщо чогось бракує.
Події для аналітики та CRM
Контейнер генерує DOM події, коли відвідувач щось робить, щоб сайт міг надіслати їх у Google Analytics, tag manager або свою CRM. Вони спливають, тож один listener на 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 | Кнопки, посилання, активні вкладки, перемикачі, focus ring. Відтінки для hover і pressed обчислюються з нього | "#e4002b" |
text | Основний текст | "#1a1a1a" |
muted | Другорядний текст: labels, підказки, дати | "#6b7280" |
heading | Заголовки, назви перевізників і суден, лінії мапи | "#002f6c" |
background | Фон сторінки застосунку. "transparent" дозволяє показати власний фон клієнта | "#ffffff" |
surface | Картки, поля введення, смуги таблиць | "#f5f7fa" |
border | Рамки та розділювачі | "#e5e7eb" |
success | Позитивні стани: доставлено, вчасно, найдешевше | "#15803d" |
radius | Заокруглення кутів карток і панелей, px (0 до 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 і Next.js, з пошуковою індексацією
Використовуйте це, коли сайт клієнта побудований на React або Next.js і вміст застосунку має індексуватися як сторінка клієнта (наприклад, сторінка для кожного напрямку, “розклад рейсів Shanghai to Hamburg”).
Це складається з двох частин:
- Знімок. Сервер клієнта забирає в нас дані напрямку як простий HTML (таблицю розкладу або тарифів, заголовок, короткий підсумок в один рядок і schema.org markup) і вставляє їх у власну сторінку. Пошукові системи індексують це як контент клієнта, на URL клієнта.
- Застосунок. У браузері інтерактивний застосунок монтується над ним, із пошуком, фільтрами, деталями та бронюванням. Знімок залишається на сторінці як згорнута таблиця під застосунком, тож crawlers і відвідувачі бачать той самий вміст.
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 minutes (Cache-Control: max-age=1800). Знімок рахується як один пошук у ліміт застосунку; той самий напрямок у той самий день безкоштовний. 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>
)}
</>
);
}
Як це виглядає для пошукової системи: власні title і description сторінки, заголовок і повна таблиця рейсів (або тарифів) у HTML, з Dataset markup. Як це виглядає для відвідувача: живий застосунок, уже відкритий на цьому напрямку, з тими самими результатами як згорнута таблиця під ним. Відвідувачі з вимкненим JavaScript бачать відкриту таблицю. Таблиця згорнута, а не прихована, тож сторінка не показує crawlers нічого такого, що відвідувач не може відкрити.
Snapshot HTML приходить із нашого сервера з екранованим кожним значенням, тому його безпечно вставляти. Стилізуйте його класами .navo-snapshot і .navo-snapshot-table, якщо він колись показується.
Інші серверні фреймворки (Remix, Astro, Nuxt, PHP, WordPress) працюють так само: отримайте знімок на сервері, виведіть html на сторінку, поставте контейнер поруч із ним.
Звичайний React (без server rendering)
Коли пошукова індексація не важлива (сторінка відстеження за меню, intranet), достатньо компонента без знімка:
Loader працює так само в 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').
Чому фрейм
Loader відмальовує кожен застосунок усередині фрейму з navo24.com. Так само працюють Stripe Checkout, вбудовування Google Maps і плеєри YouTube, з тих самих причин:
- Прив’язка до домену. Сам браузер відмовляється показувати застосунок на сайті, якого немає в списку ключа (
frame-ancestors). Script component, завантажений на сторінку клієнта, так заблокувати неможливо. - Без конфліктів стилів. CSS клієнта не може зламати застосунок, а наш CSS не може вплинути на їхній сайт.
- Оновлення без клієнта. Нові перевізники, виправлення та функції доходять до кожного сайту того самого дня; на стороні клієнта нічого не потрібно оновлювати.
- Пошукові системи. Вміст усередині фрейму не індексується як сторінка клієнта, як і будь-яка мапа чи відео, вбудовані на сайт. Коли це важливо, додайте server-rendered snapshot, див. React і Next.js, з пошуковою індексацією.
Відвідувачі не входять у систему всередині фрейму, тому блокування third-party 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 форма залишається demo і повідомляє про це.
Що бачать відвідувачі, а чого не бачать
- Назви та логотипи перевізників, ціни, transit times, строк дії та що включає тариф.
- Тарифи без названого перевізника показуються як ”
Select”, з логотипом клієнта. - Джерела тарифів і платформи ніколи не показуються. Вони видаляються на нашому сервері до того, як дані потрапляють у браузер.
Безпека
Прив’язка до домену. Сторінки застосунку відповідають з Content-Security-Policy: frame-ancestors, де перелічено лише домени ключа, тому браузер відмовляється показувати їх будь-де ще. Запити даних містять ключ і host батьківської сторінки та відхиляються, якщо host немає у списку. Ключ, скопійований на інший сайт, там не працює.
Ліміти. Кожен застосунок на ключі має власний місячний або річний ліміт (див. Ліміти використання). Крім того, кожен ключ має safety cap 50,000 запитів на місяць, стелю 600 запитів на хвилину для всього сайту (щоб сплеск трафіку одного сайту не сповільнював застосунки для інших; підвищується за запитом) і ліміти на відвідувача проти scripted abuse; понад них застосунок показує коротке повідомлення “спробуйте ще раз” і генерує navo:limit.
Повідомлення. Фрейм і loader спілкуються через postMessage, і кожна сторона надсилає лише до точного origin іншої сторони: фрейм до сторінки клієнта, loader до navo24.com. Деталі пошуку ніколи не надсилаються до *.
Ротація. Якщо ключ витік або сайт змінив власника, ми випускаємо новий ключ, а старий одразу припиняє працювати.
Тестування перед запуском
Надішліть нам staging домен разом із production доменом або localhost:<port> для машини розробника. Обидва можуть бути на одному ключі.
Чекліст
- Клієнт надсилає назву, домени, логотип, колір, e-mail для бронювань, застосунки, які він придбав (режим AI увімкнений або вимкнений), і ліміт для кожного застосунку (а також, за бажанням, webhook і шляхи сторінок).
- Ми створюємо ключ і надсилаємо фрагменти.
- Клієнт додає
embed.jsі контейнери, спочатку на staging. - Клієнт перевіряє: search → tracking, rates → details → booking (надходить тестовий e-mail), спільне посилання відкривається на їхньому сайті. Якщо CSP суворий, перевіряє консоль браузера на заблокований
navo24.com. - Клієнт додає production домен (якщо його ще немає у списку) і запускає сайт.