Modal Communication

Handle communication between your website and the Anon modal

Migration Modal Event Communication

The Anon modal uses a structured event system to communicate user interactions and modal state to the parent window when embedded as an iframe. Events are sent via window.postMessage and always include user and migration context.

Event Types & Payloads

All events have the following payload components:

Event Structure Example

{
  "id": "evt_1234567890_abc123",          // Unique identifier for the event
  "object": "event",
  "created": "2023-11-09T12:00:00.000Z",  // ISO 8601 timestamp
  "type": "migration_modal.opened",       // Event type (see table)
  "data": {
    "user_id": "123",                     // End-user ID provided at modal creation
    "migration_id": "456"       
    // Additional event-specific fields may be included
  }
}

id · string · required

Unique identifier for the event

object · string · required

Always set to "event"

created · string · required

ISO 8601 timestamp of when the event was created

type · string · required

Event type. One of: migration_modal.opened, migration_modal.completed, migration_modal.closed, migration_modal.failed, migration_modal_step.started, migration_modal_step.submitted, migration_modal_step.completed, migration_modal_step.failed

data · object · required

Event-specific data containing user and migration context

Show data

user_id · string · required

End-user ID provided at modal creation

migration_id · string · required

Migration identifier

modal_step · string

Current modal step (for migration_modal_step events). Options: welcome, provider_selection, login, mfa, company_selection, and unrecoverable_error.

error_message · string

Error description (for migration_modal.failed and migration_modal_step.failed events)

Below is a summary of all event types, when they are emitted, and their payload structure.

Event Type	When Emitted	Data Provided
migration_modal.opened	Modal first displayed	{}
migration_modal.completed	Migration successfully started	{}
migration_modal.closed	User exits before migration start	{ "modal_step": "<string>" }
migration_modal.failed	Unrecoverable error	{ "modal_step": "<string>", "error_message": "<string>" }
migration_modal_step.started	Step displayed to user	{ "modal_step": "<string>" }
migration_modal_step.submitted	User submitted step (intent)	{ "modal_step": "<string>" }
migration_modal_step.completed	Step processed successfully	{ "modal_step": "<string>" }
migration_modal_step.failed	Step failed (validation or system)	{ "modal_step": "<string>", "error_message": "<string>" }

Receiving Events in the Parent Window

To listen for modal events, add a message event listener in your parent application. Always check the event source and type:

window.addEventListener("message", (event) => {
  // You can also check: event.origin === "https://dashboard.anon.com" for extra security
  if (event.data?.source !== "anon_modal") return;

  const modalEvent = event.data.event;
  if (!modalEvent) return;

  switch (modalEvent.type) {
    case "migration_modal.opened":
      // Handle modal opened
      break;
    case "migration_modal.completed":
      // Handle migration success
      break;
    case "migration_modal.closed":
      // Handle user exit
      break;
    case "migration_modal.failed":
      // Handle unrecoverable error
      break;
    // ... handle other event types as needed
    default:
      // Unknown event
      break;
  }
});

Event Flows

Below are typical event flows for different user and system scenarios.

Successful Migration

1. migration_modal.opened

   Modal first displayed

2. migration_modal_step.started

   Step displayed to user (e.g., “welcome”)

3. migration_modal_step.submitted

   User clicks submit

4. migration_modal_step.completed

   Step processed successfully

5. migration_modal_step.started

   Next step displayed (e.g., “login”)

6. migration_modal.completed

   All steps completed - authentication workflow successful

Validation or Login Error

1. migration_modal_step.started

   Step displayed to user (e.g., “login”)

2. migration_modal_step.submitted

   User clicks submit

3. migration_modal_step.failed

   Validation error by Anon modal (e.g., “Invalid email format”)

4. migration_modal_step.submitted

   User tries again

5. migration_modal_step.failed

   Login error by service (e.g., “Wrong email / password provided”)

6. migration_modal_step.submitted

   User tries again

7. migration_modal_step.completed

   Validation & login passes

Unrecoverable Error

1. migration_modal_step.started

   Step displayed to user (e.g., “login”)

2. migration_modal_step.submitted

   User clicks submit

3. migration_modal.failed

   Internal server error - unrecoverable

---

Best Practices:

• Always verify the event source and origin.
• Use the event type and data to drive analytics, UI, or business logic.
• All events include user_id and migration_id for context.
• The event system deduplicates identical events within a 3-second window.