ATTENTION: This feature is currently in preview, more details can be found in this article. 


What are AddIn Events & Commands?

STREAMBOXY AddIn Events & Commands are part of the STREAMBOXY AddIns Model and allow you to react on events happing in the frontend in realtime or control the STREAMBOXY frontend from within your AddIn.


Example Use Cases are:

  • React on changed user role (attendee got promoted to speaker etc.)
  • React on changed user language
  • Navigating to a different Session (for example if you build a session scheduler)


Events & Commands are a defined way of cross iFrame Communication with the STREAMBOXY Core UI, which is required for certain actions since your AddIns are always running within an iFrame.

The communication with STREAMBOXY Core UI is handeld by subscribing to specific context events within the STREAMBOXY Core UI and sending commands to it.


You can take advantage of Events & Commands using plain JavaScript. We also provide an npm package to make integrating into STREAMBOXY as easy as possible. 



Where can I use AddIn Events & Commands

You can use STREAMBOXY AddIn Events & Command in the following platform parts:

  • Content Pages
  • Navigation Content Pages
  • Poster
  • External Tools


How to use AddIn Events & Commands?



NPM Package Usage with Angular

You will find the documentation for the npm package usage in our example with angular at the Github Repo Readme File here: 

https://github.com/streamboxy/AddIns



Sample Implementation

You will find sample implementations in addition to the concepts described in this article in our Github Repo:
https://github.com/streamboxy


I.e. Navigation to different Sessions within an event: https://github.com/streamboxy/code-samples/blob/main/control/navigate/navigate.html


Preparation of Cross-Domain Communication

Integrating into STREAMBOXY Core utilizes Cross-Domain Communication. To do this in a secure manner both STREAMBOXY Core and your AddIn need to know each other's domains. STREAMBOXY Core attaches an URL Search Parameter to every Content URL to provide a content page with its currently loaded STREAMBOXY Core origin. To access this information, our Add-In packages provides a helper class. If you use Vanilla JS, you can access the param by yourself. Please use the provided code snippets to get started.


Vanilla JS

var coreURL = getOrigin();

// Provide the currently used Streamboxy Stage URL origin, if a custom domain is used, use the custom domains URL origin
// Streamboxy Core attaches the calling CoreURL (e.g. https://stage.streamboxy.com) as search param to your provided URL
function getOrigin() {
     var params = (new URL(document.location)).searchParams;
     var encodedOrigin = params.get('origin');
     var origin = decodeURIComponent(encodedOrigin);

      return origin;
}



Register an AddIn

Before you can subscribe to new STREAMBOXY Core UI Events, you have to tell STREAMBOXY Core that your application wants to receive data. This is necessary because interaction between Core and an AddIn is conducted in a secure environment. 


In order to accomplish that, simply call the registerAddIn Method (make sure your call includes your used apiVersion - currently only "v1" is supported) or send a "Notice Event" by yourself.


Vanilla JS

var coreURL = getOrigin();

var noticeEvent = {
  type: 0
};

window.parent.postMessage(noticeEvent, coreURL);




Subscribe to STREAMBOXY Core AddIn Events

In order receive events from STREAMBOXY Core, you have to subscribe to these events.


The following Code Samples show you how to subscribe to Events in your AddIn.


STREAMBOXY AddIn Message Types

