userDidStartWatchingEvent

Indicates that a user has started watching an event and initializes the event view model.

Overview

When a user starts watching an event, call this method to initialize the necessary components for the Maestro panel and interactive features. This method creates a new event view model and establishes the connection between the SDK and your application's event delegate.

Pass a single eventId string for a standard single-event session. Pass eventId as string[] to start a multi-event session (e.g. a multiview layout with several simultaneous events); the SDK loads one page configuration per ID. The configs are kept as an ordered list (the first config is authoritative for settings that can't be merged, such as feature flags and polling intervals), not flattened into one.

Method Signature

userDidStartWatchingEvent(config: SDKEventConfigParams): Promise<IMaestroEvent>;

Parameters

Parameter	Type	Description
config	SDKEventConfigParams	A config object containing the necessary fields to properly initialize the event view model

SDKEventConfigParams Interface

export type SDKEventConfigParams = {
  /**
   * The instance of the app's implementation of IMaestroEventDelegate
   */
  delegate: IMaestroEventDelegate;
  /**
   * Page ID(s) to load page configuration(s).
   * Pass a string for a single-event session or string[] for a multi-event session.
   * When both pageId and eventId are arrays, indices correspond (same length).
   */
  pageId?: string | string[];
  /**
   * User settings for customizing SDK behavior (panel visibility, feature toggles, etc.)
   */
  userSettings?: IUserSettings;
  /**
   * Event ID(s) used as metadata to resolve and load page configuration(s).
   * Pass a string for a single-event session or string[] for a multi-event session.
   * Omit when loading by pageId alone.
   */
  eventId?: string | string[];
  /**
   * @description - Indicates whether to use the production environment for this event.
   * @default true
   */
  useProdEnv?: boolean;
};

See IMaestroEventDelegate

Return Value

A Promise that resolves to an IMaestroEvent instance, which provides methods for interacting with the current session. In a multi-event session, getCurrentEventIDs returns all active event IDs.

Examples

Single-event session

const delegate = new MyEventDelegate();

const event = await SDK.userDidStartWatchingEvent({
  eventId: 'YOUR_EVENT_ID',
  delegate,
});

Multi-event session

Pass eventId as an array to load multiple events simultaneously (e.g. for a multiview layout).

const delegate = new MyEventDelegate();

const event = await SDK.userDidStartWatchingEvent({
  eventId: ['EVENT_ID_1', 'EVENT_ID_2'],
  delegate,
});

// Retrieve all active event IDs
const ids = event.getCurrentEventIDs(); // ['EVENT_ID_1', 'EVENT_ID_2']

Using pageId

const Sidebar = () => {
  useEffect(() => {
    startWatchingEvent();
  }, []);

  async function startWatchingEvent() {
    const delegate = new MyEventDelegate();

    try {
      const event = await SDK.userDidStartWatchingEvent({
        pageId: 'YOUR_PAGE_ID',
        delegate,
      });
    } catch (error) {
      console.error("Failed to start watching event:", error);
    }
  }

  return <div id="panel" />;
};

Throws

This method rejects (the returned Promise rejects) in these cases:

• Error("siteID must be set before calling userDidStartWatchingEvent.") — if configure() was not called with a non-empty siteID first.
• Error("Either eventId or pageId must be provided to load the page configuration.") — if both eventId and pageId are omitted.
• Error("Could not determine page configuration for siteId: … pageId: … and eventId: …") — if no page configuration could be resolved for the given IDs.

Notes

• The SDK must be configured with configure() before calling this method.
• Either eventId or pageId must be provided; both cannot be omitted.
• When both pageId and eventId are arrays, their indices correspond and they should have the same length. This is a convention the SDK relies on — it is not validated at runtime.
• Calling userDidStartWatchingEvent while a session is already active refreshes the session with the new IDs: the SDK diffs the page configs, ends analytics sessions for removed pages, starts them for added pages, and reuses the existing event view model.