Skip to content

Web integration overview

Integrate Traveln into your website using iframe embeds or the headless JavaScript SDK:

  • Trip Planner Widget: an embedded planning surface that collects a prompt and launches the authenticated Traveln trip planner flow.
  • SSO Button Widget: a lightweight CTA button that silently authenticates the user and redirects them to a Traveln destination such as the trip planner, trips list, or accommodation search.
  • Headless SDK: a JavaScript SDK for custom partner UI. Your page renders the controls and the SDK handles tenant config, SSO token exchange, and Traveln redirects.

Choose the right embed

Product Best for User experience Docs
Trip Planner Widget Pages where users should start planning inside your site Users type a prompt into an embedded Traveln UI Trip Planner Widget
SSO Button Widget Landing pages, nav bars, dashboards, campaign pages, or account areas that need a single CTA Users click one button and are redirected through Traveln SSO to a destination screen SSO Button Widget
Headless SDK Fully custom pages, cards, forms, or nav bars Your UI calls Traveln methods and redirects through SSO 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 two products is the user trigger:

  • The Trip Planner Widget sends a prompt and redirects into the AI trip planner flow.
  • The SSO Button Widget redirects on click using a predefined button target.
  • The Headless SDK exposes JavaScript methods such as startPlanner, openTrips, and startAccommodationSearch for custom 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 or the button.

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.