# Embedded Experiences
Embedded experiences provide a mechanism for embedding OpenSocial
gadgets and other web-accessible content sources directly into a
variety of contexts such as Activity Streams, email messages and Atom
feeds. The mechanism works by inserting a small structure of data that
includes a reference to the embedded content along with contextual
data an OpenSocial container would need to render the content
appropriately.</t>
This data structure can be serialized as either a JSON object or XML
and includes the following properties:</t>
<texttable>
<ttcol align="left" width="15%">Property</ttcol>
<ttcol align="left">Description</ttcol>
<c><spanx style="verb">context</spanx></c>
<c>If the Embedded Experience is used to embed an OpenSocial gadget,
the "context" field is used to pass data to the gadget so that it
knows exactly which content to render. For instance, a gadget that
displays a person's profile information will need to know which
profile to display; a gadget that displays an album of recent photos
will need to know the identity of the album to display. The content
of the "context" field is undefined and specific to each individual
gadget definition.</c>
<c><spanx style="verb">gadget</spanx></c>
<c>A URL to an OpenSocial Gadget definition document that defines the
gadget to be embedded.</c>
<c><spanx style="verb">previewImage</spanx></c>
<c>An optional URI to an image that can be used as a preview for the
embedded content.</c>
<c><spanx style="verb">url</spanx></c>
<c>A URL to a web page that allows virtually any web-accessible
resource to be used as an Embedded Experience.</c>
</texttable>
The "url" and "gadget" properties each reference content that is to be
embedded. Typically, an Embedded Experience will provide one or the
other. However, both properties MAY be specified. When both properties
are specified within the Embedded Experience, the decision about which
to render is left to the container.
When serialized as JSON, the embedded experience take the form of a
single JSON Object with four distinct properties: "context", "gadget",
"previewImage" and "url". Additional extension properties MAY be
included in the JSON object.
For instance, a simple JSON Embedded Experience that references an
OpenSocial gadget:
{
"gadget" : "http://www.example.com/embedded/gadget.xml",
"context" : {
"title" : "Hello World",
"id" : 123
},
"previewImage" : "http://www.example.com/embedded/123.png"
}
When serialized as XML, it is expressed in the form of a root element
<embed> containing four child elements: <context>, <gadget>,
<previewImage>, and <url>. Additional extension elements and
attributes MAY be included in the JSON object.
For example,
<embed>
<gadget>http://www.example.com/embedded/gadget.xml</gadget>
<context>
<title>Hello World</title>
<id>123</id>
</context>
<previewImage>http://www.example.com/embedded/123.png</previewImage>
</embed>
#.# Additional Examples
A simple URL embedded experience using the JSON serialization:
{
"url" : "http://www.example.org/embed/123.html"
}
The same URL embedded experience using the XML serialization:
<embed>
<url>http://www.example.org/embed/123.html</url>
</embed>
An embedded experience that specifies both a gadget and URL serialized as JSON:
{
"gadget" : "http://www.example.com/embedded/gadget.xml",
"url" : "http://www.example.org/embed/123.html",
"context" : {
"title" : "Hello World",
"id" : 123
},
"previewImage" : "http://www.example.com/embedded/123.png"
}
The same embedded experience serialized as XML:
<embed>
<gadget>http://www.example.com/embedded/gadget.xml</gadget>
<url>http://www.example.org/embed/123.html</url>
<context>
<title>Hello World</title>
<id>123</id>
</context>
<previewImage>http://www.example.com/embedded/123.png</previewImage>
</embed>
#.# Considerations for Embedded Gadgets
#.#.# The "embedded" View
When rendering a gadget as an embedded experience, the container will
look within the gadget definition for a view named "embedded". Gadget
developers can used the "embedded" view to specify a customized view
of the gadget that is specific to the embedded experience. If an
"embedded" view is not found within the gadget definition, the contain
SHOULD render the gadget's default view.
#.#.# Accessing The Context
An embedded experience gadget has the option of requiring some
contextual information in order to render itself. By abstracting the
data from the gadget itself, gadget developers can develop generalized
gadgets that can be used for all embedded expereinces of a specific
type. For example, a gadget developed to display videos can be built
so that the id of the video is contained and extracted from the
embedded experience's "context" property.
{
"gadget" : "http://example.org/embedded/video.xml",
"context" : {
"video-id" : "abc123"
}
}
Gadgets that are written to support embedded experiences MUST require
the "embedded-experiences" feature within their gadget definition in
order to access the context. The contextual data is stored within the
<xref target="DataContext">data context</xref> object for the gadget.
The key, "org.opensocial.ee.context", is used to access the context.
Gadgets can add a listener on the data context object for this key, or
it may retreive the key's value by using the data context APIs.
For instance, the Gadget below registers a listener with the data
context to retrieve any context data included with the embedded
experience:
<Module>
<ModulePrefs title="Embedded Experiences Test"
description="Tests the embedded experiences APIs.">
<Require feature="embedded-experiences"></Require>
</ModulePrefs>
<Content type="html" view="embedded">
<![CDATA[
<script type="text/javascript">
function myCallback(key){
var value = opensocial.data.getDataContext().getDataSet(key);
document.getElementById("contextData").innerHTML =
"Context Information For This Gadget: " + value;
}
function initData() {
opensocial.data.getDataContext().registerListener('org.opensocial.ee.context',
myCallback);
}
gadgets.util.registerOnLoadHandler(initData);
</script>
<div id="contextData"></div>
]]>
</Content>
</Module>
#.# Security
Embedded experiences allow content to be rendered on the page that
user has not necessarily requested, therefore it needs to be secured.
The container SHOULD only ever render content that the user has
previously approved. This specification does not dictate how secure
rendering of embedded experiences is to be performed.
#.# Embedded Experiences within Activity Streams
Embedded experiences can be used within an Activity Streams document
in order to provide a more interactive experience. Whereas the core
properties of the Activity provide a textual description of the event,
an included embedded experience can provide a direct representation of
the object involved.
For instance, if a user uploads a collection of photos and creates a
new photo album, an embedded experience can be used within the
activity to provide a representation of the album itself:
{
"postedTime": "2011-02-10T15:04:55Z",
"actor": {
"objectType" : "person",
"id": "tag:example.org,2011:martin",
"displayName": "Martin Smith"
}
"verb": "post",
"object" : {
"objectType":"collection",
"objectTypes":["image"]
"id": "http://example.org/albums/germany-2009",
"url": "http://example.org/albums/germany-2009",
},
"openSocial" : {
"embed" : {
"gadget" : "http://example.org/AlbumViewer.xml",
"context" : {
"albumName": "Germany 2009",
"photoUrls": [
"http://examplephotos.com/3495/3925132517_5959dac775_t.jpg",
"http://examplephotos.com/3629/3394799776_47676abb46_t.jpg",
"http://examplephotos.com/4009/4413640211_715d924d9b_t.jpg",
"http://examplephotos.com/2340/3528537244_d2fb037aba_t.jpg",
"http://examplephotos.com/36/98407782_9c4c5866d1_t.jpg",
"http://examplephotos.com/48/180544479_bb0d0f6559_t.jpg",
"http://examplephotos.com/2668/3858018351_1e7b73c0b7_t.jpg"
]
}
}
}
}
As illustrated in the example, when included within an activity, the
embedded experience MUST appear as the value of the "embed" property
as a child of the "openSocial" property.
#.# Embedded Experiences within Email
Numerous services send email notifications to your inbox in order to
let you know something took place that you may be interested in. Most
of the time however these notifications do not provide much useful
information beyond a link back to the service's website. By
leveraging embedded experiences, services can send an embedded
representation of the object the notification is about, and allow the
user to take action on the notification directly from within an
embedded experiences enabled email client.
Embedded experiences serialized as either JSON or XML can be embedded
Multipart MIME encoded email messages. Such email messages MUST
utilize the "multipart/alternative" MIME variant and MUST contain at
least two MIME parts -- one containing regular content of the email
message as would be typically sent to an email client (typically
text/plain or text/html), and another containing the embedded
experience content using either the "application/embed+json" or
"application/embed+xml" MIME media type, respectively representing the
JSON and XML serializations. Additional MIME parts MAY be included
From: notifications@socialnetwork.com
To: johndoe@example.com
Subject: Social Network: Mary Has Commented On Your Status
MIME-Version: 1.0
Content-Type: multipart/alternative;
boundary="XXXXboundary text"
Mary has commented on your status.
--XXXXboundary text
Content-Type: text/plain
Mary has commeneted on your status.
--XXXXboundary text
Content-Type: text/html
<html>
<!-- HTML representation here -->
</html>
--XXXXboundary text
Content-Type: application/embed+json
{
"gadget" : "http://www.socialnetwork.com/embedded/commentgadget.xml",
"context" : 123
}
General
Content
Integrations