Skip to content
Navo24Navo24

راهنماها

جاسازی اپ‌های Navo در سایت مشتری

ردیابی کانتینر را در وب‌سایت خود جاسازی کنید، همراه با نرخ حمل، برنامه حرکت کشتی و حالت AI، با برند خودتان، یک تگ اسکریپت و کلید قفل‌شده روی دامنه.

می‌توانید رهگیری کانتینر را در وب‌سایت خود مشتری جاسازی کنید، همراه با نرخ‌های حمل و برنامه‌های حرکت کشتی. این‌ها همان اپ‌هایی هستند که در سایت نمونه فورواردر می‌بینید: یک ویجت جست‌وجو برای صفحه اصلی، به‌علاوه یک صفحه کامل برای هر اپ. هرکدام با نام، لوگو و رنگ مشتری نمایش داده می‌شود. هر نما لینک اختصاصی خودش را دارد، بنابراین بازدیدکننده می‌تواند یک کانتینر، یک جست‌وجوی نرخ، یک نرخ، یک حرکت کشتی، یک کشتی یا یک بندر را برای همکارش بفرستد و همان مورد روی سایت مشتری باز می‌شود.

در سمت مشتری نیازی به API key یا سرور نیست. کلید embed عمومی است و فقط روی دامنه‌هایی کار می‌کند که برای آن ثبت کرده‌ایم.

مشتری چه چیزهایی برای ما می‌فرستد

موردمثالالزامی
نام شرکت، همان‌طور که بازدیدکنندگان باید ببینندAcme Logisticsبله
دامنه‌هایی که اپ‌ها روی آن‌ها اجرا می‌شوند (production, staging)acme.com, www.acme.com, staging.acme.comبله
لوگو، SVG یا PNG، نشان مربعی یا افقیhttps://acme.com/logo.svgبله
رنگ برند، یک مقدار hex#0e6ba8بله
رنگ‌های بیشتر، فونت‌ها، گردی گوشه‌هاببینید ظاهر و حساختیاری
ایمیلی که درخواست‌های رزرو را دریافت می‌کند[email protected]برای نرخ‌های حمل
Webhook URL برای درخواست‌های رزرو (به CRM/TMS آن‌ها)https://acme.com/hooks/navoاختیاری
کدام اپ‌ها را می‌خواهندهرکدام از tracking, freight, schedules؛ حالت AI روشن یا خاموشبله
محدودیت مصرف برای هر اپ، ماهانه یا سالانهtracking: 300 محموله یکتای ماهانهبله
صفحاتی که هر اپ در آن قرار می‌گیرد/track, /rates, /schedulesپیشنهادی
نمایش یا مخفی‌بودن “Powered by Navo”نمایش داده شودپیش‌فرض: نمایش داده شود

ما کلید را می‌سازیم و اسنیپت‌های زیر را با کلید تکمیل‌شده ارسال می‌کنیم.

یک کلید چه چیزهایی را می‌تواند شامل شود

یک کلید یک یا چند اپ را باز می‌کند، و حالت AI یک سوییچ جداگانه است:

پکیجاپ‌های روی کلیدچیزی که بازدیدکننده دریافت می‌کند
فقط Trackingtrackingصفحه Tracking؛ ویجت جست‌وجو فقط کادر tracking را بدون تب و بدون سوییچ AI نشان می‌دهد
Tracking با AItracking, aiهمان مورد، به‌علاوه حالت AI در ویجت جست‌وجو و “پرسش از AI” روی محموله‌ها
Rates و schedulesfreight, schedulesدو تب در ویجت جست‌وجو، صفحات rates و schedules
همه‌چیزtracking, freight, schedules, aiهر سه تب، حالت AI، همه صفحات

ویجت از روی کلید ساخته می‌شود: تب، صفحه یا دکمه AI که کلید آن را باز نمی‌کند اصلاً رسم نمی‌شود، و سرور ما حتی اگر کسی درخواست را به‌اجبار بفرستد، داده آن را رد می‌کند.

