What Is An Embedded Experience?

Embedded experiences allows allow application developers to embed content from their applications inside OpenSocial 2.0 containers.  An embedded experience can be built as an OpenSocial gadget, or it can be a simple web page, but because .  Because both are based on standard web technologies like HTML, CSS, and Javascript, any web developer should be able to create an embedded experience.  Embedded experiences are backed by a simple data model.  Containers and gadgets which support embedded experiences will recognize this data model and can choose to render the embedded experience.

...

As mentioned above, there are two types of embedded experiences, : OpenSocial gadgets Gadgets and web pages.  Embedded experiences which point to web pages are the simplest to create, especially if the web page you want to use already exists.  Embedded experiences which point to web pages can also be embedded in any container, even if they don't support OpenSocial.  You may choose a URL embedded experience if you just want to show static content , which that is publicly available on the internet.  Good examples of this would be an embedded experience which tracks a package , or an embedded experience which asks a user to fill out a survey.  These types of applications are usually public content which does not require authentication to access.  However you will also be limited on the type experience you can provide with a web page.  You will not be able take advantage of any of the OpenSocial APIs when you are using an URL embedded experience.

Embedded experiences based on gadgets have the ability to be more powerful and take advantage of all of the OpenSocial APIs.  Probably the  The number one reason you would choose a gadget over a web page is because the user needs to authenticate to view or take action on the content in the embedded experience.  OAuth is part of the OpenSocial specification and it can allow your embedded experience gadget to access secure content once the user has delegated access to the gadget.  Embedded experience gadgets can also use any of the OpenSocial APIs.  Your gadget can access to the users friends, send messages to other users, or contribute actions to the surrounding container.

...

The embedded experiences data model is the way to represent an embedded experience in JSON or XML.  It tells the container everything is needs to know so it can render the embedded experience.  The data model has only a couple of properties.

• gadget - The URL to the gadget you would like to use as an embedded experience.
• url - The URL to a text/html page you would like to use as an embedded experience.
• context - The context is information you would like to use in your gadget.  Note: the context is not only used with for gadget embedded experiences that are web pages.
• previewImage - This is a URL to an image which can be used as a preview of the embedded experience.  This information is not necessary , but is a convenience to the container if it doesn't want to render the embedded experience immediately but would instead want to show a preview of the content that could be rendered.

...

Now that you know what an embedded experience is, and we know what makes up an embedded experience, we are ready to get started building one.  In this tutorial we will build a gadget based embedded experience since that is the more complex and interesting type of embedded experience.  If your you're interested in building a URL embedded experience its a it's as simple as building a web page and placing the URL to that page in the data model you want to use.  See below the sections entitled "Embedded Our Gadget In An Email" and "Embedding Our Gadget In An Activity In An Activity Stream" on how to embed the data model in emails or activity streams.

For this tutorial we will build an embedded experience gadget which will embed a YouTube video in both emails and activity streams.  The first thing we need to do is decide on what our data model is going to look like.  For this tutorial we will keep it fairly simple, our .  Our embedded experience gadget will just embed a YouTube video.  Lets say we want to embed a video to an OpenSocial tutorial,  http://www.youtube.com/watch?v=9gW2YVBrNVA.  As most people know you can already embed YouTube videos into any HTML page using this HTML.

...

We could just place this HTML in the gadget use that gadget as out our embedded experience.  Lets  Let's take a look at what an embedded experience gadget and data model would look like using this HTML.

...

Data Model

...

.

...

Gadget XML

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="YouTube Player" description="YouTube Player Using Embedded Experiences" height="400" width="700"/>
<Content type="html">
  <![CDATA[
    <object width=480" height="285">
  <param name="movie" value="http://www.youtube.com/v/9gW2YVBrNVA"></param>
  <param name="allowFullScreen" value="true"></param>
  <param name="allowscriptaccess" value="always"></param>
  <embed src="http://www.youtube.com/v/9gW2YVBrNVA" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="285">
  </embed>
</object>
  ]]>
</Content>
</Module>

...

...

Data Model

...

{
  "gadget": "http://example.com/YouTube_EE.xml"
}

The problem with this embedded experience is that it is very static.  What if we wanted to create an embedded experience for a different YouTube video?  With our current embedded experience we would have to build a new gadget.  Fortunately there is a way to solve this problem.

...

The first difference you will notice in our new gadget XML is that we have included two features in the ModulePrefs section.  The dynamic-height feature is used to adjust the height of the gadget once the video has been placed in the gadget.  The more important feature is the embedded-experiences feature.  This is the feature which will get the context information and make it available to the gadget.  The context information from the data model is placed in the data context object, under the key org.opensocial.ee.context.  You can access information from the data context object by using the data context APIs to get the data set for the embedded experiences key.

