English | Site Directory

OpenSocial Release Notes

Release Notes for v0.8.1

Primary focus of this version

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

OpenSocial specification changes

  • Server side API changes. 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 now allow "-", "_", and "." characters. OpenSocial IDs may now contain "-", "_", and "." in addition to alphanumeric characters.
  • Aligned with Portable Contacts.

Incompatible changes
  • RESTful protocol incompatibilities. 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.

RESTful protocol changes
  • Compatibility with PortableContacts. 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:
  • New format=xml response type. Requests will support the format=xml parameter. People requests must be made in either format=xml or format=json.
  • Containers MUST implement random access pagination. Containers are now required to implement paging of results via the startIndex and itemsPerPage parameters.
  • Removal of the link rel=next Collection field. This parameter has been removed from JSON Collection responses.
  • Removal of the author Collection field. This parameter has been removed from JSON collection responses.
  • Containers SHOULD support returning all contacts at once. 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.
  • Default itemsPerPage behavior. It is up to each container to define the number of contacts returned when no itemsPerPage parameter is specified in a request.
  • Changes to sorting parameters. 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.
  • New updatedSince query parameter. Queries may now specify that results only contain entries that have been updated in a specified interval.
  • Responses indicate whether sorting and filtering have taken place. 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.
  • Ability to request deleted Person objects. Using a new @deleted selector and the updatedSince parameter, it is possible to retrieve all contacts that were deleted since the supplied date
  • Person responses MUST contain at least the id and name fields. Containers must return at least a name and an id when returning Person data.
  • A profile URL is a URL, too. The value returned in the profileUrl Person field MUST also be returned in the urls field, as a type=profile entry.
  • New Person photos field. 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.
  • New Person ims field. 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.
  • New Person accounts field. 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.
  • Plural Person fields get a primary sub-field. 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.
  • Combine the jobs and schools plural fields to organizations. 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".
  • Plural Person fields standardize on a value field. 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.
  • The Person.gender field is now a string. Person records will now treat gender as a string field, with the canonical values of "male" and "female".
  • Addresses no longer contain extendedAddress or poBox sub-fields. 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.
  • Rename unstructuredAddress to formatted. The unstructuredAddress sub-field of an Address is renamed to formatted.
  • Rename dateOfBirth to birthday. The dateOfBirth Person field is renamed to birthday.
  • Rename timeZone to utcOffset. The timeZone Person field is renamed to utcOffset.
  • Definition of nickname. The nickname Person field is now defined as "the casual way to address this person in real life".
  • Default set of Person fields is specified. 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.
  • Query for supportedFields. 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.
  • Removal of indexBy. The indexBy query parameter has been removed.
  • The Activity.title field is now an HTML string. The Activity title field is now treated as a string that may contain HTML markup, instead of a complex data object.
  • Rename unstructured to formatted. The unstructured Name field is renamed to formatted.
  • New displayName field added. The displayName field is added as a required top-level Person field.
RPC protocol changes
  • Introducing the RPC Protocol. A new, optional JSON RPC protocol has been introduced to simplify batching and complex server-to-server operations.

opensocial.* JavaScript changes
  • New opensocial.IdSpec.GroupId enum. This enum may be used to construct an IdSpec object, using either the values of opensocial.IdSpec.GroupId.FRIENDS and opensocial.IdSpec.GroupId.SELF.
  • supportsField responses specified. The return values for opensocial.Environment.supportsField() calls have been defined as true when a container supports a field, and false otherwise.

gadgets.* JavaScript changes
  • No changes have been made to the gadgets.* JavaScript API.

Gadgets XML changes

  • Support for OAuth in the <Preload> element. 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.

Release Notes for v0.8

This document describes the significant additions and changes in version 0.8 of the OpenSocial API. All features are covered in the API Reference (v0.8).

OpenSocial specification changes

  • RESTful API. The 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.

Incompatible changes

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:

opensocial.* JavaScript changes

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

gadgets.* JavaScript changes

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

Gadgets XML changes

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

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.