محدودیت‌های مصرف

هر اپ روی یک کلید محدودیت خودش را دارد، برای هر ماه تقویمی یا هر سال تقویمی (UTC). چیزی که یک واحد حساب می‌شود:

اپیک واحدتکرارهای رایگان
trackingیک محموله یکتا (شماره کانتینر، booking یا B/L)همان محموله تا پایان دوره
freightیک جست‌وجوی نرخ (مسیر و تجهیز)همان جست‌وجو در همان روز
schedulesیک جست‌وجوی برنامه حرکت (مسیر، کشتی یا بندر)همان جست‌وجو در همان روز
aiیک سؤال از دستیار AIندارد

مثال: tracking با 300 محموله یکتای ماهانه. بازدیدکنندگان مشتری می‌توانند آن 300 محموله را در تمام ماه هرچقدر خواستند باز کنند و refresh کنند؛ محموله 301 تا روز 1 ماه بعد رد می‌شود. وقتی یک اپ به محدودیت خود می‌رسد، بازدیدکنندگان می‌بینند “این سرویس فعلاً در این سایت متوقف شده است. لطفاً با تماس بگیرید.” اپ‌های دیگر روی همان کلید همچنان کار می‌کنند. ما مصرف را برای هر اپ می‌بینیم و می‌توانیم هر لحظه محدودیت را بالا ببریم، بدون هیچ تغییری روی سایت مشتری.

نصب

loader را یک‌بار روی هر صفحه‌ای که یک اپ را نشان می‌دهد قرار دهید:

<script src="https://navo24.com/embed.js" async></script>

سپس یک container در جایی که اپ باید نمایش داده شود.