Notice in the content section of the gadget we have also removed all the HTML from our previous embedded experience gadget and now just have a script tag and a div tag.  If we take a look at the contents of the script tag you will see two functions and a call to register an on load handler to kick everything off.  The on load handler we register, initData, will be called once the gadget has been loaded.  When initData is called we register a listener for the key org.opensocial.ee.context on the data context object.  When the data set attached to the key org.opensocial.ee.context has changed our listener function will be called and can retrieve the data set for that key.  In the embedded experiences case the data set is the context information from the data model.  The data set, or context information, can be retrieved by calling opensocial.data.getDataContext().getDataSet('org.opensocial.ee.context').  In our example embedded experience gadget we call showPlayer with the context information, which in our data model is the YouTube video id.  The showPlayer function sets the inner HTML of the div element with the id player to the HTML to show the YouTube video.

...

Now that we know what our data model is going to look like and we have written our gadget we are ready to start providing embedded experiences.  One of the most interesting use cases is to provide a richer experience in emails.  The majority of services today send static HTML emails based on a standard called MIME.  This is a step above plain text emails but , the HTML has its own limitations as well.  Embedded experiences has taken advantage of the MIME email spec to allow applications to send embedded experiences in MIME emails as well.  If an application already is application is already sending MIME emails, the changes will be minimal and it will not effect users who are using mail clients which that don't support embedded experiences.  

...

From: notifications@example.com
To: johndoe@example.com
Subject: Check Out This YouTube Video
MIME-Version: 1.0
Content-Type: multipart/alternative;
        boundary="XXXXboundary text"

--XXXXboundary text
Content-Type: text/plain

Check out this YouTube video.
http://www.youtube.com/watch?v=9gW2YVBrNVA

--XXXXboundary text
Content-Type: text/plainhtml

Check out this YouTube video.
http://www.youtube.com/watch?v=9gW2YVBrNVA

--XXXXboundary text
Content-Type: text/html

Check out this <a href="<a href="http://www.youtube.com/watch?v=9gW2YVBrNVA">YouTube video</a>.

This is a pretty standard multipart/alternative MIME email.  It has two parts, a text/plain and a text/html part.  Like I said above, to make this an embedded experience email we just have to add another part.to add another part.

...

Embedded Experience MIME Email With JSON Data Model

...

From: notifications@example.com
To: johndoe@example.com
Subject: Check Out This YouTube Video
MIME-Version: 1.0
Content-Type: multipart/alternative;
        boundary="XXXXboundary text"

--XXXXboundary text
Content-Type: text/plain

Check out this YouTube video.
http://www.youtube.com/watch?v=9gW2YVBrNVA

--XXXXboundary text
Content-Type: text/html

Check out this <a href="http://www.youtube.com/watch?v=9gW2YVBrNVA">YouTube video</a>.

--XXXXboundary text
Content-Type: application/embed+json
{
  "gadget" : "http://example.com/YouTube_EE.xml",
  "context" : "9gW2YVBrNVA"

}

...

Embedded Experience MIME Email With XML Data Model

...

From: notifications@example.com
To: johndoe@example.com
Subject: Check Out This YouTube Video
MIME-Version: 1.0
Content-Type: multipart/alternative;
        boundary="XXXXboundary text"

Check out this YouTube video.
http://www.youtube.com/watch?v=9gW2YVBrNVA

--XXXXboundary text
Content-Type: text/plain

Check out this YouTube video.
http://www.youtube.com/watch?v=9gW2YVBrNVA

--XXXXboundary text
Content-Type: text/html

Check out this <a href="http://www.youtube.com/watch?v=9gW2YVBrNVA">YouTube video</a>.

--XXXXboundary text
Content-Type: application/embed+jsonxml
{<embed>
  "gadget" : "http:<gadget>http://example.com/YouTube_EE.xml",xml</gadget>
  "context" : 123
}
<context>9gW2YVBrNVA</context>
</embed>

In our new email you can see we have added another part with the content type of application/embed+json.  This is a MIME type the OpenSocial foundation has registered with IANA to represent embedded experiences.  In addition to the JSON MIME type the OpenSocial foundation has also registered applicaiton/embed+xml for the XML data model.  The content of the MIME part is just our embedded experiences data model.  When email clients which support embedded experiences receive this email, they will be looking for a MIME part with the type application/embed+json or application/embed+xml, and if they find it they can choose to render the embedded experience.  If a client which does not support embedded experiences receives this email they will choose to render whatever other part they support, most likely the text/html part.

...

OpenSocial 2.0 supports the ActivityStreams 1.0 specification.  OpenSocial has also has defined a namespace extension to the ActivityStreams spec which contains OpenSocial specific concepts.  The embedded experiences data model can be placed inside the OpenSocial extension.  Say we have this activity entry.

...