Communication between experience and parent site
This page describes the most common way to establish communication between the experience and the parent page.
Use Case
Communication with the parent site becomes an important requirement when you want to create a deeper integration with the parent site. This is incredibly useful when you want to:
- Add a product to cart when it was clicked on within the experience
- Open the shopping cart when it was clicked on inside the experience
- Show a notification on the parent site when a user reaches a specific room
- Reward the user with points on the parent page after collecting a star within the experience
Using postMessages to establish communication
In order to securely communicate between cross-origin frames, window.postMessage() is used. This allows bi-directional communication between the frames and allows to control what happens after a message has been received, or before the message was sent. You can read more about the window.postMessage() method here.
Sender
In most scenarios, the sender of the events will be the experience. It will send an event when:
- a user moves between panoramas
- a user hovers over an interactable element
- a user clicks on an interactable element
- a user enters a different room
- …and more.
And the event that’s sent looks like this:
{
"type": "experienceEvent",
"name": "OpenPDP",
"data": "60402",
"market": "gb",
"locale": "en",
"organization_id": ""
}Events that come from the experience will always have it’s type as 'experienceEvent' to make it easier to understand where the event is coming from. A breakdown of each property that’s sent:
type: "experienceEvent"- "
name": The name of the event. Example: OpenPDP, OpenCustomModel, etc. - "
data": The data that’s passed as the event. In case of OpenPDP, this would be the product ID that should be opened. - "
market": The market of the experience. Example: ‘gb’, ‘us’, ‘it’. - "
locale": The locale of the experience. Example : ‘en’, ‘es’, ‘it’ - "
organization_id": The organisation ID of the experience. Can be empty for the moment.
Receiver
In order to react to these messages, the receiver needs to listen to them. We will do that by adding an eventListener .
After you receive the message from the iframe, it is entirely up to you what you do with that information. In this example, if the message has a productId, we are going to add it to the cart, if not, we are going to invoke Checkout():
window.addEventListener("message", (event) => {
if (event.origin !== "your virtual experience URL")
return;
switch (event.data.name) {
case 'AddToCart':
AddToCart(event.data.data);
break;
case 'Checkout':
Checkout();
break;
}
}, false);You should now have the embedded experience and the communication between the experience and your website established!
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.