Skip to content

Web integration overview

Integrate Traveln into your website using Hosted Widgets or the Headless SDK:

  • Hosted Trip Planner Widget: an embedded planning surface that collects a prompt and launches the authenticated Traveln trip planner flow.
  • Hosted Button Launchers: lightweight hosted CTAs that silently authenticate the user and redirect them to supported Traveln destinations.
  • Headless SDK: a JavaScript SDK for custom partner UI. Your page renders the controls and the SDK handles tenant config, SSO token exchange, redirects, iframe embeds, bookings, accommodation search, and OpenChat.

Choose the right embed

Product Best for User experience Docs
Hosted Trip Planner Widget Pages where users should start planning inside your site Users type a prompt into an embedded Traveln UI Hosted Trip Planner Widget
Hosted Button Launchers Landing pages, nav bars, dashboards, campaign pages, or account areas that need simple CTAs Users click a hosted button and are redirected through Traveln SSO Hosted Button Launchers
Headless SDK Fully custom pages, cards, forms, nav bars, iframe shells, and specific-chat embeds Your UI calls Traveln methods and Traveln handles SSO, routing, and embeds Headless SDK

What every web integration includes

  • A CDN bootloader script from the Traveln CDN host
  • Your tenant slug
  • A server-side token endpoint on your backend
  • Traveln tenant config served from the CDN host

The full widget also uses a container element in your page:

<div id="traveln-widget">
  <script
    src="https://cdn.traveln.ai/widget/v1/traveln-widget.js"
    data-tenant="your-tenant-slug"
    data-token-url="/api/traveln/sso/"
    data-locale="en"
  ></script>
</div>

Architecture

All web integration paths use a Client + Server integration to keep sensitive keys server-side:

  1. Client-side: you embed a lightweight JavaScript loader or SDK and pass your tenant slug plus safe configuration.
  2. Tenant config: the loader reads Traveln tenant configuration from the CDN host to resolve branding and routing details.
  3. Token exchange: the loader calls your backend endpoint (data-token-url) to request a signed SSO token.
  4. Server-side: your backend validates the user session and creates a signed token using your SSO HMAC secret.
  5. Initialization: Traveln verifies the token on /sso-login/, creates the session, and routes the user to the requested Traveln screen.

The difference between the products is ownership of the user interface and launch pattern:

  • Hosted Widgets render Traveln-owned prompt or launcher UI on the partner page.
  • The Headless SDK exposes JavaScript methods such as startPlanner, openTrips, openBookings, startAccommodationSearch, and openChat for partner-owned UI.

Prerequisites

  • Tenant slug: your organization identifier (for example partnerdemo).
  • SSO HMAC secret: used to sign SSO tokens with HMAC-SHA256.
  • HTTPS: required for secure token exchange in production.
  • Allowed web origins: your frontend origin must be permitted by Traveln so the CDN config request and iframe flow can succeed.

Start here

Common integration flow

Traveln uses the same SSO contract for iframe embeds and the SDK:

  1. Your page loads the CDN script.
  2. The CDN script reads tenant config from /widget/v1/<tenant_slug>/config.json.
  3. The CDN script calls your backend token endpoint.
  4. Traveln validates the signed token on /sso-login/.
  5. The user lands on the Traveln destination configured by the widget, button launcher, SDK redirect, SDK iframe embed, or SDK OpenChat embed.

If you want a fast implementation path, open Widget Studio first and generate the exact snippet for your use case. Then wire your backend token endpoint using the server guide.