Widgets

Axle widgets are full-viewport overlays that surface additional user experiences within your application, similar to Axle Ignition. Currently, validation is the only supported widget type - it displays a policy’s validation result to the user. Once you have a validationResult from Validate Policy, start a widget session using the Start Widget endpoint. This returns a widgetToken and a widgetUri to display to the user.

Request Sample

curl --request POST \
  --url https://sandbox.axle.insure/widgets \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "validation": {
    "enabled": true,
    "data": {
      "validationResult": "val_abcdef123456"
    }
  }
  }'

Response

{
  "success": true,
  "data": {
    "widgetToken": "ey...",
    "widgetUri": "https://widget.sandbox.axle.insure/?token=ey..."
  }
}

Appending origin or redirect URI

Before rendering the widget, your application should append either origin (for web) or redirectUri (for mobile) as a query parameter to the widgetUri. This tells the widget how to communicate back to your application on exit. Web:

https://widget.sandbox.axle.insure/?token=ey...&origin=https://example.com

Mobile:

https://widget.sandbox.axle.insure/?token=ey...&redirectUri=https://example.com/validation/redirect

Web: Display in iframe

Open iframe

Render the widgetUri (with origin appended) in an iframe set to 100% width and 100% height of the viewport. Axle handles all internal layout and scrolling, so your application doesn’t need to manage the widget’s sizing.

Listen for MessageEvent

Add an event listener on the parent window. For security, verify that the message origin is the Axle widget domain (e.g., https://widget.sandbox.axle.insure) before processing.

Process the exit event

When the user closes or exits the widget, remove the iframe (or close the modal) and return the user to the previous view.

Page with iframe and eventListener (example)

<style>
  .validation-widget {
    z-index: 999;
    position: fixed;
    left: 0;
    top: 0;
    height: 100%;
    width: 100%;
    border: none;
  }
</style>

<iframe
  src="https://widget.sandbox.axle.insure/?token=ey...&origin=https://example.com"
  class="validation-widget"
></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.origin === "https://widget.sandbox.axle.insure") {
      switch (event.data.status) {
        case "exit":
          // Remove the iframe / close the modal
          break;
      }
    }
  });
</script>

Mobile: Display in native webview

Open the widgetUri (with redirectUri appended) in a native webview. When the user exits the widget, Axle redirects to the redirectUri you provided with a status query parameter appended:

https://example.com/validation/redirect?status=exit

Your native app should catch this redirect and close the webview.

Platform	Delivery	Requires
Web (iframe)	`window.postMessage` to parent window	`origin` appended to `widgetUri`
Mobile (webview)	URL redirect	`redirectUri` appended to `widgetUri`

onExit

Emitted when the user closes or exits the widget (e.g., clicks a close button or back action). Via postMessage (web):

{
  "status": "exit"
}

Via redirect (mobile):

{redirectUri}?status=exit

When your application receives this event, it should tear down the iframe or close the webview and return the user to the previous view.

That’s it - your users can now view their validation result through Axle’s widget without leaving your application 🎉.

Home

Guides

API Reference

Advanced

Start a widget session

Appending origin or redirect URI

Web: Display in iframe

Mobile: Display in native webview

Widget events

onExit

​Start a widget session

​Appending origin or redirect URI

​Web: Display in iframe

​Mobile: Display in native webview

​Widget events

​onExit

Start a widget session

Appending origin or redirect URI

Web: Display in iframe

Mobile: Display in native webview

Widget events

onExit