Page Comparison

      <section title="Embedded Experiences" anchor="Embedded-Experiences">
     <xref<xref target="Issue-1144">Discussion</xref>
   
    <t>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>
    
    <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">preferredExperience</spanx></c>
      <c>An optional collection of properties that describe the preferred 
      way the creator of the embedded experience would like containers to
      render the content.</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">root_context</spanx></c>
      <c>An optional reference to the object with which the embedded 
      experience is associated. For instance, if the embedded experience is
      included within an Activity, the root_context would refer to that
      Activity. If contained within an email, however, the root_context would
      refer to the email.</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>
    
    <t>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 MAYAt least one of these properties MUST be specified.
    When both properties properties     are specifiedused within the Embedded Experience, the decision about which 
    to render is left to the container.</t>
 
  
    <t>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.</t>
 
  
    <figure><preamble>For instance, a simple JSON Embedded Experience
    that references an OpenSocial gadget:</preamble>
    <artwork>
  {
    "gadget" : "http://www.example.com/embedded/gadget.xml",
    "context" : {
      "title" : "Hello World",
      "id" : 123
    },
    "previewImage" : "http://www.example.com/embedded/123.png"
  }
    </artwork></figure>
   
    <t>When serialized as XML, it is expressed in the form of a root element 
    &lt;embed&gt; containing four child elements: &lt;, the order of which is 
    considered insignificant: &lt;context&gt;, 
    &lt;gadget&gt;, &lt;previewImage&gt;, and &lt;url&gt;. Additional extension
    elements and attributes MAY be included in the JSON object.</t>
 
  
    <figure><preamble>For example,</preamble>
    <artwork><![CDATA[
  <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>
    ]]></artwork></figure>
  
 
  <section title="Additional Examples">
    <t>Note  that  no  XML <figure><preamble>Anamespace simpleis URLcurrently embeddeddeclared experience usingfor the JSON XML
      serialization:</preamble><artwork>
  {
    "url" : "http://www.example.org/embed/123.html"
  }serialization. This means that special care must be taken when 
      </artwork></figure>
      
      <figure><preamble>The same URL embedded experience using the XML
      serialization:</preamble><artwork><![CDATA[
  <embed>
    <url>http://www.example.org/embed/123.html</url>
  </embed>
      ]]></artwork></figure>
    
      <figure><preamble>An embedded experience that specifies both a gadget 
      and URL serialized as JSON:</preamble><artwork>
  {
    "gadget" : including an XML embedded experience into another type of XML 
    document. For example, the following shows an XML embedded experience
    within a partial Atom Entry Document. Note the addition of
    <spanx style="verb">xmlns=""</spanx> on the embed element in order
    to "undeclare" the in-scope default XML namespace.</t>
 
    <figure><artwork><![CDATA[
  <entry xmlns="http://www.examplew3.comorg/embedded2005/gadget.xmlAtom",>
    "url" : "http:<id>http://www.example.org/entries/embed/123.html",1</id>
    ...
    <embed xmlns="context">
      <gadget>http: {//www.example.com/embedded/gadget.xml</gadget>
      <context>
  "title" : "Hello World",      <title>Hello World</title>
      "id" : 123  <id>123</id>
      },</context>
    "previewImage"  <previewImage>http: "http://www.example.com/embedded/123.png"png</previewImage>
    }</embed>
  </entry>
    <]]></artwork></figure>
 
         <figure><preamble>The same<section title="Additional Examples">
 
      <figure><preamble>A simple URL embedded experience serializedusing the as XML:</preamble>JSON 
      <artwork><![CDATA[serialization:</preamble><artwork>
  <embed>{
    "url" <gadget>http://www.example.com/embedded/gadget.xml</gadget>
    <url>http "http://www.example.org/embed/123.html</url>html"
   }
<context>
      <title>Hello World</title></artwork></figure>
 
    <id>123</id>   <figure><preamble>The  same </context>URL  embedded   <previewImage>http://experience using the XML
      serialization:</preamble><artwork><![CDATA[
  <embed>
    <url>http://www.example.comorg/embeddedembed/123.png<html</previewImage>url>
  </embed>
      ]]></artwork></figure>
    
    </section>    <figure><preamble>An embedded  experience  that <section title="Considerations for Embedded Gadgets">

specifies both a gadget 
       and <section title="The &quot;embedded&quot; View">URL serialized as JSON:</preamble><artwork>
   {
    <t>When"gadget" rendering a gadget as an embedded experience, the container
 : "http://www.example.com/embedded/gadget.xml",
    "url" : "http://www.example.org/embed/123.html",
    "context" : {
      will"title" look: within the gadget definition for a view named "embedded"."Hello World",
      "id" : 123
     },
    Gadget"previewImage" developers can used the "embedded" view to specify a customized
 : "http://www.example.com/embedded/123.png"
  }
      </artwork></figure>
 
    view<figure><preamble>The ofsame theembedded gadgetexperience thatserialized is specific to the embedded experience. If 
   as XML:</preamble>
    <artwork><![CDATA[
  <embed>
    an "embedded" view is not found within the gadget definition, the 
  <gadget>http://www.example.com/embedded/gadget.xml</gadget>
    <url>http://www.example.org/embed/123.html</url>
    <context>
      <title>Hello World</title>
      contain<id>123</id>
SHOULD  render  the gadget's default view.</t></context>
    <previewImage>http://www.example.com/embedded/123.png</previewImage>
  </embed>
    ]]></artwork></figure>
 
    </section>    
 
    <section title="AccessingConsiderations for TheEmbedded ContextGadgets">
 
      <t>An embedded experience gadget has the option of requiring some
<section title="The &quot;embedded&quot; View">
        contextual<t>When informationrendering ina ordergadget toas renderan itself.embedded  Byexperience, abstractingthe thecontainer
        will datalook fromwithin the gadget itself,definition gadgetfor developersa canview developnamed "embedded". 
      generalized  gadgetsGadget thatdevelopers can beuse usedthis forview allto embeddedspecify expereincesa ofcustomized
a
        specificview type.of  Forthe example,gadget athat gadgetis developedspecific to display videos can the embedded experience. If 
        bean built"embedded" soview thatis thenot idfound ofwithin the videogadget isdefinition, containedthe 
and  extracted  from     contain  SHOULD  render the embedded experiencegadget's "context"default propertyview.</t>
        </section>
 
      <figure><artwork> <section title="Accessing The Context">
  {      "gadget" : "http://example.org/embedded/video.xml",
    "context" : {<t>An embedded experience gadget has the option of requiring some
      "video-id" : "abc123"
   contextual }information  in }order  to  render itself.    </artwork></figure>
By abstracting the
        <t>Gadgetsdata thatfrom arethe writtengadget toitself, supportgadget embeddeddevelopers experiencescan MUSTdevelop
require           the "embedded-experiences" feature within their gadget definition in generalized gadgets that can be used for all embedded expereinces of a
        order to access the context.  The contextual data is stored within the 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
        <xref target="DataContext">data context</xref> object for the gadget.  
 the embedded experience's "context" property.</t>
 
        <figure><artwork>
  {
    "gadget" : "http://example.org/embedded/video.xml",
    "context" : {
      "video-id" : "abc123"
    }
  }
        </artwork></figure>
 
        <t>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.</t>
 
        <figure><preamble>For instance, the Gadget below registers a listener
        with the data context to retrieve any context data included with the 
        embedded experience:</preamble>
          <artwork xml:space="preserve">
  &lt;Module&gt;
    &lt;ModulePrefs title="Embedded Experiences Test" description="Tests the embedded experiences APIs."&gt;
      &lt;Require feature="embedded-experiences"&gt;&lt;/Require&gt;
    &lt;/ModulePrefs&gt;
    &lt;Content type="html" view="embedded"&gt;
        &lt;![CDATA[
        The key, "org.opensocial.ee.context", is used to access the context.
  &lt;script type="text/javascript"&gt;
              Gadgets can add a listener on the data context object for this key, orfunction myCallback(key){
          it  may  retreive  thevar key's value by using the data context APIs.</t>= opensocial.data.getDataContext().getDataSet(key);
                  <figure><preamble>For instance, the Gadget below registers a listener document.getElementById("contextData").innerHTML = "Context Information For This Gadget: " + value;
            }
with  the  data  context  to  retrieve  anyfunction contextinitData() data{
included  with  the           embedded experience:</preamble>opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', myCallback);
          <artwork xml:space="preserve">  }
  &lt;Module&gt;      &lt;ModulePrefs title="Embedded Experiences Test" description="Tests the embedded experiences APIs."&gt    gadgets.util.registerOnLoadHandler(initData);
      &lt;Require feature="embedded-experiences"&gt;&  &lt;/Requirescript&gt;
      &lt;/ModulePrefs&gt;
    &lt;Contentdiv typeid="html" view="embedded"contextData"&gt;&lt;/div&gt;
    ]]&gt;
    &lt;![CDATA[;/Content&gt;
          &lt;script type="text/javascript"/Module&gt;</artwork>
        </figure>
 
    function myCallback(key){  </section>
 
    <section title="Accessing the Root Context" anchor="rootContext">
 
        var value = opensocial.data.getDataContext().getDataSet(key);
  <t>Every embedded experience is associated with a source object 
       known  as   document.getElementById("contextData").innerHTML = "Context Information For This Gadget: " + value;it's "root context". For instance, for an embedded 
      experience contained  within  an  Activity  in }a  JSON  Activity  Stream,
      functionthe initData()root {context  is  often  the  containing  activity.     opensocial.data.getDataContext().registerListener('org.opensocial.ee.context', myCallback);
When rendered,
       a  gadget  often }needs  to  access  information  from  the  root gadgets.util.registerOnLoadHandler(initData);context.</t>
 
      &lt;/script&gt; <t>The value of the "root_context" property within the "embed" is 
         &lt;div id="contextData"&gt;&lt;/div&gt;an object with two properties:</t>
 
      ]]&gt;<texttable>
    &lt;/Content&gt;    &lt;/Module&gt;</artwork><ttcol align="left" width="15%">Property</ttcol>
        </figure> <ttcol align="left">Description</ttcol>
          
 <c><spanx style="verb">id</spanx></c>
    </section>
      <c>Specifies  the  unique <section title="Accessingidentifier of the Rootroot Context" anchor="rootContext">
  context object.
        <t>Every embedded experience The specific format of the identifier is associateddependent withon athe sourcetype
object         knownof asthe it's "root context".</c>
For instance, for an embedded 
        experience contained within an Activity in a JSON Activity Stream,
<c><spanx style="verb">type</spanx></c>
         <c>Specifies the root context's isobject oftentype theas containingdefined activity.by Whenthe
rendered,        a gadget often needs to access information from the root context.</t>Core Data specification [TODO: New Core Data Spec Ref].</c>
        </texttable>
 
    <t>The  value<figure><preamble>The offollowing the "root_context" property within the "embed" is example shows an embedded experience
       that anreferences objectit's withroot twocontext propertiesactivity:</t>preamble>

      <texttable><artwork>
   {
    <ttcol align="leftid" width="15%">Property</ttcol>
   : "http://example.org/activities/1",
    <ttcol align="leftverb">Description</ttcol>    : "post",
    <c><spanx style="verbactor">id</spanx></c>    : ...,
    <c>Specifies"object" the unique identifier of the root context object.: ...,
    "openSocial" : {
       "embed" The: specific{
format  of  the  identifier  is"gadget" dependent on the type: "http://example.com/embedded/foo.xml",
        of the root context.</c>"root_context" : {
          <c><spanx style="verb">type</spanx></c>"id" : "http://example.org/activities/1",
        <c>Specifies the root context's object type as defined by the  "type" : "opensocial.Activity"
        }
    Core  Data}
specification  [TODO:  New}
Core  Data Spec Ref].</c>
}
      </artwork></texttable>figure>  
    
      <figure><preamble>The following example shows an embedded experience <t>TODO: Complete this... Lots of questions need answering: see 
      that references it's root context activity:</preamble>http://docs.opensocial.org/display/OSD/More+precision+for+EE+data+model?focusedCommentId=6684693&#comment-6684693</t>
 
    <artwork></section>
 
{
    "id" : "http://example.org/activities/1",</section>
 
  <section title="verbPreferred Experiences" : anchor="postpreferredExperience",>
 
    "actor" : ...,
    "object" : ...,<t>While the container retains control over deciding exactly how an
    "openSocial"embedded :experience {is  processed  and   "embed" : {rendered, there are situations 
     where the  creator "gadget"of : "http://example.com/embedded/foo.xml",the embedded experience might wish to provide 
     clues to   "root_context" : {
          "id" : "http://example.org/activities/1",the container as to how it would prefer the content to be
          "type" : "opensocial.Activity" displayed. These clues are included within the Embedded Experience
        }using the "preferredExperience" property.</t>
 
    }<figure><preamble>The  following  illustrates }a  basic }example 
    serialized  as JSON:</artwork></figure>preamble>
    <artwork>
    {
     "gadget" <t>TODO: Complete this... Lots of questions need answering: see 
      "http://www.example.com/embedded/gadget.xml",
    "url" : "http://docswww.opensocialexample.orgcom/display/OSD/More+precision+for+EE+data+model?focusedCommentId=6684693&#comment-6684693</t>
  
    </section>
  
  </section>
  
  <section title="Preferred Experiences" anchor="preferredExperience">
foo/bar.html",
    "context" : {
      "title" : "Hello World",
      <t>While the container retains control over deciding exactly how an"id" : 123
    },
    "previewImage" : "http://www.example.com/embedded/123.png",
    embedded"preferredExperience" experience: is{
processed  and  rendered, there are situations   "target" : {
    where the creator of the embedded experience might wish to provide     "type" : "gadget",
        clues to the container as to how it would prefer the content to be"view" : "my-ee-view"
      },
      "display" : {
        displayed. These clues are included within the Embedded Experience"type" : "link"
      }
  }
    using the "preferredExperience" property.</t>
    
    <figure><preamble>The following illustrates a basic example</artwork></figure>
 
    <figure><preamble>And the same example using the alternative 
    XML serialization:</preamble>
    <artwork><artwork><![CDATA[
  {<embed>
    "gadget" : "http:<gadget>http://www.example.com/embedded/gadget.xml",xml</gadget>
    "url" : "http<url>http://www.example.com/foo/bar.html",html</url>
    "context" : {<context>
      "title" : "Hello World",
<title>Hello World</title>
      "id" : 123
<id>123</id>
    },
    "previewImage" : "http</context>
    <previewImage>http://www.example.com/embedded/123.png",png</previewImage>
    "preferredExperience" : {
<preferredExperience>
      "target" : {
<target>
        "type" : "gadget",
<type>gadget</type>
        "view" : "my<view>my-ee-view"view</view>
      },</target>
      "display" : {
<display>
        "type" : "link"<type>link</type>
      </display>
    }</preferredExperience>
  }</embed>
    <]]></artwork></figure>
 
    <t>In this example, we have an embedded experience serialized as JSON.
    The structure defines both a "url" and a "gadget" property, both of w
    which can be used by the container to display embedded content. Typically,
    the decision of which to display when the embedded experience is rendered
    is up to the container. The "preferredExperience.target" property allows the 
    creator of the embedded experience to indicate that it would prefer the
    container to use the "gadget" property for rendering, and specifically that
    the "my-ee-view" view within that gadget be used. The "preferredExperience.display"
    property indicates that rather than simply displaying the gadget automatically,
    the embedded experience's creator would rather the container initially display a 
    hyperlink that, when clicked, causes the gadget to be displayed.</t>
    
    <texttable>
      <ttcol align="left" width="15%">Property</ttcol>
      <ttcol align="left">Description</ttcol>
      <c><spanx style="verb">display</spanx></c>
      <c>Describes preferences for how the embedded experience should 
      initially be displayed by the container. The value of the 
      "display" property is an object that contains a 
      required "type" property, the value of which determines 
      what other properties might appear within the object.</c>
      <c><spanx style="verb">target</spanx></c>
      <c>Describes preferences for which type of embedded experience 
      the container should render. For instance, if the embed includes
      both a "url" and "gadget" property, the "target" is used to specify
      which is preferred. The value of the "target" property is an 
      object that contains a required "type" property, the value of which
      determines what other properties might appear within the object.</c>
    </texttable>
 
    <section title="Display Types">
 
      <t>This specification currently defines three possible values for the 
      type property on the display object: "link", "image", and "text".
      Each of which are illustrated below.</t>
 
    
      <figure><preamble>Display using a hyperlink:</preamble><artwork>
  {
    "gadget" : "...",
    ...,
    "preferredExperience" : {
      "target": {...},
      "display": {
        "type" : "link",
        "text" : "Click on me!",
        "title" : "Click on this link!"
      }
    }
  }
      </artwork></figure>
 
    
      <t>When "type" equals "link", the additional properties on the 
      display object are:</t>
 
    
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">text</spanx></c>
        <c>The text of the hyperlink.</c>
        <c><spanx style="verb">title</spanx></c>
        <c>The text to display as the "popup help" or "tooltip" of 
        the hyperlink.</c>
      </texttable>
 
    
      <figure><preamble>Display using the previewImage:</preamble><artwork>
  {
    "gadget" : "...",
    ...,
    "previewImage" : "http://example.org/preview.png",
    "preferredExperience" : {
      "target": {...},
      "display": {
        "type" : "image",
        "altText" : "The alt text",
        "width" : 100,
        "height" : 100
      }
    }
  } 
      </artwork></figure>
 
    
      <t>When "type" equals "image", the additional properties on the 
      display object are:</t>
 
    
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">altText</spanx></c>
        <c>Specifies alternative text to display if the image cannot 
        be displayed. Equivalent to the HTML image tags alt attribute.</c>
        <c><spanx style="verb">data</spanx></c>
        <c></c>
        <c><spanx style="verb">height</spanx></c>
        <c>Specifies the display height of the image.</c>
        <c><spanx style="verb">width</spanx></c>
        <c>Specifies the display width of the image.</c>
      </texttable>
 
    
      <figure><preamble>Display using text:</preamble><artwork>
  {
    "gadget" : "...",
    ...,
    "previewImage" : "http://example.org/preview.png",
    "preferredExperience" : {
      "target": {...},
      "display": {
        "type" : "text",
        "content" : "This is some text"
      }
    }
  } 
      </artwork></figure>
 
      <t>When "type" equals "text", the additional properties on the 
      display object are:</t>
 
    
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">content</spanx></c>
        <c></c>
      </texttable>
 
      <t>Implementations are free to define additional display types, 
      each with their own properties. If a container encounters an 
      embedded experience that uses an unknown or unsupported display 
      type, the container MUST ignore the display preferences.</t>
 
    </section>    
    
    <section title="Target Types">
 
  
      <t>This specification currently defines three possible values for the 
      type property on the target object: "gadget" and "url". Each of which 
      are illustrated below.</t>
 
  
      <figure><preamble>Preferring the gadget target:</preamble><artwork>
  {
    "gadget" : "...",
    "url" : "...",
    ...,
    "preferredExperience" : {
      "target": {
        "type" : "gadget",
        "view" : "my-ee-view"
      },
      "display": {
        ...
      }
    }
  }
      </artwork></figure>
 
    
      <t>When "type" equals "gadget", the additional properties on the 
      target object are:</t>
 
    
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">view</spanx></c>
        <c>The preferred gadget view to render.</c>
        <c><spanx style="verb">viewTarget</spanx></c>
        <c></c>
      </texttable>
 
    
      <figure><preamble>Preferring the url target:</preamble><artwork>
  {
    "gadget" : "...",
    "url" : "...",
    ...,
    "preferredExperience" : {
      "target": {
        "type" : "url",
        "windowTarget" : "_new"
      },
      "display": {
        ...
      }
    }
  }
      </artwork></figure>
 
           <t>When "type" equals "url", the additional properties on the 
      target object are:</t>
 
    
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">windowTarget</spanx></c>
        <c></c>
      </texttable>
    
      <t>Implementations are free to define additional target types, 
      each with their own properties. If a container encounters an 
      embedded experience that uses an unknown or unsupported target 
      type, the container MUST ignore the target preferences.</t>
    
    </section>
 
  </section>
 
  <section title="Security">
    <t>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.   ThisThis specification does not dictate how
    secure rendering of embedded experiences is to be performed.</t>
  </section>
 
  <section title="Embedded Experiences within Activity Streams">
   
    <t>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.</t>
   
    <figure><preamble>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:</preamble>
          <artwork xml:space="preserve">
  {
    "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"
          ]
        }
      }
    }
  }</artwork></figure>
   
    <t>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.</t>
   
  </section>
   
  <section title="Embedded Experiences within Email">
 
    <t>Numerous services send email notifications to your inbox in
    order to let you know something took place that you may be
    interested in.   MostMost of the time however these notifications do not
    provide much useful information beyond a link back to the service's 
    website.   ByBy 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.</t>
 
    <t>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 </t>
 
    <figure>
      <preamble>For instance,</preamble>
      <artwork xml:space="preserve">
  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
 
  &lt;html&gt;
  &lt;!-- HTML representation here --&gt;
  &lt;/html&gt;
 
  --XXXXboundary text
  Content-Type: application/embed+json
  {
    "gadget" : "http://www.socialnetwork.com/embedded/commentgadget.xml",
    "context" : 123
  }</artwork>
    </figure>
    
  </section>
 
  </section>