Skip to content
Navo24Navo24

Руководства

Приложения Navo на сайте клиента

Встройте отслеживание контейнеров на сайт, ставки фрахта, расписания рейсов и AI-режим под своим брендом: один тег script и ключ, привязанный к домену.

Вы можете встроить отслеживание контейнеров на собственный сайт клиента, вместе со ставками на перевозку и расписаниями судозаходов. Это те же приложения, которые вы видите на примерном сайте экспедитора: поисковый виджет для главной страницы и отдельная полноценная страница для каждого приложения. Каждое приложение отображается с названием, логотипом и цветом клиента. У каждого представления есть своя ссылка, поэтому посетитель может отправить коллеге один контейнер, один поиск ставки, одну ставку, один рейс, одно судно или один порт, и ссылка откроется на сайте клиента.

На стороне клиента не нужен ни API key, ни сервер. Ключ для встраивания публичный и работает только на доменах, которые мы для него укажем.

Что клиент отправляет нам

ItemExampleRequired
Название компании в том виде, как его должны видеть посетители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 включается отдельным переключателем:

PackageApps on the keyWhat the visitor gets
Только TrackingtrackingСтраница отслеживания; поисковый виджет показывает поле отслеживания без вкладок и без переключателя AI
Tracking с AItracking, aiТо же самое, плюс AI mode в поисковом виджете и “Спросить AI” в отправках
Ставки и расписанияfreight, schedulesДве вкладки в поисковом виджете, страницы ставок и расписаний
Всеtracking, freight, schedules, aiВсе три вкладки, AI mode, все страницы

Виджет строится на основе ключа: вкладка, страница или кнопка AI, которые ключ не открывает, вообще не отрисовываются, а наш сервер не отдает для них данные, даже если кто-то принудительно отправит запрос.

Лимиты использования

У каждого приложения на ключе есть собственный лимит, за календарный месяц или календарный год (UTC). Что считается одной единицей:

AppOne unitFree 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 во всех приложениях, чтобы перекрестные ссылки (например “Показать ставки” в рейсе или “Расписание судна” в отправке) вели на правильную страницу сайта клиента.

Параметры

AttributeWhat it does
data-navo-appsearch, tracking, freight или schedules.
data-navo-keyКлюч встраивания сайта.
data-navo-pagesJSON-карта соответствия приложения и пути страницы на сайте клиента.
data-navo-heightФиксированная высота в px. По умолчанию фрейм растет по содержимому; tracking, как полноценная карта, 680 px.
data-navo-syncoff не меняет URL страницы, пока посетитель переходит внутри приложения.
data-navo-themeJSON с цветами, шрифтами и углами, см. Внешний вид.

Сайты с 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 поймает все приложения на странице.

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.

Внешний вид

По умолчанию приложения берут фирменный цвет клиента из ключа. Чтобы точнее попасть в дизайн сайта, добавьте 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>

Каждый ключ необязателен. Некорректное значение игнорируется, остальные продолжают применяться.

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

Схема состоит из двух частей:

  1. Snapshot. Сервер клиента запрашивает у нас данные направления в виде обычного HTML (таблица расписания или ставок, заголовок, краткое описание в одну строку и разметка schema.org) и вставляет их в свою страницу. Поисковые системы индексируют это как контент клиента, на 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 считается одним поиском в лимите приложения; то же направление в тот же день бесплатно. У 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:

ViewLink
Контейнер/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

  1. Клиент отправляет название, домены, логотип, цвет, e-mail для бронирований, купленные приложения (AI mode включен или выключен) и лимит для каждого приложения (а также, при необходимости, webhook и пути страниц).
  2. Мы создаем ключ и отправляем фрагменты.
  3. Клиент добавляет embed.js и контейнеры, сначала на staging.
  4. Клиент проверяет: поиск → tracking, rates → details → booking (приходит тестовое письмо), shared link открывается на их сайте. При строгом CSP проверьте консоль браузера на заблокированный navo24.com.
  5. Клиент добавляет production-домен (если его еще нет в списке) и выходит в live.