SpatialChat iFrame API

 

SpatialChat allows to embed websites in a room using the iframe element.

A website loaded in an embedded iframe can communicate with SpatialChat via the SpatialChat iframe API, which allows the website to get information about the current space and room, or about the user.

Further in this document we will use terms: host - for a SpatialChat room. iframe - for a site embedded in SpatialChat room iframe.

Communication technology

window.postMessage() api (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) is used as a communication channel. 

Both host and iframe can listen and post messages. Iframe can post messages to window.parent or window.opener

API Surface

Messages are exchanged in a form of JSON object (no need to serialize manually) of a following format:

{
	name: string, // restricted to a list of supported message names,
  requestId?: string // optional id to match request message with response
	data: any // any payload corresponding to the message name
}

Workflow

  1. Host subscribes to iframe messages as soon as iframe is added.
  2. Iframe sends any available message.
  3. Host responds to incoming messages by sending appropriate message back.

Available API Methods

1. Request: get_space_ids

data: undefined

Send this message wherever you want to know which space and room iframe is embedded into. Do not call this multiple times unless necessary, cache the result, it never changes within a session.

Response: space_ids

data: { spaceId: string, roomId: string, spaceSlug: string }

This is a response message to get_space_ids

2. Request: get_user_info

data: undefined

Send this message wherever you want to know the current space user info. User can change this data within a session.

Response: user_info

data: { name?: string, about?: string, pronoun?: string, avatarUrl?: string }

This is a response message to get_user_info

API usage example

Request: get_user_info

postMessage(
 {
  name: 'get_user_info',
  requestId: 'qwe123' // optional
 },
 '<https://app.spatial.chat>'
)

Response: user_info

{
 name: 'user_info',
 requestId: 'qwe123' // in case the requestId was received in the request.
 data: {
   name?: string
   about?: string
   pronoun?: string
   avatarUrl?: string
 }
}

Security considerations

  1. Make sure the target window is window.parent or window.opener.
  2. Always set postMessage’s 2nd parameter targetOrigin. Iframe should set 'https://app.spatial.chat'.
  3. Do not use postMessage’s 3rd parameter transfer.
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.