ویجت جست‌وجو (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 ویجت بازدیدکنندگان را به صفحات خود مشتری می‌فرستد. بدون آن، نتیجه داخل همان frame ویجت باز می‌شود.

صفحه Tracking (/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 استفاده کنید تا cross-linkها (برای مثال “نمایش نرخ‌ها” روی یک حرکت کشتی، یا “برنامه کشتی” روی یک محموله) روی صفحه درست سایت مشتری فرود بیایند.

گزینه‌ها

Attributeکاری که انجام می‌دهد
data-navo-appsearch, tracking, freight یا schedules.
data-navo-keyکلید embed سایت.
data-navo-pagesنگاشت JSON از اپ به مسیر صفحه روی سایت مشتری.
data-navo-heightارتفاع ثابت بر حسب px. به‌صورت پیش‌فرض frame با محتوایش رشد می‌کند؛ 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 یا frame را مسدود می‌کند و container خالی می‌ماند:

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

اگر به‌جای frame-src از child-src استفاده می‌شود، آن را همان‌جا اضافه کنید. چیز دیگری لازم نیست: اپ‌ها داده‌ها، فونت‌ها و نقشه‌هایشان را داخل frame و تحت policy خود ما بارگذاری می‌کنند. اگر موردی جا افتاده باشد، console مرورگر نام directive مسدودشده را نشان می‌دهد.

رویدادها برای analytics و CRM

وقتی بازدیدکننده کاری انجام می‌دهد، container رویدادهای DOM را fire می‌کند تا سایت بتواند آن‌ها را به Google Analytics، یک tag manager یا CRM خودش بفرستد. این رویدادها bubble می‌شوند، پس یک listener روی document همه اپ‌های صفحه را می‌گیرد.

Eventزمانevent.detail
navo:searchیک جست‌وجو نتیجه برگرداندapp (tracking, freight, schedules) و query: 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 را به container اضافه کنید: رنگ‌ها، فونت‌ها، گردی گوشه‌ها و حالت تیره.

<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چه چیزی را تغییر می‌دهدمثال
accentدکمه‌ها، لینک‌ها، تب‌های فعال، سوییچ‌ها، focus ring. سایه‌های hover و pressed از روی آن محاسبه می‌شوند"#e4002b"
textمتن اصلی"#1a1a1a"
mutedمتن ثانویه: labelها، hintها، تاریخ‌ها"#6b7280"
headingheadingها، نام carrier و vessel، خطوط نقشه"#002f6c"
backgroundپس‌زمینه صفحه اپ. "transparent" اجازه می‌دهد پس‌زمینه خود مشتری دیده شود"#ffffff"
surfaceکارت‌ها، inputها، stripeهای جدول"#f5f7fa"
borderborderها و جداکننده‌ها"#e5e7eb"
successوضعیت‌های مثبت: تحویل‌شده، به‌موقع، ارزان‌ترین"#15803d"
radiusگردی گوشه کارت‌ها و panelها، px (0 تا 40)8
buttonRadiusگردی گوشه دکمه‌ها و inputها، px. 999 شکل pill می‌دهد (پیش‌فرض)6
fontفونت بدنه. هر خانواده Google Fonts برای شما بارگذاری می‌شود؛ "system" از فونت سیستم بازدیدکننده استفاده می‌کند"Inter"
headingFontفونت headingها، با همان قواعد. اگر نباشد headingها از font استفاده می‌کنند"Playfair Display"
fontCssstylesheet فونت خودتان (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"}'

یک theme برای همه صفحات. می‌توانیم theme را روی خود کلید هم ذخیره کنیم. در این حالت هر container روی هر صفحه آن را بدون attribute می‌گیرد، و ما می‌توانیم بعداً بدون تغییر در سایت مشتری آن را تنظیم کنیم. data-navo-theme روی یک container همچنان نسبت به theme کلید اولویت دارد، کلید به کلید.

theme فقط به اپ داخل frame می‌رسد: هرگز صفحه خود مشتری را تغییر نمی‌دهد.

React و Next.js، همراه با search indexing

وقتی سایت مشتری با React یا Next.js ساخته شده و محتوای اپ باید به‌عنوان صفحه خود مشتری index شود، از این روش استفاده کنید (برای مثال، یک صفحه برای هر lane، “Shanghai to Hamburg sailing schedule”).

این روش دو بخش دارد:

  1. Snapshot. سرور مشتری داده‌های lane را از ما به‌صورت HTML ساده می‌گیرد (جدول schedule یا rate، یک heading، یک خلاصه یک‌خطی و markup مربوط به schema.org) و آن را داخل صفحه خودش قرار می‌دهد. موتورهای جست‌وجو آن را به‌عنوان محتوای مشتری، روی URL مشتری index می‌کنند.
  2. App. در مرورگر، اپ تعاملی بالای آن mount می‌شود، با جست‌وجو، فیلترها، جزئیات و booking. snapshot به‌صورت یک جدول جمع‌شونده زیر اپ روی صفحه می‌ماند، بنابراین crawlerها و بازدیدکنندگان همان محتوا را می‌بینند.

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 برای body. پاسخ می‌تواند 30 دقیقه cache شود (Cache-Control: max-age=1800). یک snapshot به‌عنوان یک جست‌وجو در برابر محدودیت اپ حساب می‌شود؛ همان lane در همان روز رایگان است. 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>
      )}
    </>
  );
}

این برای موتور جست‌وجو چگونه دیده می‌شود: عنوان و توضیح خود صفحه، یک heading و یک جدول کامل از sailings (یا rates) در HTML، همراه با markup از نوع Dataset. برای بازدیدکننده چگونه دیده می‌شود: اپ زنده، از قبل روی همان lane باز شده، با همان نتایج به‌صورت یک جدول تاخورده زیر آن. بازدیدکنندگانی که JavaScript خاموش دارند جدول باز را می‌بینند. جدول تاخورده است، نه مخفی، بنابراین صفحه چیزی را به crawlerها نشان نمی‌دهد که بازدیدکننده نتواند باز کند.

