Getting Started - Building a custom widget

A guide for developers building widgets for the Statflo platform, based on @statflo/widget-sdk.

Contents

• Overview
• Installation
• Getting started
• Creating a widget
• Events API
• Security
• Adding your widget to Statflo
• Checklist before submitting a widget

Overview

A Statflo widget is a standalone web app that runs inside the Statflo host app, embedded via an iframe. @statflo/widget-sdk is a JavaScript cross-domain widget SDK that gives your widget a clean, declarative way to talk to the host app: it syncs state updates and UI events across the iframe boundary using window.postMessage under the hood.

A widget can be built with plain JavaScript or with React.

Installation

npm install @statflo/widget-sdk
# or
yarn add @statflo/widget-sdk

Getting started

The SDK repository ships two runnable example widgets, one in React and one in vanilla JavaScript, along with a hosted playground for testing against simulated events.

React example widget

yarn --cwd examples/react install
yarn --cwd examples/react start

View it at http://localhost:3001.

Vanilla JS example widget

yarn --cwd examples/vanillajs install
yarn --cwd examples/vanillajs start

View it at http://localhost:3002.

View samples

If you need inspiration for a Widget or Sendable design, see whats possible by testing out some of our samples.

Widget playground

A live playground is available at statflo.github.io/widget-sdk/conversations for testing widgets as you build them. The suggested workflow:

1. Check the "Getting Started" guide in the left-hand navigation.
2. Open Widget Manager and add the example widgets above via Add Widget.
3. Open Conversations to view your added widgets rendered as they'd appear in the host app.
4. Open Event Manager to simulate sending events to your widgets — this is the easiest way to check your widget behaves correctly without a real Statflo environment.

Build and run the example widgets first and get comfortable with them in the playground before writing your own — it's the fastest way to understand the event flow.

Creating a widget

For full working code, see the examples directory in the SDK repo. The core pattern is the same regardless of framework: initialize the widget store, publish events to the host app, and listen for events from it.

Initializing the widget store

Vanilla JS

import useWidgetStore from "@statflo/widget-sdk";

React

Despite its name, useWidgetStore is a vanilla zustand store rather than a React hook you can call directly. Bind it to your component with zustand's useStore:

import useWidgetStore from "@statflo/widget-sdk";
import { useStore } from "zustand";

const publishEvent = useStore(useWidgetStore, (state: WidgetState) => state.publishEvent);

Publishing an event

Vanilla JS

import { WidgetEvent } from "@statflo/widget-sdk";

const { publishEvent } = useWidgetStore.getState();

publishEvent(new WidgetEvent("MESSAGE_UPDATED", "<YOUR MESSAGE>"));

React

import { WidgetEvent } from "@statflo/widget-sdk";

const publishEvent = useStore(useWidgetStore, (state: WidgetState) => state.publishEvent);

useEffect(() => {
  // This event only fires on component initialization
  publishEvent(new WidgetEvent("MESSAGE_UPDATED", "<YOUR MESSAGE>"));
}, []);

Listening to an event

Vanilla JS

useWidgetStore.subscribe((state) => {
  const latest = state.getLatestEvent();

  if (latest) {
    switch (latest.type) {
      case "MESSAGE_UPDATED":
        // ...
        break;
    }
  }
});

React

const { events, getLatestEvent } = useStore(useWidgetStore, (state) => state);

useEffect(() => {
  const latest = getLatestEvent();

  if (!latest) {
    return;
  }

  switch (latest.type) {
    case "MESSAGE_UPDATED":
      // ...
      break;
  }
}, [events]);

Events API

This is the full set of event types currently supported by Statflo. Publishing an outgoing event type outside this list won't do anything, since the host app isn't listening for it.

Outgoing events (widget → host app)

Published from the widget to trigger functionality in the host app.

type AlertDetails = {
  status: "info" | "warning" | "dark" | "light" | "white" | "neutral" | "success" | "error";
  text: string;
};

Incoming events (host app → widget)

Event types the widget can listen for.

type User = {
  carrier_id: number;
  dealer_id: number;
  email: string;
  language: string;
};

Security

Widget communication is built on window.postMessage. By default, the SDK sets the target origin to the URL you register your widget under with the Statflo API. Make sure that the registered URL matches where your widget is actually deployed.

Adding your widget to Statflo

Once your widget has been deployed and is ready to be integrated into the application, reach out to the Statflo team to have it added.

Checklist before submitting a widget

• [  ] Widget correctly handles USER_AUTHENTICATED, AUTHENTICATION_TOKEN, CURRENT_ACCOUNT_ID, and DARK_MODE
• [  ] Any API calls your widget makes are authenticated with the token from AUTHENTICATION_TOKEN
• [  ] Any outgoing events use one of the documented types (EXPAND_IFRAME, SHOW_ALERT, APPEND_MESSAGE, REPLACE_MESSAGE)
• [  ] Tested in the widget playground using the Event Manager to simulate incoming events
• [  ] Deployed, with the deployed URL ready to share with the Statflo team for registration