Core-Gadget - Embedded Experiences

  <!-- ///////////// -->
   <section title="Embedded Experiences" anchor="Embedded-Experiences">
   <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 with one exception: the special property name 
      "opensocial" is reserved for use by the container implementation.
      The "context" properties JSON object value or XML element structure 
      MUST NOT contain a property named "opensocial".</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">imageData</spanx></c>
      <c>An optional string value that containing Base64-encoded binary data for an
      image resource that represents the embedded content. This can be 
      the same image resource linked to by the previewImage property or 
      a separate image. An embedded experience SHOULD NOT contain both 
      the imageData and previewImage properties.</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">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 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.</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[
          &lt;script type="text/javascript"&gt;
            function myCallback(key) {
              var context = opensocial.data.getDataContext().getDataSet(key);
              var video_id = context["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 title="Additional Container Specific Context" anchor="rootContext">
  
          <t>While the contextual data associated with the 
          "org.opensocial.ee.context" key will generally originate 
          from the information provided by the "context" property
          within the Embedded Experience document, containers are 
          free to insert additional, container specific contexual 
          data into the object. For example, a container might wish to 
          communicate information about the type of parent object 
          within which the Embedded Experience information was 
          received.</t>
          
          <t>If such additional information is provided, the object 
          associated with the "org.opensocial.ee.context" key will have an
          additional "opensocial" property, whose value is itself a
          object with at least one property named "associatedContext" whose 
          value is an object whose properties are entirely defined by the 
          specific container implementation.</t>
          
          <figure><preamble>The following example illustrates how this 
          additional context information is accessed:</preamble><artwork>
  function myCallback(key) {
    var context = opensocial.data.getDataContext().getDataSet(key);
    var video_id = context["video-id"];
    
    var associatedContext = context.opensocial.associatedContext;
    // the properties are container specific
    var ac_id = associatedContext.id;
    var ac_type = associatedContext.type;
    // ...
  }
  function initData() {
    opensocial.data.getDataContext().registerListener(
      "org.opensocial.ee.context", myCallback);
  }
  gadgets.util.registerOnLoadHandler(initData);
          </artwork></figure>
          
          <t>Specific container implementations are free to insert any additional
          information they wish into both the "associatedContext" and "opensocial"
          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 two possible values for the 
      required "type" property on the display object: "link", "image".
      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>A required String that provides the text to display with the hyperlink.</c>
        <c><spanx style="verb">title</spanx></c>
        <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>
      
      <figure><preamble>Display using contained Base64-encoded binary data:</preamble><artwork>
  {
    "gadget" : "...",
    ...,
    "imageData" : "{Base64-encoded Image}",
    "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 optional, alternative text to display if the image cannot 
        be displayed. Equivalent to the HTML image tags alt attribute.</c>
        <c><spanx style="verb">height</spanx></c>
        <c>Specifies the preferred display height of the image in pixels.</c>
        <c><spanx style="verb">width</spanx></c>
        <c>Specifies the preferred display width of the image in pixels.</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 two 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>Note that the preferred experience target's "type" property is only 
      required if the preferred target is not obvious within the embedded 
      experience. For instance, if the embedded experience only defines an 
      IRI value for the "gadget" property, then the preferred target type
      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": {
        ...
      }
    }
  }
      </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">viewTarget</spanx></c>
        <c>When specifying a URL, rather than being forced to render in an 
        embedded view, the developer may wish to indicate to the container 
        that the page be opened in a new browser window. In this case, the 
        target properties for a URL match those that are defined by the 
        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 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 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.</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 encoded
    as text/html content, 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>