HTML مربوط به snapshot از سرور ما با همه مقدارها به‌صورت escaped می‌آید، بنابراین درج آن ایمن است. اگر زمانی نمایش داده شد، با کلاس‌های .navo-snapshot و .navo-snapshot-table به آن style بدهید.

فریم‌ورک‌های سرور دیگر (Remix, Astro, Nuxt, PHP, WordPress) هم به همین شکل کار می‌کنند: snapshot را روی سرور fetch کنید، html را داخل صفحه چاپ کنید و container را کنار آن بگذارید.

React ساده (بدون server rendering)

وقتی search indexing مهم نیست (یک صفحه tracking پشت منو، یک intranet)، component بدون snapshot کافی است:

loader در یک single-page app هم به همین شکل کار می‌کند (React, Vue, Svelte): container را render کنید، سپس 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').

چرا frame

loader هر اپ را داخل یک frame از navo24.com رسم می‌کند. Stripe Checkout، embedهای Google Maps و playerهای YouTube هم به همین شکل کار می‌کنند، به همان دلایل:

  • قفل دامنه. خود مرورگر اجازه نمی‌دهد اپ روی سایتی نمایش داده شود که در لیست کلید نیست (frame-ancestors). یک script component که داخل صفحه مشتری بارگذاری می‌شود را نمی‌توان این‌طور قفل کرد.
  • بدون تداخل style. CSS مشتری نمی‌تواند اپ را خراب کند و CSS ما نمی‌تواند سایت آن‌ها را لمس کند.
  • به‌روزرسانی بدون مشتری. carrierهای جدید، اصلاحات و قابلیت‌ها همان روز به همه سایت‌ها می‌رسند؛ در سمت مشتری چیزی برای upgrade وجود ندارد.
  • موتورهای جست‌وجو. محتوای داخل frame به‌عنوان صفحه مشتری index نمی‌شود، درست مثل هر embed نقشه یا ویدئو. وقتی این موضوع مهم است، snapshot رندرشده روی سرور را اضافه کنید، ببینید React و Next.js، همراه با search indexing.

بازدیدکنندگان داخل frame وارد حساب کاربری نمی‌شوند، بنابراین مسدودسازی cookieهای third-party در مرورگر روی آن اثری ندارد.

لینک به یک نمای دقیق

وقتی بازدیدکننده در یک اپ کار می‌کند، URL صفحه همراه او تغییر می‌کند: ?navo_app=<app>&navo=<view>. دکمه‌های کپی لینک داخل اپ‌ها همین نوع لینک را تولید می‌کنند. مثال‌ها روی صفحه مشتری /rates:

نمالینک
یک کانتینر/track?navo_app=tracking&navo=ref%3DZMOU8956106
جست‌وجوی نرخ روی یک lane/rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC
یک نرخجست‌وجوی بالا به‌علاوه %26quote%3D<id>
جست‌وجوی sailing روی یک lane/schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM
یک sailingجست‌وجوی بالا به‌علاوه %26sailing%3D<id>
یک کشتی/schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890
یک بندر/schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN

یک rate یا sailing اشتراک‌گذاری‌شده حتی بعد از خارج‌شدن از نتایج live همچنان باز می‌شود؛ با تاریخی نمایش داده می‌شود که داده آن گرفته شده بود.

درخواست‌های رزرو

رزرو روی یک rate فرم درخواست را باز می‌کند (contact, company, e-mail, phone, number of containers, cargo-ready date, cargo, notes). هنگام submit:

  • یک ایمیل به آدرس booking مشتری می‌رود، شامل مسیر، تجهیز، carrier، قیمتی که بازدیدکننده دیده و جزئیات تماس بازدیدکننده. Reply-To خود بازدیدکننده است، بنابراین مشتری مستقیم از mailbox خودش پاسخ می‌دهد؛
  • اگر 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" }
  }
}

