WebXDCWebXDC docs: https://webxdc.org/docs/ is a specification for sharing interactive embeddable widgets built with web-like technologies (HTML, JavaScript) via a chat platform, and sharing state between participants in the chat without allowing external network connections for the sandboxed web content. In order to provide support for WebXDCWebXDC docs: https://webxdc.org/docs/ widgets, the host protocol (XMPP in our case) must define a way to transmit these widgets and the associated state updates.
This specification uses some terminology defined below:
widget: the WebXDC widget delivered in a zip container as defined by WebXDCWebXDC docs: https://webxdc.org/docs/
host application: the XMPP client embedding the widget
peer: the chat partner in a 1:1 chat or one of the participants of a Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>. or other group chat
host protocol: the protocol used by the peers to communicate (XMPP in our case)
A widget may be attached to a message using any file-transfer mechanism supported by the client, such as Out-of-Band Data (XEP-0066)XEP-0066: Out of Band Data <https://xmpp.org/extensions/xep-0066.html>. or Stateless Inline Media Sharing (XEP-0385)XEP-0385: Stateless Inline Media Sharing (SIMS) <https://xmpp.org/extensions/xep-0385.html>.. The message MUST contain a <thread/> element with a new, unique id. Note: including multiple file-transfer mechanisms in the same message may be beneficial for broader compatibility.
When a widget needs to communicate an update to peers in a chat, this update may contain one or more of the following items as defined in WebXDCWebXDC sendUpdate: https://webxdc.org/docs/spec/sendUpdate.html.
Item
Description
info
Human readable message to send to the chat
summary
Text which may be shown next to the widget launcher
document
Title which may be shown next to the widget launcher
payload
Arbitrary JSON serializable value
These items are delivered in a message which MUST have the same <thread> as the message which originally delivered the widget itself. The stanza SHOULD contain a x child having the urn:xmpp:webxdc:0 namespace, with these items (except for info) as children, as defined below.
The info item is human-readable and is not needed by the widget itself, thus it is appropriate to transmit it anywhere that it might be visible to all participants, such as in a message body. If this is the only item present, an empty <x> element SHOULD still be included in the message to signal this update came from the widget.
018fe972-ea89-7f4b-90f8-729b85b7f32d
Juliet has added an event.
]]>
These items are delivered as children of the <x> item, and in the same namespace. The document item using a <document> child and the summary item using a <summary> child.
The payload item is delivered using JSON Containers (XEP-0335)XEP-0335: JSON Containers <https://xmpp.org/extensions/xep-0335.html>. as a child of the <x> element
018fe972-ea89-7f4b-90f8-729b85b7f32d{}
]]>
WebXDCWebXDC selfAddr and selfName: https://webxdc.org/docs/spec/selfAddr_and_selfName.html widgets get various data injected into them by the host application. One of these worth mentioning is the selfAddr property.
When the chat is a 1:1 chat this property SHOULD be set to the XMPP URI for the local party's bare Jabber ID e.g. xmpp:juliet@capulet.lit
When the chat supports Anonymous unique occupant identifiers for MUCs (XEP-0421)XEP-0421: Anonymous unique occupant identifiers for MUCs <https://xmpp.org/extensions/xep-0421.html>. this property SHOULD be set to the local party's occupant-id.
Note that no other type of chat is specified here, and especially that a Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>. chat without support for Anonymous unique occupant identifiers for MUCs (XEP-0421)XEP-0421: Anonymous unique occupant identifiers for MUCs <https://xmpp.org/extensions/xep-0421.html>. SHOULD NOT use full Jabber ID or room nickname for the property, as it may case inconsistent behaviour in some widgets when the user changes their nickname.
The selfName property defined by WebXDCWebXDC selfAddr and selfName: https://webxdc.org/docs/spec/selfAddr_and_selfName.html is human readable and may be set to anything useful per that specification. It MAY be set to the local Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>. nickname or User Nickname (XEP-0172)XEP-0172: User Nickname <https://xmpp.org/extensions/xep-0172.html>. where relevant.
None
It is assumed that an implementation of this XEP will be paired with an implementation of WebXDCWebXDC docs: https://webxdc.org/docs/. Please see WebXDCWebXDC docs: https://webxdc.org/docs/ for sandboxing and security considerations for your WebXDC implementation.
This XEP does not introduce any specific security considerations besides those present in any WebXDCWebXDC docs: https://webxdc.org/docs/ implementation.
It should be clear to users that their actions inside an embedded widget may be transmitted to other participants.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA)The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>..
This specification defines the following XML namespace: urn:xmpp:webxdc:0
If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.
The protocol documented by this schema is defined in
XEP-]]>04910491
]]>
Thanks to NLNet foundation for funding the work on this specification.