OpenSocial Release Notes

• Version 0.7 - January, 25, 2008
• Version 0.6 - December 21, 2007

Release Notes for v0.7

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.

Introducing the Gadgets Specification

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.

Release Notes for v0.6

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:

• 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.