OpenSocial
Specification Release Notesopensocial-and-gadgets-spec@googlegroups.com
General
OpenSocialsocial networkingRESTXMLExtensible Markup LanguageJSONJavaScript Object NotationAtomPublished August 28, 2012The Common Container which has been incubating since OpenSocial 2.0.0 is now finalized API.
The Common Container provides a set of common services that Container developers can leverage
for features like in-browser Gadget lifecycle event callbacks, Embedded Experiences, selection handlers, and action handlers.
The Embedded Experience model introduced in OpenSocial 2.0.0 has been enhanced with the addition of Preferred Experiences.
Preferred Experiences allow Embedded Experience developers to provide hints to the Container about how Embedded Experiences
should be realized in the user interface.
A more complete metadata service has been introduced into OpenSocial. This additional Metadata API allows OpenSocial applications
to have a more compelling user experience that can better adapt to the capabilities of different OpenSocial containers.
Due to the evolution of mobile web technology and lack of adoption, the OpenSocial WAP Extension is being deprecated.
List of
opensocial-resources
project issues published in OpenSocial 2.5.0 is accessible at http://bit.ly/os25publishedspecissues.
Published November 23, 2011
OpenSocial 2.0.1 revised the OAuth 2.0 related parts of OpenSocial and moved support out of incubating.
As part of these changes, an OAuth2 element was also introduced to Gadget ModulePrefs.
The API in OpenSocial 2.0.1 is based upon revision 22 of the OAuth 2.0 draft specification
which is currently under AD evaluation at IETF.
OpenSocial 2.0 continues to support OAuth 1.0a in addition to OAuth 2.0.
List of
opensocial-resources
project issues published in OpenSocial 2.0.1 is accessible at http://bit.ly/os201publishedspecissues.
Published August 18, 2011The community determined, that in practice, use of the ATOM serialization format of OpenSocial
information was not utilized. In addition, there are also several adjacent community driven
specifications that use JSON as the preferred data format. As a result, the community decided to
simplify the specification and deprecate the requirement to support ATOM as a serialization format.
OpenSocial 2.0 introduces support for ActivityStreams. This is to support two primary use cases.
First, activity streams provides a richer, more complete data model. Second, it is the desire and
intent of OpenSocial to be interoperable with as many systems as possible. Leveraging Activity
Streams allows OpenSocial containers to exchange information with other systems that may or may not
support this standard. As part of this, additional, optional fields have been added to OpenSocial
Collection. The existing Activity format and API has been deprecated and will be removed in a later
release.
OpenSocial 2.0 introduces some changes that simplifies how Gadgets can define Templates and perform
Data Pipelining within a Gadget's specification. An inlined template had to previously be defined
within a script tag, but now it's possible to define a template library within a Gadget specification.
At the time of this release the OAuth 2.0 specification was not finalized.
So in order to allow flexibility to adjust to changes in the OAuth 2.0 specification,
OAuth 2.0 support in OpenSocial 2.0 is incubating. The API in OpenSocial 2.0 is
based upon revision 20 of the OAuth 2.0 draft specification. Note that OpenSocial 2.0
continues to support OAuth 1.0a.
In OpenSocial 2.0, a new optional specification has been added for a common
container API. The goal is to simplify container and gadget integration model. It provides a set
of common services that Container developers can leverage for features like in-browser Gadget lifecycle event
callbacks, embedded experiences, and selection and action handlers.
List of
opensocial-resources
project issues published in OpenSocial 2.0 is accessible at http://bit.ly/os20publishedspecissues.
Published November 18, 2010
As OpenSocial continues to be adopted, especially in enterprise
environments, there was a desire by the community to include support for advanced mashup scenarios, specifically, those where gadgets could securely message each other in a loosely coupled manner. OpenSocial 1.1 includes support for this capability, informally known as pub-sub.
Version 1.1 officially
support an inter-gadget eventing system based upon the OpenAjax
Hub. "The OpenAjax Hub is a set of standard JavaScript functionality
defined by the OpenAjax Alliance that addresses key interoperability
and security issues that arise when multiple Ajax libraries and/or
components are used within the same web page." By incorporating this technology into OpenSocial, gadgets are now able to declare, as part of the module definition, events to which they are able to publish and subscribe. In addition, this specification has reserved several topic namespaces for use by OpenSocial.
Please refer to the Inter-Gadget Eventing in the Core-Gadget specification for more information.
Version 1.0 of the specification contained duplicate language and inconsistencies in the language around the use of OAuth. This version attempts to clean up these and present a more consistent usage model.Published March 9, 2010With so many different types of websites adopting OpenSocial it has become clear that a "one size fits all" approach isn't appropriate for the OpenSocial spec. Containers have different types of data they want to make available to clients (sometimes it's social data, sometimes it's not), and some want to expose that data via web services, while others wish to use gadgets. As such, modularity was a key goal in the OpenSocial 1.0 iteration, allowing implementers to pick and choose the elements of OpenSocial that make sense for their use cases. OpenSocial 1.0 also defines extension points so containers can add functionality not covered in the spec, but do so in a standard way, making it easier to fold such extensions back into the spec or share extensions across containers.To accommodate the varied use cases of OpenSocial containers, the Compliance section has been revised to include four compliance models:Core API Server - For containers that wish to expose data in a standard way though web services.Core Gadget Server - For containers that simply want to be able to render gadgets.Social API Server - For containers that wish to expose social data through standard web services that are consistent across containers.Social Gadget Server - For containers that want to render gadgets and provide them access to standard social data.The spec itself has been reorganized along these lines as well, consolidating all data definitions into the Core-Data.xml and Social-Data.xml files, and creating a separate file for each of the four compliance models.A new Extensions section defines how containers can extend OpenSocial in a common way so that extensions can be shared across containers, even if they're not appropriate for the official OpenSocial spec.Features included in a gadget spec should now be versioned. If no version is specified, the default value is '1.0'.OpenSocial v0.9 defined a groups REST service, so OpenSocial 1.0 adds definitions for the JavaScript API and RPC endpoint.The opensocial.* namespace has been largely deprecated in favor of the osapi.* API.Added text to make it clear the 'friend' may refer to any relationship (e.g. colleague, classmate, etc.).Variables may be declared in both inline and custom tag templates with the os:Var tag. This tag may also be used data pipelining to declare global literal variables.The spec now decalres that variable keys are case-sensitive both for Data Pipeline tags and for template parameters.Added a 'Request' field to the object returned in data pipelining responses so developers can access information about the request that initiated the request.Introduces a "SecurityProfile" feature that gadgets can include to specify if they want EL functions to HTML escape strings or not.Added language stating that only one value is allowed for a given parameter and define behavior where namespaces are used.The content in this section was split up and distributed to the appropriate sections in the spec. For example, the overview of data objects like people, activites, and messages now live in Social-Data.xmlAdded documentation for the elements in a gadget XML spec and removed the Metadata and JavaScript Request sections.MediaItem object now have a 'title' field and the 'caption' field has been deprecated.The spec now uses 'birthday' throughout.Several typos and inaccuracies that we're pointed out since v0.9 was published.Several field names have been changed. Containers should continue to support the old values to avoid breaking existing gadgets. App developers should use the new field names for all new gadgets.Old field nameNew field nameAccount.useridAccount.userIdAddress.extendedAddressRemoved. Use Address.streetAddressAddress.poBoxRemoved. Use Address.streetAddressAlbum.captionAlbum.titleName.additionalNameName.middleNamePerson.appdataPerson.appDataPerson.dateOfBirthPerson.birthdayPerson.languagesRemoved. Use Person.languagesSpokenPublished April 15, 2009The major focus of OpenSocial v0.9 was to make application development,
testing, and deployment easier and faster, while reducing the learning curve
for new app developers.OpenSocial v0.9 introduces a new
Lightweight
JavaScript API that makes requesting and parsing data simpler. The
new API has all the power, flexibility and granularity of the old one, but
the code speaks for itself:For backwards compatibility, the new API is available in a separate
namespace, “osapi” which can be activated with a <Require
feature="osapi"> directive. All the old APIs are still available via
<Require feature="opensocial-0.9">, so existing applications can
continue working. However, for new application development, the new
lighter API is the smarter choice. Not only will you save time typing, but
your JS code will be significantly reduced, improving download times.In its first iterations, OpenSocial was limited to running AJAX
applications inside social networks. However, testing an app that is
rendered by someone else's server has proven difficult and the heavy
reliance on JavaScript meant that lots of server-side web programming
skills were under-utilized.Some developers even come up with ways to cram their old way of
developing web applications into the OpenSocial model – using a
makeRequest() to download HTML contents from a URL on their servers, and
then stuff the result into an element’s innerHTML somewhere on the page.
Clearly these developers were sending us a powerful signal we couldn’t
ignore.Proxied
Content is a formal way for the same use case to be achieved. It
allows developers to specify a URL for a given <Content> block in
their gadget spec rather than inline JavaScript and HTML.When the given view is requested, the container will make a request to
the URL specified (or fetch the data from cache) and render the HTML
returned directly in the browser.This small code change introduces several advantages:Provides a simpler pathway for converting existing web applications
into OpenSocial apps.Allows containers to sanitize content before rendering, protecting all
the parties involved.Reduces the number of server round-trips required to render an
application, especially when combined with data pipelining. Fewer round
trips significantly reduces latency for end users.A common pattern in OpenSocial apps to date is for apps to request
social data from the container when first loaded using a DataRequest, then
send that data to remote servers using a makeRequest. Using JavaScript to
perform these operations requires the container to load the app's IFrame
before any requests are made, leaving the end user staring at a
'Loading...' message.Data
Pipelining defines a simple declarative XML language that allows the
developer to specify what social data their application will need, so the
container can make that data immediately available by including it in the
app's IFrame. When used with proxied content, the social data is sent to
the URL specified in the href attribute of the <Content>
element.In this example, the container sends the viewer's information to the
given URL (i.e. http://www.example.com/userInfo.php), where the PHP file
can access the viewer's ID and return HTML containing the appropriate
information for that user.Until now, the standard approach to rendering data into OpenSocial apps
has involved manipulating a DOM element's innerHTML and/or dynamically
creating DOM elements. These methods for generating UI can be unwieldy,
difficult to maintain, and aren't easily reusable. For example, imagine
handing off the following snippet to a HTML/CSS programmer to improve the
UI design:OpenSocial Templates give
you a straightforward approach to creating data-driven UI in OpenSocial
gadgets while separating markup from programming logic. The result is code
that is cleaner, more streamlined, reusable, and much easier to maintain.
With OpenSocial Templates, the example above becomes more
HTML-friendy:OpenSocial Templates also support looping and conditional display,
giving developers the flexibility to create elaborate UI elements with
less code.OSML Markup is
a series of special tags that can be used within templates – these tags
can be used to accomplish common tasks (such as displaying user Badges
with proper container “bling”), or to safely perform what would otherwise
be unsafe operations (for example, including a Flash movie while
restricting its access or executing JavaScript within the container memory
space).OSML is extensible. All containers must provide a small set of standard
tags, but each container is free to add its own extension tags (although
cooperation is encouraged to avoid conflicts). Furthermore, app developers
can create Custom Tag templates to build up a library of OSML tags to be
used in their own applications.Several changes to ensure
that the data formats for OpenSocial REST and Portable Contacts are
compatible.Adds support for
startIndex and count parameters when requesting activities.Adds support for rewriting the content of
a gadget and allows developers to control the behavior of the rewriter by
introducing a new optional feature "content-rewrite". The content-rewrite
feature defines a set of rewriting operations that a container can perform
on rendered and proxied content and rules to allow developers to control
which content the rewriter can operate on.Adds support for accessing photos and
other media items.Allows upload of files through REST and
JSON-RPC calls to the OpenSocial container. This mechanism can be used to
support many capabilities such as uploading audio/video/image content to
the container for inclusion in a user's album or creating activity stream
entries that contain uploaded media item content.Exposes JavaScript functions which can be
used by developers and libraries to output logging information. This
creates a single place for developers to look when debugging their
application, smoothing over a barrier to adoption.Adds internationalization support
for currency, date time, and numeric formatting.Provides an additional mechanism for gadget
developers to control the lifecycle of specific HTTP content cached by
OpenSocial containers beyond what is already available through standard
HTTP cache control headers. This capability allows developers to
explicitly invalidate the content the container has fetched on behalf of a
user (via proxied rendering or authenticated/signed makeRequest calls) and
static resources such as gadget specs and message bundlesExtends the current messaging model to
support read/write access via JavaScript and REST/RPC.Using OAuth from a gadget requires opening a
pop-up window to the OAuth service provider. We've added a JavaScript
method to handle the some nuances required to get this right and provide a
good user experience, such as avoiding popup blockers and detecting when
the popup has been closed.Allows developers to define named
views in their gadget spec and navigate to these views using JavaScript or
templates.Allows per-user key/value pairs
stored on the container to be accessed as if they were extended profile
fields.NonePublished September 25, 2008The server-to-server protocols are the primary focus of version 0.8.1.
The Person schema has been aligned with the Portable Contacts effort, and an
optional RPC proposal has been added.Server to server functionality has
been expanded with the addition of a
JSON RPC protocol, which will
allow for simpler batching of requests. To maintain naming consistency,
the RESTful API is now known as the RESTful protocol.
OpenSocial IDs may now contain "-", "_", and "." in addition to
alphanumeric characters.The RESTful protocol has
renamed or deleted many query and response fields. Please consult the
following list of RESTful protocol changes for more detailed
information.By implementing the
RESTful protocol, a container now becomes technically compatible with the
Portable
Contacts specification. Many of the following changes were
implemented to facilitate this compatibility.Requests will support the
format=xml parameter. People requests must be made in either format=xml or
format=json.
Containers are now required to implement paging of results via the
startIndex and itemsPerPage parameters.This parameter
has been removed from JSON Collection responses.This parameter has
been removed from JSON collection responses.It
should be possible to return all the requested contacts in a single
request, however containers may choose to limit the maximum items returned
per request for performance reasons.It is up to each container to
define the number of contacts returned when no itemsPerPage parameter is
specified in a request.The orderBy parameter has been
renamed to sortBy. A new sortOrder parameter has been introduced, with
values ascending and descending. The default value of sortOrder is
ascending.Queries may now specify
that results only contain entries that have been updated in a specified
interval.
Since sorting and filtering on arbitrary fields can be too expensive for a
container to support, responses now contain top-level response fields
filtered, sorted, and updatedSince, to indicate whether the content in the
response was filtered according to the original request.Using a new
@deleted selector and the updatedSince parameter, it is possible to
retrieve all contacts that were deleted since the supplied date.
Containers must return at least a name and an id when returning Person
data.The value returned in the
profileUrl Person field MUST also be returned in the urls field, as a
type=profile entry.Person records now include a photos
field, which will contain a list of entries with sub-fields url, type and
primary. If the thumbnailUrl field is returned on a Person object, this
url must also be present in the photos field, as a type=thumbnail
entry.Person records now include an ims
field, which will contain a list of entries with sub-fields value,
type,and primary. The type values of "aim", "gtalk", "icq", "xmpp", "msn",
"skype", "qq" and "yahoo" are defined to match several commonly used
services, although new types may be defined as well.Person records now include an
accounts field, used to represent other services where the Person has
accounts. This field will contain a list of entries with sub-fields
domain, userid, username, and primary.The emails,
urls, ims, phoneNumbers, addresses, organizations, and photos Person
fields will recieve an additional primary sub-field which will indicate
which field in the list (if any) is the "primary value" of that type.
Entries for jobs and schools will be combined into one array of
Organization structures named organizations. The Organization structure
will be extended with a type sub-field, with canonical values of "job" and
"school".The
primary textual value of plural Person fields should be stored in a
sub-field named value. This will require renaming emails.address,
phoneNumbers.number, urls.address and all instances of the {Enum}.key
field to {Enum}.value. The addresses, accounts, and organizations fields
are complex and do not have the concept of a value field. For the purposes
of sorting and filtering, the corresponding "primary" sub-fields on these
fields will be addresses.formatted, accounts.domain, and
organizations.name.Person records will
now treat gender as a string field, with the canonical values of "male"
and "female".
The extendedAddress and poBox Address subfields have been removed in favor
of storing a complete (and potentially multi-line) address in the
streetAddress sub-field.The
unstructuredAddress sub-field of an Address is renamed to formatted.The dateOfBirth Person field
is renamed to birthday.The timeZone Person field is
renamed to utcOffset.The nickname Person field is now
defined as "the casual way to address this person in real life".If a Person
request is missing the fields query parameter, the minimal set of fields
that must be returned by default have been defined as id, name, and
thumbnailUrl, to match the defaults for the JS API.The RESTful protocol now defines
the endpoints /people/@supportedFields and /activities/@supportedFields,
which will return lists of the Person and Activity fields supported by the
container.The indexBy query parameter has been
removed.The Activity
title field is now treated as a string that may contain HTML markup,
instead of a complex data object.The unstructured Name field
is renamed to formatted.The displayName field is added
as a required top-level Person field.A new, optional
JSON RPC protocol has been
introduced to simplify batching and complex server-to-server
operations.This enum may be used to
construct an IdSpec object, using either the values of
opensocial.IdSpec.GroupId.FRIENDS and opensocial.IdSpec.GroupId.SELF.The return values for
opensocial.Environment.supportsField() calls have been defined as true
when a container supports a field, and false otherwise.The
<Preload> element now supports the value of "oauth" for its authz
attribute. If authz=oauth is specified, then the oauth_service_name,
oauth_token_name, oauth_request_token, and oauth_request_token_secret
attributes will be accepted. These attributes have the same semantics and
defaults as their corresponding gadgets.io.makeRequest parameters.Published May 27, 2008The OpenSocial specification now requires that containers
implement a REST based API according to the RESTful API specification. This
allows for servers, mobile devices, and desktop applications to interact with
OpenSocial containers. See the
specification for details.Version 0.8 introduces several changes to the OpenSocial JavaScript APIs
that are not compatible with previous versions. Because most containers
support multiple API versions, existing gadgets will continue to use the
0.7 API and will work as before. However, gadgets that are updated to take
advantage of 0.8 features will have to use the newer versions of these
changed APIs. The incompatible changes are:Instead,
use an IdSpec object with the appropriate NETWORK_DISTANCE parameter. See
the
API documentation for details.opensocial.Person.Field.LOOKING_FOR used
to return a string, now returns an opensocial.Enum.LookingFor object.Automatic data
escaping has become easier to control with the addition of an escapeType
parameter to the newFetchPersonAppData and getField methods, which allow a
developer to specify whether the returned data should be escaped.All data stored in the
Persistence API is now treated as JSON-encoded. This allows for easier
storage of complex objects as well as smart data escaping by the
container.The
newRemovePersonAppDataRequest method was introduced to allow
developers to delete stored data from the Persistence API.The Person object has new
hasApp and
networkPresence fields. The lookingFor field has been changed to a
more structured format.The new
IdSpec object provides a structured way to define a group of people,
including a NETWORK_DISTANCE parameter which will allow for querying
friends of friends.The new
topFriends and isFriendsWith fields allow developers to filter the
results of Person requests in new ways.The Message object now has
titleId and bodyId fields so that messages can use templates in the same
way that activities do.Responses may now contain the new
limitExceeded error code to indicate that a quota was exceeded by
the request.The
getContainerUrlTemplate method was added to simplify constructing
navigation URLs.A container is now able to specify a template for the
application's URL, so developers can construct navigation links without
making synchronous JavaScript calls.The
requestShareApp method now lets the developer set navigation targets that
application users will see, both after accepting invites and also when
sharing the application with friends.The
gadgets.io.AuthorizationType.AUTHENTICATEDparameter has been deprecated in
favor of the newly added gadgets.io.AuthorizationType.OAUTH. Gadgets may
now consume web services requiring OAuth authorization.The
description of signed makeRequest calls has become much more detailed in
the spec. The names of parameters that containers may or must include have
been standardized, and key management practices are spelled out in
detail.Calls to
gadgets.io.getProxyUrl and gadgets.io.makeRequest may now include a
parameter specifying how often the container should refresh the content
which lives at the supplied URL.
Calls to gadgets.views.requestNavigateTo may now specify an OWNER's ID
number in order to navigate between viewson different users' profiles.The gadgets.util.sanitizeHtml
method was added to convert potentially malicious HTML code to text safe
for display.The gadgets.views.ViewType
enumeration has been modified to reflect the most well-known set of views:
HOME, PROFILE, CANVAS, and PREVIEW.
The new PubSub feature enables developers to send data between multiple
gadgets on the same view.Message bundles can now
be inlined into the gadget XML, and no longer have to be in a separate
file.
Gadgets can use the new <Preload> element to instruct the container
to fetch data from a remote source during the gadget rendering process.
This data will be inlined in the rendered output and available immediately
when gadget code is executed. Use of this method should reduce latency for
gadgets that depend on content from remote servers to render.The new
<Preload> element also supports preloading responses from signed
requests. Developers should add the authz="signed" attribute and value to
the <Preload> element to specify that a request for the URL should
be signed by the container.
There is a new <Link> element that can be used within the gadget
ModulePrefs section. This change is intended to allow containers to
support new link types, such as gadgetsHelp and gadgetsSupport.
To improve localization support, substitutions are now supported for all
hangman variables that get displayed to users (e.g. all Module.ModulePrefs
attributes, UserPref@display_name)The
ModulePrefs section can now be used to specify URLs for usage of
OAuth.
Gadgets now support lifecycle events. You can place link tags in gadget
xml that specify URLs the container should hit when a specified type of
event occurs. This way, a gadget can be notified of all app installs or
uninstalls.
You can use the new preferredHeight and preferredWidth tags to specify
default height and width for each Content section.This means that gadgets
with multiple views can have different default heights.Published January 25, 2008Version 0.7 of the OpenSocial JavaScript API is intended to be the first
iteration that can fully support rich, social applications. All features are
covered in the
API Reference (v0.7), but differences between version 0.6 and version
0.7 are explained in this section.This release adds a
slew of standard fields that you can access about a Person. These include
location, schools, pets, movies, sports, and
more. However, keep in mind that a container may not have all of
this information available so your application should always check first by
using the supportsField method.Two new methods allow your
application to send messages on behalf of a user. You can invite a user's
friends to install your application with the requestShareApp method. You
can also send an application-specific message with the requestSendMessage
method. Both of these methods require the user sending the message to
authorize the request first.You can now define activity messages with
placeholders for pieces of applicaton or user data. This separation of data
and presentation allows multiple activities to be combined into activity
summaries?consolidated bundles of activities that let users know what their
friends are up to without having to wade through a flood of messages. For
example, instead of seeing five new updates about friends that installed a
new application, you would see one update that says five of your friends
added the application. For details on how to use activity templates in your
application, see
opensocial.Activity in the OpenSocial API reference.Support for global and
instance-scoped application data has been removed from the API. Global
application data can be implemented using feeds (that can be prefetched for
performance) and other web standards. Instance-scoped application data can
be implemented on top of user-scoped data by including the module ID of the
application in the key.As part of the Apache Shindig project, gadgets have been open sourced.
The new
Gadgets
Specification defines the gadgets.* JavaScript namespace where you'll
find that some of your favorite methods from the Gadgets API have been
re-namespaced into a cleaner API for your convenience and clarity. For
example, _IG_Adjust_IFrame_Height is now available as
gadgets.window.adjustHeight (and don't worry, these updates are backwards
compatable, so the old methods will work with Shindig-based renderers).Some notable updates in the Gadgets API include:The Gadgets API
provides methods that allow your application to get more information about
how a container will render your gadget. You can get information about the
dimensions available for your gadget with
gadgets.windows.getViewportDimensions, and obtain information for
internationalization, such as the country and language of the user, using
the gadgets.Prefs object. You can also use the gadgets.skins.getProperty
method to get information about the look and feel of the container, such
as the color of the font or background.The methods for getting
the current view, or navigating between views, have been removed from the
Environment class and now live in the gadgets.views.* namespace.The
Gadgets XSD has been extended to support multiple <Content>
blocks, where each <Content> block declares the views it should be
rendered on. You can also use gadgets.views.getCurrentView to get the
current view at run-time. For more information, see the
Gadgets
Specification.
The makeRequest method has been moved from the opensocial.* namespace to
gadgets.io.makeRequest. Also, two new fields, HEADERS and POST_DATA, have
been added to gadgets.io.RequestParameters so you can now send arbitrary
HTTP headers or POST data in your request.
The hasCapability method has been removed from the opensocial.Environment
class. To check whether a function is supported by your current container,
you now use gadgets.util.hasFeature.You can now use the stringify and
parse methods of the gadgets.json.* package to store objects using the
Persistence API without having to import a third-party library. See
the
OpenSocial API Reference for more info.Published December 21, 2007The OpenSocial JavaScript API (v0.6) introduces several new features.
These are all covered in the
API
Specification (v0.6), but differences between version 0.5 and version
0.6 are explained in this section.
The new Environment class includes a hasCapability method that takes a
function name and tells you if that function is available in your current
container. It also includes a supportsField method to check if a particular
field is supported in person or activity objects. These new methods allow
apps to cleanly handle container-specific extensions if they're provided.
The Environment class also includes a getDomain method, which tells you
which site you are in (such as orkut.com or myspace.com). However, keying
on domain should only be used if the more explicit environment variables
aren't sufficient.This
release also adds a new Surface class. You can use
opensocial.requestNavigateTo to take your gadget from one page of a
container to another (for example, to link the profile to the canvas page).
This call takes a Surface object, which you get from an Environment object
(opensocial.getEnvironment()). The environment's getSupportedSurfaces
method tells you which surfaces the container supports, and getSurface
tells you which one you are currently on. The getParams method returns all
of the parameters passed in by the requestNavigateTo call if any were
requested. The Surface class currently has only two methods, getName and
isPrimaryContent, but more methods may be added as the API progresses.The beginning of tighter
permission control is introduced in v0.6. Now, when a gadget uses a data
request to fetch a viewer from the server, it is only returned if that
gadget has access. If the gadget does not have access, one of the newly
defined standard error codes, opensocial.ResponseItem.Error.UNAUTHORIZED,
is returned instead. A gadget can also check ahead of time for its access
by using the new opensocial.hasPermission call. If access is denied, you
can use opensocial.requestPermission to ask the viewer for the specified
permission. Of course, some containers may always grant viewer access, and
some may always deny, but now this decision is up to the container.Another addition
to the API is the new opensocial.makeRequest method. This is an enhancement
to the current gadget API
IG_Fetch... methods. The opensocial.makeRequest method allows for
POSTs as well as GETs, and you can specify whether you want your data fetch
to be signed or even authenticated.The Stream class is gone,
and its fields are now part of the Activity class. The summary field on the
Activity class has been removed because title and body seem to be
sufficient for most developer's needs. Folders were deprecated in 0.5 and
have been completely removed now.When requesting people, instead of using broad categories (e.g. BASIC,
MATCHING, FULL, and so on) for the
opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS value, you can
now specify an array of Person fields (which you should check in advance
with the supportsField method). Specifying fields instead of categories
allows you to tailor the calls to deliver exactly what you need.Lastly, the init method on the container has been deleted. Make sure to
use the requires tag in your gadgets to fetch opensocial. All other ways of
initializing opensocial in your gadget are deprecated.