Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 2 Next »

What Is An Embedded Experience?

Embedded experiences allows 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 both are based on standard web technologies like HTML, CSS, and Javascript, and 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.  Embedded experiences can be used anywhere inside a container but the two most common use cases are inside an email, or inside an activity stream entry.

What Type Of Embedded Experience Should I Choose?

As mentioned above, there are two types of embedded experiences, OpenSocial 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, in which case there is little development to do.  URL embedded experiences 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 is publically 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 our 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 URL embedded experience.  You will not for example be able take adavantage of any of the OpenSocial features 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 the OpenSocial APIs.  Probably the number one reason you would choose a gadget over a URL is because the user needs to authenticate to view the content in the embedded experience, or to take an 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 to do so.  Embedded experience gadgets can also use any of the OpenSocial APIs within the gadget.  Your gadget can access to the users friends, send messages to other users, or contribute actions to the surrounding container.

Data Model

The embedded experiences data model represents an embedded experience.  It tells the container everything is needs to know so it can render the embedded experience.  The data model can be represented in either JSON or XML, with the preferred method being JSON, especially if it is being places inside an activity in an activity stream.  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 can compliment a gadget embedded experience.  This can be any information you may want to be passed to your embedded experience.
  • previewImage - This is a URL to an image which can be used as a preview before rendering an 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 still wants to show a preview of the content that could be rendered.

All embedded experiences must include either a gadget or URL in order to be valid embedded experience.  The data model MAY choose to include both if the service wants to provide both types of embedded experiences.  Services may include any combination of the other properties based on their use cases.

  • No labels