A STREAMBOXY Core Event (which is sent to your AddIn as well) always contains a message type to state which data was sent. After your Notice STREAMBOXY Core sends the current configuration (SessionStyle, Language, UserContext, SessionData) to your subscribed handlers. If a property is updated STREAMBOXY Core provides an update as well. The command type is used by your AddIn to send a command to the Core application. The following list (to be extended in the future) shows currently supported message types. You can find the identifier for VanillaJS integrations in brackets.

  • Notice (0)
  • SessionStyle (1)  

    • SessionStyle Object which will be sent by the STREAMBOXY Stage

      export class SessionStyle {
    accentColor: string;
    activeColor: string;
    activeHoverColor: string;
    backgroundColor: string;
    canvasColor: string;
    customHeaderHeight: number;
    customHeaderHtml: string;
    hoverColor: string;
    logo: string;
    logoVisible: boolean;
    modifiedUtc: string;
    textColor: string;
    textFontUrl: string;
    titleFontUrl: string;
    customPageTitle: string;
    customFavicon: string;
}


  • Language (2)
    • The Language Data is a simple LanguageTag string (f.e. 'en-US')
  • UserContext (3)
    • UserContext Object which will be sent by STREAMBOXY Stage
    • export class SessionUserContext {
    modifiedUtc: string;
    role: SessionRole;
    parentsessionRole: SessionRole;
    sessionId: string;
    sessionUserId: string;
    tenantUserId: string;
}


  • SessionData (4)
    • SessionData Object which will be sent by STREAMBOXY Stage 
    • export class SessionData {
    analyzeVideo: boolean;

    helpmenuEnabled: boolean;
    infopanelEnabled: boolean;
    documentsEnabled: boolean;
    surveyEnabled: boolean;
    surveyShowVoteCount: boolean;
    topMenuBarVisible: boolean;

    showTechCheckOnStart: boolean;

    chatEnabled: boolean;
    chatPanelOpenOnEnter: boolean;
    chatPosition: 'Left' | 'Right';

    qaEnabled: boolean;
    qaPosition: 'Left' | 'Right';

    fullscreenDisabled: boolean;

    conferenceAllowParticipantAudio: boolean;
    conferenceAllowParticipantVideo: boolean;
    conferenceAllowParticipantScreenshare: boolean;
    conferenceStartWithTileView: boolean;

    hiveEnabled: boolean;
    contentUrl: string;
    containsLivestreamOnlyUser: boolean;
    customPermissions: boolean;
    participantsVisible: boolean;
    anonymizeUsageData: boolean;
    userAggregateThreshold: number;
    description: string;
    endDateTimeUtc: string;
    hideAgendaTimes: boolean;
    modifiedUtc: string;
    saveRecording: boolean;
    showRecording: boolean;
    startMuted: boolean;
    preventLiveStreamPause: boolean;
    sessionState: SessionState;
    sessionType: SessionType;
    startDateTimeUtc: string;
    title: string;
    isMainSession: boolean;

    parentSession: {
        id: string,
        tenantId: string;
        modifiedUtc: string,
        sessionData: SessionData
    };
}


  • Command (5)
  • TenantContext (6) - only in the backstage
    • TenantContext Object which will be sent by STREAMBOXY Backstage
      export class TenantContext {
  tenantId: string;
  tenantUrl: string;
}


  • BackstageStyle (7) - only in the backstage
    • BackstageStyle Object which will be sent by STREAMBOXY Backstage
      export class BackstageStyle {
  backgroundColor: string;
  textColor: string;
  accentColor: string;
  hoverColor: string;
}




Vanilla JS

var coreURL = getOrigin();

window.addEventListener('message', (event) => {
    if (event.origin !== this._coreURL.origin) {
      throw new Error('Will not process message by unknown origin.');
    }

    switch (event.data.type) {
      case 0: {
        break;
      }
      case 1: {
       // Apply new Styling
       // Access SessionStyle Object using event.data.data
       this._styleService.update(event.data.data);
        break;
      }
      case 2: {
       // Apply new Language
       // Access Language string using event.data.data
        const langTag = event?.data.data?.split('-')[0] ?? event?.data.data;
        this._languageService.switchLanguage(langTag);

        break;
      }
      case 3: {
       // Apply new UserContext
       // Access UserContext Object using event.data.data
        this._acs.changeRole(event?.data.data?.role);

        break;
      }
      case 4: {
       // Apply new SessionData
       // Access SessionData Object using event.data.data

        this.updateConfig(event.data.data);
        break;
      }
      default: {
        break;
      }
    }

});



Send Commands to STREAMBOXY Core

You can control STREAMBOXY Core UI by sending commands to it. 


For example, you can change the users session by sending a "NavigateToSession"-Command, which is show in the code below.

The target session Ids used in this sample can also be retrieved using the STREAMBOXY API.


STREAMBOXY Command Types

STREAMBOXY Core listens to specific commands sent by your AddIn to control the Core application. The following commands are available (list to be extended in the future), you can find the required arguments in brackets.

  • NavigateToSession (sessionId)
    • The NavigateToSession Object is structured like this
    • const navigateToSessionEvent = {
  type: 5,
  data: {
    command: 0,
    args: [targetSessionId]
  }
};


  • ReadyState 
    • Special Command for STREAMBOXY Conferencing


Vanilla JS

var coreURL = getOrigin();

const targetSessionId = "<SBXSessionId>"

const navigateToSessionEvent = {
  type: 5,
  data: {
    command: 0,
    args: [targetSessionId]
  }
};

window.parent.postMessage(navigateToSessionEvent, coreURL);