Skip to content

Web integration overview

Integrate Traveln into your website using one of two embeddable web products:

  • 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.

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

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

Both web embeds use a Client + Server integration to keep sensitive keys server-side:

  1. Client-side: you embed a lightweight JavaScript loader and pass your tenant slug plus safe configuration attributes.
  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.

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 both embeddables:

  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.