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> with one exception: the special property name 
      <c>A"opensocial" URLis toreserved anfor OpenSocialuse Gadgetby definitionthe documentcontainer that defines the implementation.
       The gadget"context" toproperties be embedded.JSON object value or XML element structure 
      MUST NOT contain a property named "opensocial".</c>
 
      <c><spanx style="verb">preferredExperience<>gadget</spanx></c>
      <c>An<c>A optionalURL collectionto ofan propertiesOpenSocial thatGadget describedefinition thedocument preferred that  defines  the 
  way the creator of the embedded experience would like containers to      gadget renderto thebe contentembedded.</c>
      
      <c><spanx style="verb">previewImage<>imageData</spanx></c>
      <c>An optional URIstring tovalue anthat imagecontaining that can be used as a preview for the 
     Base64-encoded binary data for an
      image resource that represents the embedded content.</c>
 
  This can be 
    <c><spanx style="verb">root_context</spanx></c>    the  same <c>Animage optionalresource referencelinked to by the objectpreviewImage withproperty whichor 
the embedded 
      experiencea isseparate associatedimage. ForAn instance,embedded ifexperience theSHOULD embeddedNOT experiencecontain isboth 
      includedthe withinimageData anand Activity, the root_context would refer to thatpreviewImage properties.</c>
      
      <c><spanx style="verb">preferredExperience</spanx></c>
      Activity. If contained within an email, however, the root_context would <c>An optional collection of properties that describe the preferred 
      way the creator of the embedded experience would like containers to
      referrender to the emailcontent.</c>
      
      <c><spanx style="verb">url<>previewImage</spanx></c>
      <c>An <c>Aoptional URLURI to aan web pageimage 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>
    
    <t>The "url" and "gadget" properties each reference content that is to 
    be embedded. At least one of these properties MUST be specified.
    When both properties are used 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, 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>
    
    <t>Note that no XML namespace is currently declared for the XML
    serialization. This means that special care must be taken when 
    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.w3.org/2005/Atom">
    <id>http://example.org/entries/1</id>
    ...
    <embed xmlns="">
      <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>
  </entry>
    ]]></artwork></figure>
   
    <section title="Additional Examples">
    
      <figure><preamble>A simple URL embedded experience using the JSON 
      serialization:</preamble><artwork>
  {
    "url" : "http://www.example.org/embed/123.html"
  }
      </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" : "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"
  }
      </artwork></figure>
      
    <figure><preamble>The same embedded experience serialized as XML:</preamble>
    <artwork><![CDATA[
  <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>
    ]]></artwork></figure>
    
    </section>    
 
    <section title="Considerations for Embedded Gadgets">
 
      <section title="The &quot;embedded&quot; View">
        <t>When rendering a gadget as an embedded experience, the container
        will look within the gadget definition for a view named "embedded". 
        Gadget developers can use this 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.</t>
      </section>
 
      <section title="Accessing The Context">
        <t>An embedded experience gadget has the option of requiring some
        contextual information in order to render itself.  By 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 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.</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 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[
          &lt;script type="text/javascript"&gt;
 
            function myCallback(key) {
 
              var valuecontext = opensocial.data.getDataContext().getDataSet(key);
              document.getElementById("contextData").innerHTMLvar video_id = "Context Information For This Gadget: " + valuecontext["video-id"];
            }
            function initData() {
              opensocial.data.getDataContext().registerListener('
                "org.opensocial.ee.context'", myCallback);
            }
            gadgets.util.registerOnLoadHandler(initData);
        &lt;/script&gt;
           &lt;div id="contextData"&gt;&lt;/div&gt;
    ]]&gt;
    &lt;/Content&gt;
  &lt;/Module&gt;</artwork>
        </figure>

        </section>
 
    <section <section title="AccessingAdditional theContainer RootSpecific Context" anchor="rootContext">
  
        <t>Every  <t>While embeddedthe experiencecontextual isdata associated with athe 
source  object         known as it's "root org.opensocial.ee.context". key Forwill instance,generally fororiginate 
an  embedded         experiencefrom containedthe withininformation anprovided Activityby inthe a"context" JSONproperty
Activity  Stream,        within the rootEmbedded contextExperience isdocument, oftencontainers theare 
containing activity. When rendered,          free to insert additional, container specific contexual 
          data ainto gadgetthe oftenobject. needsFor toexample, accessa informationcontainer frommight thewish root context.</t>to 
          <t>Thecommunicate valueinformation ofabout the "root_context" property within the "embed" is type of parent object 
          anwithin objectwhich withthe two properties:</t>
 
 Embedded Experience information was 
    <texttable>
        <ttcol align="left" width="15%">Property</ttcol>received.</t>
        <ttcol align="left">Description</ttcol>  
          <c><spanx style="verb">id</spanx></c> <t>If such additional information is provided, the object 
        <c>Specifies  theassociated uniquewith identifier of the root context object.the "org.opensocial.ee.context" key will have an
        The  specificadditional format of the identifier"opensocial" property, whose value is dependentitself ona
