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 увімкнений або вимкненийТак
Ліміт використання для кожного застосунку, на місяць або на рікtracking: 300 унікальних відправлень на місяцьТак
Сторінки, на яких буде розміщено кожен застосунок/track, /rates, /schedulesРекомендовано
“Працює на Navo” показувати чи приховуватипоказуватиЗа замовчуванням: показувати

Ми створюємо ключ і надсилаємо фрагменти нижче, уже із заповненим ключем.

Що може містити один ключ

Ключ відкриває один або кілька застосунків, а режим AI є окремим перемикачем:

PackageApps on the keyWhat the visitor gets
Лише trackingtrackingСторінка відстеження; пошуковий віджет показує поле відстеження без вкладок і без перемикача AI
Tracking з AItracking, aiТе саме, плюс режим AI у пошуковому віджеті та “Запитати AI” у відправленнях
Rates and schedulesfreight, schedulesДві вкладки в пошуковому віджеті, сторінки тарифів і розкладів
Усеtracking, freight, schedules, aiУсі три вкладки, режим AI, усі сторінки

Віджет будується з ключа: вкладка, сторінка або кнопка AI, яку ключ не відкриває, взагалі не відмальовується, а наш сервер відхиляє її дані, навіть якщо хтось примусово надішле запит.

Ліміти використання

Кожен застосунок на ключі має власний ліміт, на календарний місяць або календарний рік (UTC). Що рахується як одна одиниця:

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

Опції

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 до обох, інакше браузер заблокує loader або фрейм, а контейнер залишиться порожнім:

script-src ... https://navo24.com;
frame-src  ... https://navo24.com;

Якщо замість frame-src використовується child-src, додайте його туди. Більше нічого не потрібно: застосунки завантажують свої дані, шрифти й мапи всередині фрейму, під нашою власною політикою. Консоль браузера показує заблоковану директиву, якщо чогось бракує.

Події для аналітики та CRM

Контейнер генерує DOM події, коли відвідувач щось робить, щоб сайт міг надіслати їх у Google Analytics, tag manager або свою CRM. Вони спливають, тож один listener на 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Кнопки, посилання, активні вкладки, перемикачі, 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”).

Це складається з двох частин:

  1. Знімок. Сервер клієнта забирає в нас дані напрямку як простий HTML (таблицю розкладу або тарифів, заголовок, короткий підсумок в один рядок і schema.org markup) і вставляє їх у власну сторінку. Пошукові системи індексують це як контент клієнта, на URL клієнта.
  2. Застосунок. У браузері інтерактивний застосунок монтується над ним, із пошуком, фільтрами, деталями та бронюванням. Знімок залишається на сторінці як згорнута таблиця під застосунком, тож 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:

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 форма залишається 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> для машини розробника. Обидва можуть бути на одному ключі.

Чекліст

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