Architecture

Before wiring anything up, it helps to know exactly what you are adding to your page and where your code meets Koala. Koala Smartblock is a self-contained widget: you embed it, you talk to it through one well-defined surface, and Koala handles everything behind that surface.

The moving parts

• Your page: the page you embed the widget into, the code that reacts to it, and your own application or backend.
• The widget: a custom element, <koala-smartblock-sb4>, that renders the protection experience inside your page.
• The loader script: a small script you include that boots the widget and pulls its configuration and assets from Koala's CDN.
• Koala's CDN: serves the loader, your partner configuration (by version), and the widget's assets.
• Koala's backend: prices protection bundles for the trip (quotes) and creates policies.

Where your code meets Koala: window.CTStore

You interact with the widget through two parts of one global object:

• dataSource: the trip context you provide (currency, language, the trip, travellers). This is your data going in, and it is shared with the car-rental Smartblock.
• koala: the Koala namespace. It holds everything Koala-specific and must exist before the loader script runs (its presence is also how the widget knows it belongs on the page):
  • koala.events: callbacks the widget invokes as things happen (ready, bundle selected or declined, basket changed, errors). Signals coming out.
  • koala.basketPayload: the current basket, kept up to date for you to read. Shared state.
  • koala.restart: a runtime helper that re-initializes the widget.

You set dataSource, register handlers on koala.events, and read state from koala. You never reach into the widget itself.

note

The top-level window.CTStore.events is the shared event bus the car-rental Smartblock uses. Koala also mirrors its basket change there for pages that run both widgets, but for Koala the place to work is koala.events.

What is yours, and what is Koala's

You own:

• the page and where the widget appears (the custom element),
• providing the trip data through dataSource,
• reacting to koala.events and keeping your own UI in sync,
• the final call to Koala that creates the subscription or deletes the quote, made from your application.

Koala owns:

• the widget, its rendering, and its behaviour,
• which bundles are shown, their pricing, and their content,
• the theme and layout (configured to fit in your theme; you do not style it),
• the backend that prices bundles and issues policies.

The one experience lever you pass at runtime is context (dataSource.custom.context), which tells Koala where in the journey the widget sits, for example checkout, confirmation, or manage-booking. Everything else about the experience is configured by Koala.