Skip to content

Client integration

Traveln exposes three client-side web integration scripts:

  • Trip Planner Widget for embedded prompt capture and planner launch
  • SSO Button Widget for a single redirect CTA
  • Headless SDK for custom UI that launches Traveln flows

The iframe loaders are configured with data- attributes on the script tag. The Headless SDK is configured with Traveln.init(...).

CDN hosts

Use the CDN host for the environment you are integrating with:

Environment CDN origin
Production https://cdn.traveln.ai
Development https://dev.cdn.traveln.ai
Local http://cdn.localhost:8000

All examples below use production URLs.

Trip Planner Widget

Basic embed

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

Configuration attributes

Control the widget's behavior using data- attributes on the script tag.

Attribute Required Description
data-tenant Yes Your tenant slug (for example partnerdemo).
data-token-url No URL to your backend token endpoint. Relative URLs are resolved against the current origin. Default: /api/traveln/sso/. Recommended to set explicitly.
data-sso-login-url No Explicit Traveln SSO entrypoint. Default: window.location.origin + /sso-login/. Use this when the embed is rendered from a Traveln-hosted docs or studio page instead of the final tenant host.
data-locale No Language code such as en or ar. Default: en.
data-direction No ltr or rtl. Overrides locale-based direction.
data-iframe-height No Initial iframe height (200-2000). Default: 380.
data-widget-submit No Optional CTA button text override.
data-widget-input No Optional input placeholder override.
theme-widget-submit-bg No Optional CTA button background color (#RGB or #RRGGBB).
theme-widget-submit-text No Optional CTA button text color (#RGB or #RRGGBB).

Suggested prompts

You can pass suggested prompts by placing JSON in a script tag with id traveln-widget-prompts:

<script id="traveln-widget-prompts" type="application/json">
  ["Plan a weekend in Dubai", "Family-friendly summer trip", "Romantic 3-day getaway"]
</script>

Dynamic loading (SPA)

const script = document.createElement("script")
script.src = "https://cdn.traveln.ai/widget/v1/traveln-widget.js"
script.setAttribute("data-tenant", "your-tenant-slug")
script.setAttribute("data-token-url", "/api/traveln/sso/")
script.setAttribute("data-locale", "en")
document.body.appendChild(script)

Load on demand

Prefer loading the widget only on pages where it's needed.

Reference page: Trip Planner Widget

SSO Button Widget

Basic embed

Use the dedicated SSO button loader when you need a single CTA instead of the full planner widget:

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

Button configuration attributes

Attribute Required Description
data-tenant Yes Your tenant slug.
data-token-url No URL to your backend token endpoint. Default: /api/traveln/sso/. Recommended to set explicitly.
data-sso-login-url No Explicit Traveln SSO entrypoint. Default: window.location.origin + /sso-login/. Use this when the embed is rendered from a Traveln-hosted docs or studio page instead of the final tenant host.
data-locale No Language code. Default: en.
data-direction No ltr or rtl. Overrides locale-based direction.
data-button-type No trip_planner, trips, or accommodation_search. Default: trip_planner.
data-button-text No Optional button label override.
data-button-width No Optional button width.
data-button-height No Optional button height.
data-button-padding No Optional button padding.
data-button-margin No Optional outer embed margin.
data-button-bg No Optional button background color (#RGB or #RRGGBB).
data-button-text-color No Optional button text color (#RGB or #RRGGBB).
data-button-border-radius No Optional button border radius.
data-button-border No Optional button border, for example 1px solid #FD8559.

Supported button targets

data-button-type Destination after SSO Default label
trip_planner /ai-trip-planner/ "Generate a trip"
trips /trips/ "My Trips"
accommodation_search /accommodation-search/ "Accommodation Search"

Reference page: SSO Button Widget

Headless SDK

Use the SDK when you want to render your own UI and call Traveln programmatically.

<script src="https://cdn.traveln.ai/sdk/v1/traveln-sdk.js"></script>
<script>
  Traveln.init({
    tenant: "your-tenant-slug",
    tokenUrl: "/api/traveln/sso/",
    ssoLoginUrl: "/sso-login/",
    locale: "en"
  });

  document.querySelector("#plan-trip").addEventListener("click", () => {
    Traveln.startPlanner({
      prompt: document.querySelector("#trip-prompt").value
    });
  });
</script>

SDK methods

Method Use case
Traveln.start({ target, prompt, filters }) Generic launcher for all supported targets.
Traveln.startPlanner({ prompt }) Launch the AI trip planner.
Traveln.openTrips() Open the user's trips list.
Traveln.startAccommodationSearch({ filters }) Open accommodation search with optional filters.
Traveln.getSSOToken({ prompt }) Request a token without redirecting immediately.
Traveln.buildRedirectUrl({ token, traceId, target, prompt, filters }) Build an SSO URL from a token.

Reference page: Headless SDK