Events between the UI and the SDK

This page explains the events that happen between the SDK, user interface and the outside website. These events are important and can be used to build custom functionality, such as:

• Allowing user to enter a private room if they are logged in
• Collecting collectables that can be turned in for various rewards
• Showing a specific UI screen when the user reaches a specific point in the experience

And much more!

Getting Started

In order to see the events that are being sent from the SDK and the experience, you can set the debug parameter to be true, when embedding the experience via the SDK, like so:

    <script>
        window.emperiaAsyncInit = function () {
            emperia.init({
                id: "experience-root",
                experience_url: "https://experience.emperiavr.com/example/experience/experience.html",
                ui_url: "https://ui.emperiavr.com/Standard-UI/Production/2.0.0/static/",
                attach_ui: true,
                debug: true
            });
        };
    </script>

You can read more about the available parameters in the SDK page. You can also view the events being sent in this testing URL.

The next time you open up a page, you should see events being logged inside the console view, like so:

Event Structure

There are set events that get sent by default with each exprience, however you also have the option to add your own custom events through the Unreal Engine plugin. You can read about adding custom actions and models here.

Below is a table explaining the structure of the event.

Event invocation

Certain events are emitted when a certain action happens within the SDK or the experience. Below is a table explaining when each event is invoked.

How does the SDK talk to Standard-UI

• Now when the dispatcher dispatches an event dispatch({ name: "uiReady" }) , the UI on the other end is listening to it like this,
Copy

  useEffect(() => {
    const eventListener = (event: Event) => {
      const interceptedEvent = event as CustomEvent;
      const eventType = interceptedEvent.detail.name as keyof typeof eventMap;
      const eventData = interceptedEvent.detail.data;

      if (eventMap[eventType]) {
        eventMap[eventType](eventData);
      }
    };

    window.emperia?.events?.addEventListener('fromExperience', eventListener);

    return () => {
      window.emperia?.events?.removeEventListener('fromExperience', eventListener);
    };
  }, []);

• There are bunch of events that the SDK can send to the UI defined as.
Copy

  const eventMap = {
    uiReady: () => onUIReady(),
    openWelcome: () => openWelcomeModal(),
    openInstructions: () => openInstructionsModal(),
    openProduct: (productVariantId: string) => openProductModal(productVariantId),
    openInfo: (infoModalId: string) => openInfoModal(infoModalId),
    updateLanguage: () => updateLanguage(),
  };

Each of these is pretty self explanatory but for example you want to open the product Modal with a product with an id exampleId123 you would dispatch the following event from the sdk,

Copy

dispatch({ name: "openProduct", data:{ productVariantId: 'exampleId123' } });

How does the Standard-UI talk to SDK

Now why would we want the Ui layer to talk to SDK ? Well there are more than one reasons, first is to cater any kind of tracking of analytics, secondly to communicate any change in data layer i.e. change Language of the data object being sued by the UI

The data object used by UI to populate static content, such as overlay elements etc is populated by the SDK itself when initializing data elements.

• When this listener is activated from the SDK listen("fromUserInterface") the UI can then call the SDK in such way,
Copy

	window.emperia.events.dispatchEvent(
	  new CustomEvent('fromUserInterface', { detail: { name: 'changeLanguage', locale: lang } }),
	);

As you can see its dispatching an event with name fromUserInterface with the name changeLanguage and the locale it needs to be changed to.

• While the SDK is listening to this, this is how it decides which function to invoke based on incoming event request,
Copy

const detectEvent = (incomingEvent: CustomEvent) => {
  const miscMap = window.emperia.misc;
  const ecommerceMap = window.emperia.ecommerce;
  const gamificationMap = window.emperia.gamification;
  const integrationMap = window.emperia.integration;
  const languageMap = window.emperia.language;

  const eventType = incomingEvent.detail.name;
  const eventData = incomingEvent.detail.analyticObject;
  const locale = incomingEvent.detail.locale;

  if (miscMap[eventType]) {
    miscMap[eventType](eventData);
  } else if (ecommerceMap[eventType]) {
    ecommerceMap[eventType](eventData);
  } else if (gamificationMap[eventType]) {
    gamificationMap[eventType](eventData);
  } else if (integrationMap[eventType]) {
    integrationMap[eventType](eventData);
  } else if (languageMap[eventType]) {
    languageMap[eventType](locale);
  }

  const params = new URLSearchParams(location.search);
  if (params.get("debug") == null) return;
  console.log(
    `%c Recieved ${incomingEvent.detail.name} with ${JSON.stringify(
      incomingEvent
    )} object.`,
    "color: #7fb7e2"
  );
};

const listenerEventMap = {
  fromUserInterface: detectEvent,
};

export const listen = (name: string) => {
  window.emperia?.events?.addEventListener(
    name,
    listenerEventMap[name as keyof typeof listenerEventMap]
  );
};

• The function we wanted to invoke is called changeLanguage and lives in side the languageMap as,
Copy

export const Language = {
    'changeLanguage': (locale: string) => changeLanguage(locale)
}

And that is how the UI communicated to the SDK.

Use cases

You can read more about how these events can be used to communicate between the experience and the website on this page.

Help & Support

If you have questions, suggestions, or feature requests, please join the Official Emperia Discord channel!

You can find support here through private support tickets or general conversation. You will also have the opportunity to showcase your work and chat with like-minded individuals across industries using Creator Tools, Unreal Engine, those creating immersive experiences, and more!

If you prefer, you can also reach out to us via email.

On this page

• Events between the UI and the SDK
• Getting Started
• Event Structure
• Event invocation
• How does the SDK talk to Standard-UI
• How does the Standard-UI talk to SDK
• Use cases
• Help & Support