the  type
        ofobject thewith root context.</c>
        <c><spanx style="verb">type</spanx></c>at least one property named "associatedContext" whose 
        <c>Specifies  thevalue rootis context'san object type aswhose properties are entirely defined by thethe 
        Core  Dataspecific specification [TODO: New Core Data Spec Ref]container implementation.</c>t>
          
</texttable>          <figure><preamble>The following example showsillustrates anhow embeddedthis 
experience        that  referencesadditional it'scontext rootinformation contextis activityaccessed:</preamble>preamble><artwork>
      <artwork>function myCallback(key) {
  {    var "id"context : "http://example.org/activities/1",= opensocial.data.getDataContext().getDataSet(key);
    var video_id = context["verbvideo-id"];
: "post",    
    "actor" : ...,var associatedContext = context.opensocial.associatedContext;
    "object" : ..., // the properties are container specific
    "openSocial" : {
 var ac_id = associatedContext.id;
    "embed" : {
 var ac_type = associatedContext.type;
      "gadget" : "http://example.com/embedded/foo.xml", ...
   }
    "root_context" :function initData() {
    opensocial.data.getDataContext().registerListener(
      "id" : "http://example.org/activities/1org.opensocial.ee.context",  myCallback);
   }
  gadgets.util.registerOnLoadHandler(initData);
      "type"  : "opensocial.Activity"  </artwork></figure>
        }  
      }    <t>Specific  container }implementations  are }free  to  insert   </artwork></figure>any additional
          <t>TODO: Complete this... Lots of questions need answering: see information they wish into both the "associatedContext" and "opensocial"
          http://docs.opensocial.org/display/OSD/More+precision+for+EE+data+model?focusedCommentId=6684693&#comment-6684693</t> object values. The interpretation and use of any such information is
          considered out of the scope of this specification.</t>
        </section>
      </section>  
  </section>
  
  <section title="Preferred Experiences" anchor="preferredExperience">
 
    <t>While the container retains control over deciding exactly how an
    embedded experience is processed and rendered, there are situations 
    where the creator of the embedded experience might wish to provide 
    clues to the container as to how it would prefer the content to be
    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:</preamble>
    <artwork>
  {
    "gadget" : "http://www.example.com/embedded/gadget.xml",
    "url" : "http://www.example.com/foo/bar.html",
    "context" : {
      "title" : "Hello World",
      "id" : 123
    },
    "previewImage" : "http://www.example.com/embedded/123.png",
    "preferredExperience" : {
      "target" : {
        "type" : "gadget",
        "view" : "my-ee-view"
      },
      "display" : {
        "type" : "link"
      }
  }
    </artwork></figure>
    
    <figure><preamble>And the same example using the alternative 
    XML serialization:</preamble>
    <artwork><![CDATA[
  <embed>
    <gadget>http://www.example.com/embedded/gadget.xml</gadget>
    <url>http://www.example.com/foo/bar.html</url>
    <context>
      <title>Hello World</title>
      <id>123</id>
    </context>
    <previewImage>http://www.example.com/embedded/123.png</previewImage>
    <preferredExperience>
      <target>
        <type>gadget</type>
        <view>my-ee-view</view>
      </target>
      <display>
        <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 threetwo possible values for the 
      required "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 <c>A required String that provides the text ofto display with the hyperlink.</c>
        <c><spanx style="verb">title</spanx></c>
        <c>The<c>Optional 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"<figure><preamble>Display equals "image", the additional properties on the using contained Base64-encoded binary data:</preamble><artwork>
  {
     "gadget" display object are:</t>: "...",
    ...,
     "imageData" <texttable>
   : "{Base64-encoded Image}",
    <ttcol align="left" width="15%">Property</ttcol>
 "preferredExperience" : {
      <ttcol align="lefttarget">Description</ttcol>
 : {...},
      <c><spanx style="verb">altText</spanx></c>display": {
        <c>Specifies"type" alternative text to display if the image cannot 
: "image",
        be displayed. Equivalent to the HTML image tags alt attribute.</c>"altText" : "The alt text",
        <c><spanx style="verbwidth">data</spanx></c>         <c></c>
: 100,
        <c><spanx style="verb">height</spanx></c>
 height" : 100
      <c>Specifies}
the  display  height}
of the image.</c>
  } 
      <c><spanx style="verb">width</spanx></c></artwork></figure>
      
    <c>Specifies  the<t>When display"type" width ofequals "image", the image.</c>additional properties on the 
      display object are:</texttable>t>
      
    <figure><preamble>Display  using text:</preamble><artwork><texttable>
    {     <ttcol align="gadgetleft" : "...",width="15%">Property</ttcol>
    ...,     <ttcol align="previewImageleft">Description</ttcol>
: "http://example.org/preview.png",        <c><spanx style="preferredExperienceverb" : {>altText</spanx></c>
        "target": {...}<c>Specifies optional,  alternative  text  to "display": {display if the image cannot 
        "type" : "text",be displayed. Equivalent to the HTML image tags alt attribute.</c>
        <c><spanx style="content" : "This is some text"
      }
    }
  }verb">height</spanx></c>
        <c>Specifies the preferred display height of the image in pixels.</c>
          </artwork></figure><c><spanx style="verb">width</spanx></c>
        <t>When<c>Specifies "type"the equals "text", the additional properties on the preferred display width of the image in pixels.</c>
      display object are:</t>texttable>
     
  <texttable>    <t>Implementations  are  free  to <ttcol align="left" width="15%">Property</ttcol>
define additional display types, 
      <ttcol align="left">Description</ttcol>
        <c><spanx style="verb">content</spanx></c>
   each with their own properties. If a container encounters an 
    <c></c>    embedded  experience </texttable>that  uses       <t>Implementations are free to define additional display types, 
      each with their own properties. If a container encounters an 
      embedded experience that uses an an unknown or unsupported display 
      type, the container MUST ignore the display preferences.</t>
 
    </section>    
    
    <section title="Target Types">
    
      <t>This specification currently defines threetwo 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"<t>Note equalsthat "gadget", the additionalpreferred propertiesexperience on the 
  target's "type" property is only 
      required if the preferred target object are:</t> is not obvious within the embedded 
        <texttable>
        <ttcol align="left" width="15%">Property</ttcol>experience. For instance, if the embedded experience only defines an 
      IRI value  for <ttcolthe align="leftgadget">Description</ttcol>  property,  then  the  preferred <c><spanx style="verb">view</spanx></c>target type
        <c>The preferred gadget view to render.</c>
        <c><spanx style="verb">viewTarget</spanx></c>is "gadget". However, if both the "url" and "gadget" properties are
      specified, as in the example above, the target type in the preferred
      experience MUST be specified. Containers MUST ignore the preferred 
      experience if the target type value does not match the options specified
      within the Embedded Experience (e.g. target type specifies "url" but 
      only a "gadget" IRI is provided, etc).</t>
      
      <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. If not specified, the value "embedded" is assumed.</c>
        <c><spanx style="verb">viewTarget</spanx></c>
        <c>Specifies where the container SHOULD render the view. Possible 
        values are "TAB", "DIALOG", "MODALDIALOG", "FLOAT", and "SIDEBAR".</c>
      </texttable>
      
      <figure><preamble>Preferring the url target:</preamble><artwork>
  {
    "gadget" : "...",
    "url" : "...",
    ...,
    "preferredExperience" : {
      "target": {
        "type" : "url",
        "viewTarget" : "_new"
      },
      "display": {
        <c></c>...
      </texttable>}
    }
  }
  <figure><preamble>Preferring  the  url target:</artwork></preamble><artwork>figure>
    {  
      <t>When "gadgettype" :equals "...url", the additional properties on the 
      "url" : "...",
    ...,target object are:</t>
      
      <texttable>
        <ttcol align="preferredExperienceleft" : {width="15%">Property</ttcol>
        <ttcol align="target": {left">Description</ttcol>
        "type" : "url",<c><spanx style="verb">viewTarget</spanx></c>
        "windowTarget"<c>When : "_new"
      },
      "display": {
        ...
specifying a URL, rather than being forced to render in an 
        }embedded  view,  the }developer  may }wish  to  indicate   </artwork></figure>
 to the container 
      <t>When "type" equals "url", the additional properties on the 
      target object are:</t>
     that the page be opened in a new browser window. In this case, the 
      <texttable>    target  properties  for <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>a URL match those that are defined by the 
        <c><spanx style="verb">windowTarget</spanx></c>
        <c><HTML spec, e.g. "_blank".</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.  This This 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.  Most Most of the time however these notifications do not
    provide much useful information beyond a link back to the service's 
    website.  By 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.</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 wouldencoded
    be typically sent to an email client (typically as text/plain or text/html), 
    html content, and another containing the embedded experience content 
  content  using either the 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>