Widget Integration Guide

This guide covers everything a partner development team needs to embed the WeatherIt Checkout Widget into their site.

1. Add the Script Tag

Load embed.js on any page that will contain a WeatherIt component. The script registers all three custom elements — only components present in the DOM will activate.

Production:

<script src="https://widget.weatherit.ai/embed.js" async></script>

Versioned (immutable, 1-year cache):

<script src="https://widget.weatherit.ai/v1/embed.js" async></script>

Sandbox (for testing):

<script src="https://widget-sandbox.weatherit.ai/embed.js" async></script>

📘

Always include the async attribute. The widget initialises independently and should not block page rendering.

2. Checkout Page Setup

Add two components to your checkout page — typically on the "extras" or "add-ons" step.

weatherit-widget — Protection Selector

The main component. Fetches a quote and displays protection options.

<weatherit-widget
  partner="{WEATHERIT_PARTNER_ID}"
  lat="{location.latitude}" lon="{location.longitude}"
  suburb="{location.suburb}" state="{location.state}"
  start="{booking.checkin}" end="{booking.checkout}"
  amount="{booking.total}" booking="{booking.reference}"
  type="{booking.type}" experience="{property.name}"
  product_name="{booking.productType}"
></weatherit-widget>

Attribute Reference:

Attribute-to-API Mapping:

weatherit-cart-item — Cart Line Item

A passive component that displays the selected protection as a line item in the cart sidebar. No API calls — it listens for Custom Events from weatherit-widget.

<weatherit-cart-item partner="{WEATHERIT_PARTNER_ID}"></weatherit-cart-item>

The component is hidden by default and appears when the customer selects a protection tier.

3. Confirmation Page Setup

On your booking confirmation page (a separate URL from checkout), add the confirmation component.

<weatherit-confirmation
  partner="{WEATHERIT_PARTNER_ID}"
  booking="{booking.reference}"
  policy-id="{policy.id}"
  quote-id="{quote.id}"
></weatherit-confirmation>

📘

Pass policy-id and quote-id when available. This gives the best experience — the component can show the correct state immediately without additional API calls. See the Components Reference for full state details.

4. RoomStay Integration (Event-Based)

For partners using the RoomStay SDK, the widget can receive booking data from RoomStay events instead of HTML attributes.

When it activates: If the weatherit-widget element has no booking data attributes (lat, start, etc.), it listens for RoomStay SDK events instead.

SDK event: The widget listens for the checkoutView event (camelCase, as registered via roomstay.on()).

Required event payload: The RoomStay event must include location details alongside booking data:

RoomStay HTML example:

<script src="https://widget.weatherit.ai/embed.js" async></script>

<!-- No booking attributes — widget listens for RoomStay events -->
<weatherit-widget partner="{WEATHERIT_PARTNER_ID}"></weatherit-widget>
<weatherit-cart-item partner="{WEATHERIT_PARTNER_ID}"></weatherit-cart-item>

5. Full Integration Examples

Big4 (Attribute-Based)

<script src="https://widget.weatherit.ai/embed.js" async></script>

<!-- Checkout page — Extras step -->
<weatherit-widget
  partner="{WEATHERIT_PARTNER_ID}"
  lat="{park.latitude}" lon="{park.longitude}"
  suburb="{park.suburb}" state="{park.state}"
  start="{booking.checkin}" end="{booking.checkout}"
  amount="{booking.total}" booking="{booking.reference}"
  type="camping" experience="{park.name}" product_name="{booking.siteType}"
></weatherit-widget>
<weatherit-cart-item partner="{WEATHERIT_PARTNER_ID}"></weatherit-cart-item>

<!-- Confirmation page (separate URL) -->
<weatherit-confirmation
  partner="{WEATHERIT_PARTNER_ID}"
  booking="{booking.reference}"
  policy-id="{policy.id}"
></weatherit-confirmation>

RoomStay / Daydream Island (Event-Based)

<script src="https://widget.weatherit.ai/embed.js" async></script>

<!-- Checkout page — no attributes, listens for RoomStay events -->
<weatherit-widget partner="{WEATHERIT_PARTNER_ID}"></weatherit-widget>
<weatherit-cart-item partner="{WEATHERIT_PARTNER_ID}"></weatherit-cart-item>

📘

RoomStay events must include property location (latitude, longitude, suburb, state) in the payload. The widget does not fetch location from partner config.

6. Content Security Policy

If your site uses a Content Security Policy, add these directives:

script-src: widget.weatherit.ai
connect-src: api.weatherit.ai

For sandbox testing:

connect-src: api-sandbox.weatherit.ai

7. Environments

8. Analytics

The widget fires GA4 conversion funnel events when analytics are enabled. These track the customer journey through quoting and selection:

• widget_loaded, quote_received, coverage_viewed
• coverage_selected, coverage_changed, coverage_declined
• learn_more_opened
• confirmation_upsell_shown, confirmation_upsell_clicked

All events include partner_id.

A/B testing: Append ?force_variant=challenger to the page URL to force a specific widget variant during testing.

⚠️

Visual placeholder — A screenshot or demo of the widget embedded in a checkout page will be added here.