بازدیدکننده یک تأییدیه همراه با reference می‌بیند. هیچ مبلغی دریافت نمی‌شود و هیچ booking نزد carrier انجام نمی‌شود: مشتری فضا را تأیید می‌کند و پاسخ می‌دهد.

بدون ایمیل booking یا webhook، فرم در حالت demo می‌ماند و همین را اعلام می‌کند.

بازدیدکنندگان چه می‌بینند، و چه نمی‌بینند

  • نام و لوگوی carrierها، قیمت‌ها، زمان‌های transit، اعتبار و اینکه یک rate شامل چه چیزهایی است.
  • نرخ‌هایی که carrier مشخص ندارند به‌صورت ” Select” نمایش داده می‌شوند، با لوگوی مشتری.
  • منابع و پلتفرم‌های rate هرگز نمایش داده نمی‌شوند. قبل از رسیدن داده به مرورگر، آن‌ها را روی سرور خودمان حذف می‌کنیم.

امنیت

قفل دامنه. صفحات اپ با Content-Security-Policy: frame-ancestors پاسخ می‌دهند و فقط دامنه‌های کلید را لیست می‌کنند، بنابراین مرورگر اجازه نمی‌دهد آن‌ها جای دیگری نمایش داده شوند. درخواست‌های داده کلید و host صفحه parent را همراه دارند و وقتی host در لیست نباشد رد می‌شوند. کلیدی که در سایت دیگری کپی شود آنجا کار نمی‌کند.

محدودیت‌ها. هر اپ روی یک کلید محدودیت ماهانه یا سالانه خودش را دارد (ببینید محدودیت‌های مصرف). علاوه بر آن، هر کلید یک سقف ایمنی 50,000 درخواست در ماه دارد، سقف 600 درخواست در دقیقه برای کل سایت (تا spike ترافیک یک سایت نتواند اپ‌ها را برای دیگران کند کند؛ با درخواست افزایش می‌یابد) و محدودیت‌های rate برای هر بازدیدکننده در برابر سوءاستفاده اسکریپتی؛ بالاتر از این‌ها اپ یک پیام کوتاه “دوباره تلاش کنید” نشان می‌دهد و navo:limit را fire می‌کند.

پیام‌ها. frame و loader از طریق postMessage با هم حرف می‌زنند، و هر طرف فقط به origin دقیق طرف مقابل ارسال می‌کند: frame به صفحه مشتری، loader به navo24.com. جزئیات جست‌وجو هرگز به * فرستاده نمی‌شود.

چرخش کلید. اگر کلیدی leak شود یا مالکیت سایتی تغییر کند، ما کلید جدیدی صادر می‌کنیم و کلید قبلی بلافاصله از کار می‌افتد.

تست پیش از launch

دامنه staging را همراه با دامنه production برای ما بفرستید، یا localhost:<port> را برای ماشین توسعه‌دهنده. هر دو می‌توانند روی همان کلید باشند.

چک‌لیست

  1. مشتری نام، دامنه‌ها، لوگو، رنگ، ایمیل booking، اپ‌هایی که خریده (حالت AI روشن یا خاموش) و محدودیت هر اپ را می‌فرستد (و در صورت نیاز webhook و مسیر صفحات).
  2. ما کلید را می‌سازیم و اسنیپت‌ها را ارسال می‌کنیم.
  3. مشتری embed.js و containerها را اضافه می‌کند، ابتدا روی staging.
  4. مشتری بررسی می‌کند: search → tracking، rates → details → booking (یک ایمیل تست می‌رسد)، یک لینک اشتراک‌گذاری‌شده روی سایت خودش باز می‌شود. با CSP سخت‌گیرانه، console مرورگر را برای navo24.com مسدودشده بررسی کنید.
  5. مشتری دامنه production را اضافه می‌کند (اگر هنوز در لیست نیست) و live می‌شود.