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:
VIEWER_FRIENDS and OWNER_FRIENDS have been removed. Instead, use an IdSpec object with the appropriate NETWORK_DISTANCE parameter. See the API documentation for details.
opensocial.Activity.MediaItem is now opensocial.MediaItemopensocial.Person.Field.LOOKING_FOR used to return a string, now returns an opensocial.Enum.LookingFor object.
opensocial.DataRequest.prototype.newFetchActivitiesRequest now returns a Collection.
Greater developer control over data
escaping. 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.
Persistence data treated as JSON. 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.
A method to remove Persistence
data. The
newRemovePersonAppDataRequest
method was introduced to allow developers to delete stored data from the
Persistence API.
Additional
Person
fields. The
Person object has
new hasApp and
networkPresence
fields. The
lookingFor field has
been changed to a more structured format.
More flexibility when requesting
people. 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.
Additional filters for requesting
people. The new
topFriends
and isFriendsWith
fields allow developers to filter the results of
Person requests in new
ways.
Support for templates in
messages. The
Message object now
has titleId and
bodyId fields so
that messages can use templates in the same way that activities do.
Additional error
codes. Responses may now contain
the new
limitExceeded error
code to indicate that a quota was exceeded by the request.
Support for container URL
templates. 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.
Greater control over
requestShareApp
application
flows. 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.
Support for OAuth authorization. The
gadgets.io.AuthorizationType.AUTHENTICATED parameter
has been deprecated in favor of the newly added
gadgets.io.AuthorizationType.OAUTH.
Gadgets may now consume web services requiring OAuth authorization.
Clarification
of signed request functionality. 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.
Support for refresh intervals on proxied
content. 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.
Support for specifying a target OWNER when
navigating between
views. Calls
to
gadgets.views.requestNavigateTo
may now specify an OWNER's ID number in order to navigate between
viewson different users'
profiles.
A method to sanitize
HTML. The gadgets.util.sanitizeHtml
method was added to convert potentially malicious HTML code to text safe
for display.
Standardization of view
types. The
gadgets.views.ViewType
enumeration has been modified to reflect the most well-known set of views:
HOME, PROFILE, CANVAS, and PREVIEW.
A method for gadgets on the same view to communicate with each other.The new PubSub feature enables developers to send data between multiple gadgets on the same view.
Support for inline message bundles. Message bundles can now be inlined into the gadget XML, and no longer have to be in a separate file.
Support for preloading remote data during the
gadget
render. 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.
Support for signed requests when preloading
data. 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.
Support for link elements in ModulePrefs, for
container specific
links. 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.
Additional display fields that can use message
bundle substitutions. 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)
Support for specifying OAuth URLs in the
gadget spec. The
ModulePrefs
section can now be used to specify URLs for usage of OAuth.
Support for container lifecycle events such as install and uninstall. 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.
Support for specifying a
preferred height and width on each content section of the
gadget. 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.
Version 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.
Standardized profile information fields. 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.
Support for viral growth. 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.
Activity templates. 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.
Simplified persistence API. 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:
More ways to be "environmentally friendly." 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.
Views - formerly known as surfaces. 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.
Separate specifications for each view. 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.
Fetching remote content is now handled by the Gadgets API. 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.
Determining what features a container supports is now handled by the Gadgets API. 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.
Built-in JSON support. 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.
The 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 ability for a gadget to respond differently according to its environment.
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.
Support for navigating from one surface to another.
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.
Tighter permission control.
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.
Enhanced support for fetching remote content.
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.
Other changes and deletions
Activities have been streamlined as follows:
Stream class is gone, and its fields are now part of the Activity class.Activity class has been removed because title and body seem to be sufficient for most developer's needs. 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.
The copyrights in this specification are licensed under the Creative Commons Attribution 2.5 license | Terms of Service