Event Reference

This reference provides complete documentation for all event types available in the Navi SDK, including their signatures, data payloads, and availability across different integration methods.

Event Categories

Navi SDK events are organized into two main categories:

• Activity Events - Emitted by individual activities within a care flow
• Session Events - Emitted by the overall care flow session

Activity Events

Activity events are emitted by individual activities (forms, messages, checklists, etc.) and provide real-time information about user interactions and activity state changes.

activity-ready

Emitted when an activity is fully mounted and ready for user interaction.

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.ready

activity-activate

Emitted when an activity becomes the active/focused activity in the care flow.

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.activate

activity-progress

Emitted when progress changes within an activity (forms, checklists with completion tracking).

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.progress

activity-data-change

Emitted in real-time when data values change within an activity (form field inputs, checklist items).

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.dataChange (note: camelCase conversion)

activity-complete

Emitted when an activity has been completed and submitted by the user.

Event Signature:

01

Example:

01

NaviEmbed Availability: ✅ Available as onActivityCompleted
navi.js Availability: ✅ Available as navi.activity.completed

activity-error

Emitted when an error occurs at the activity level (validation errors, submission failures).

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.error

activity-focus

Emitted when an activity gains focus (user interaction begins).

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.focus

activity-blur

Emitted when an activity loses focus (user interaction ends or moves elsewhere).

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.activity.blur

Session Events

Session events are emitted by the overall care flow session and provide information about session lifecycle, iframe management, and global state changes.

navi.session.ready

Emitted when the care flow session is fully initialized and ready for user interaction.

Event Signature:

01

Example:

01

NaviEmbed Availability: ✅ Available as onSessionReady
navi.js Availability: ✅ Available as navi.session.ready

navi.session.completed

Emitted when all activities in the care flow have been completed and the session is finished.

Event Signature:

01

Example:

01

NaviEmbed Availability: ✅ Available as onSessionCompleted
navi.js Availability: ✅ Available as navi.session.completed

navi.session.error

Emitted when a session-level error occurs (authentication failures, network issues, critical errors).

Event Signature:

01

Example:

01

NaviEmbed Availability: ✅ Available as onSessionError
navi.js Availability: ✅ Available as navi.session.error

navi.iframe.close

Emitted when the iframe should be closed or removed from the DOM.

Event Signature:

01

Example:

01

NaviEmbed Availability: ✅ Available as onIframeClose
navi.js Availability: ✅ Available as navi.iframe.close

navi.height.changed

Emitted when the iframe content height changes, allowing for dynamic iframe resizing.

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed (handled automatically)
navi.js Availability: ✅ Available as navi.height.changed (handled automatically)

navi.width.changed

Emitted when the iframe content width changes. Currently a no-op as width is handled responsively via CSS.

Event Signature:

01

Example:

01

NaviEmbed Availability: ❌ Not exposed
navi.js Availability: ✅ Available as navi.width.changed (no-op)

Integration Patterns

React Component (NaviEmbed)

The NaviEmbed React component exposes a limited subset of events via props:

01

Example Usage:

01

JavaScript SDK (navi.js)

The JavaScript SDK provides access to all event types via the .on() method:

01

Event Name Transformations

Note that some event names are transformed between internal system names and external API names:

| Internal (Portal) | External (navi.js) | External (NaviEmbed) | |-------------------|-------------------|---------------------| | navi.activity.data-change | navi.activity.dataChange | Not exposed | | activity-complete | activity-complete | onActivityCompleted |

Base Event Interfaces

All events extend these base interfaces defined in @awell-health/navi-core:

01

Security Considerations

All events are validated for origin security. Events are only processed when:

• Origin matches the expected portal domain
• Message source is identified as "navi"
• Instance ID matches a known Navi instance

Invalid events are rejected with console warnings for debugging.