| | | | |
. | Issue Id | Spec change | updated docs | Additional doc clarifications: |
. | PERSON-001, IS_FRIEND-001 | opensocial.Person.Field = {
...
/**
* A boolean indicating whether the person has used the current app.
* @member opensocial.Person.Field
*/
HAS_APP : 'hasApp',
...
}
opensocial.DataRequest.FilterType = {
...
/**
* Retrieves all friends that use this application.
*
* Note: Containers may define "use" in any manner they deem appropriate for
* their functionality, and it is not expected that this field will have the exact
* same semantics across containers
*
* @member opensocial.DataRequest.FilterType
*/
HAS_APP : 'hasApp',
/**
* Will filter the people requested by checking if they are friends with
* the given idSpec. Expects a filterOptions parameter to be passed with the following fields defined:
* - idSpec The idSpec that each person must be friends with.
* - networkDistance An optional parameter, used to specify how long the connection can be for
* two people to be considered friends. Defaults to 1 (they must be the same person or directly be friends). Containers
* can choose which values of this parameter they will support.
* As an example, 2 would mean "friend of a friend".
*/
IS_FRIENDS_WITH: 'isFriendsWith'
};
opensocial.DataRequest.PeopleRequestFields = {
// profileDetails, sortOrder, filter, etc
...
/**
* Additional options to be passed into the Filter. Specified as a Map<String, Object>.
*/
FILTER_OPTIONS: 'filterOptions'
...
} | x | The Icon element has a mode and a type attribute. The type attribute is simply the mime type of the image. The mode attribute only has one valid value, "base64". If the value is base64 and the inner content of the image tag must be a base64-encoded image. If the mode is not set then the content of the tag is a url pointing to the image.
|
. | MAKE_REQUEST-001 | /**
* Fetches content from the provided URL and feeds that content into the
* callback function. If the request is SIGNED will pass the following
* parameters along to the requested Url:
* - opensocial_viewer_id The id of the current viewer, will match the
* getId() value on the viewer person object
* - opensocial_owner_id The id of the current owner, will match the
* getId() value on the owner person object
* - opensocial_app_id The id of the current app
* - xoauth_signature_publickey The oauth for the container's public key
...
*
* @member gadgets.io
*/
makeRequest : function (url, callback, opt_params) { | x | |
. | REQUEST_NAVIGATE_TO-001 | * @param {gadgets.views.View} view The view to navigate to
* @param {Map.<String, String>} opt_params Parameters to pass to the
* gadget after it has been navigated to on the surface
* @param {String} opt_ownerId The id of the owner of the page to navigate to.
* Defaults to the current owner.
*/
gadgets.views.requestNavigateTo = function(view, opt_params, opt_ownerId) {}; | x | |
. | MESSAGE_BUNDLE-001 | <Locale lang="en" country="us">
<messagebundle>
<msg name="title">This is the message title.</msg>
</messagebundle>
</Locale> | TODO: Formalize this more | |
. | IDSPEC-001 | 1. Add a new opensocial.IdSpec object.
opensocial.IdSpec = function() {};
opensocial.IdSpec.Field = {
USER_ID : 'userId',
GROUP_ID : 'groupId',
NETWORK_DISTANCE : 'networkDistance',
}
opensocial.IdSpec.prototype.getField = function(key) {};
2. Change all IdSpec references to be opensocial.IdSpec
3. Change the filtering proposal to get rid of the networkDistance param as it is now within the idSpec
4. Add an idSpec supportsField type
| | |
. | PRELOAD-001 | add the "authz" attribute to the "Preload" element which defines the authorization type to use when doing the preload makeRequest | TODO: Formalize this more | |
. | MODULE_PREFS_SPEC-001 | <xs:element name="Link">
<xs:complexType>
<xs:attribute name="rel" type="xs:string" use="required"/>
<xs:attribute name="href" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Where "gadget help" and "gadget support" would be two rel values that
Orkut would support (and hopefully others). | | |
. | RESPONSE_ITEM-001 | opensocial.ResponseItem.Error = {
...
/**
* The gadget passed a quota on the request. Example quotas include a
* max number of calls per day, calls per user per day, calls within a
* certain time period and so forth.
*
* @member opensocial.ResponseItem.Error
*/
LIMIT_EXCEEDED : 'limitExceeded',
...
} | x | |
. | VAR_SUBSTITUTION-001 | 5. Perform substitutions of each hangman expansion on all fields which get displayed to users. This currently includes, but is not limited to, the following fields:
a. All Module.ModulePrefs attributes, Module.Content@href, Module.Content, UserPref@display_name, UserPref@default_value, and UserPref.EnumValue@display_value. | | |
. | DATA_STORE-004 | newRemovePersonAppDataRequest(idSpec, keys) | x | |
. | PUBSUB_FEATURE-001 | To publish a string-type message to a channel, a gadget calls:
gadgets.rpc.pubsub.publish(channel_name, message);
To subscribe to a message channel, a gadget calls:
gadgets.rpc.pubsub.subscribe(channel_name, subscriber_callback);
function subscriber_callback(message, sender) {
/* Do something with message if sender is a trusted gadget spec URL. */
}
To unsubscribe from a channel, a gadget calls:
gadgets.rpc.pubsub.unsubscribe(channel_name);
On the container side, the following function must be called to support "pubsub":
gadgets.rpc.pubsub.initializeRouter(gadget_id_to_spec_url_callback, {
onSubscribe: on_subscribe_callback, // optional
onUnsubscribe: on_unsubscribe_callback, // optional
onPublish: on_publish_callback // optional
});
function gadget_id_to_spec_url_callback(gadget_id) {
/* Given a gadget id, return the corresponding gadget spec URL. */
}
function on_subscribe_callback(gadget_id, channel_name) {
/* Return true to reject the subscription request; return false to accept it. */
}
function on_unsubscribe_callback(gadget_id, channel_name) {
/* Return true to reject the unsubscription request; return false to accept it. */
}
function on_publish_callback(gadget_id, channel_name, message) {
/* Return true to discard the message; return false to proceed to broadcast it to the channel. */
}
| x | |
. | OAUTH-002 | The simplest possible OAuth element declares that a gadget will use
OAuth with a service provider that supports OAuth discovery:
<ModulePrefs>
<OAuth>
<Service />
</OAuth>
</ModulePrefs>
OAuth discovery is new, and not many service providers support it yet.
The simplest possible OAuth element for a service provider that does
not support OAuth discovery declares three URLs used during the OAuth
protocol. Several reasonable defaults are assumed for some of the
OAuth protocol details.
<ModulePrefs>
<OAuth>
<Service>
<Request url="http://www.example.com/request"/>
<Authorization url="http://www.example.com/authorize"/>
<Access url="http://www.example.com/access"/>
</Service>
</OAuth>
</ModulePrefs>
The most complex OAuth element declares that the gadget will access
data from multiple OAuth service providers, and declares URLs and
several OAuth protocol details for all of them.
<OAuth>
<Service name="serviceOne">
<Request url="http://www.example.com/request"
method="GET"
param_location="header" />
<Authorization url="http://www.example.com/authorize"
method="GET"
param_location="header" />
<Access url="http://www.example.com/access"
method="GET"
param_location="header" />
</Service>
<Service name="serviceTwo">
<Request url="http://other.example.com/request"
method="GET"
param_location="header" />
<Authorization url="http://other.example.com/authorize"
method="GET"
param_location="header" />
<Access url="http://other.example.com/access"
method="GET"
param_location="header" />
</Service>
</OAuth>
OK, now that there are some examples to show how things ought to look,
let's get normative:
The <ModulePrefs> element can contain 0 or 1 <OAuth> elements.
The <OAuth> element can contain 1 or more <Service> elements.
The <Service> element has a single attribute:
name [optional]. This is a nickname the gadget will use to
reference the service provider. If unspecified, it defaults to "".
The <Service> element contains three elements, a <Request> element, an
<Authorization> element, and an <Access> element.
The <Request> element has three attributes.
url [required]: the absolute URL of the service provider request endpoint.
method [optional]: the HTTP method to use to access the
endpoint. May be GET or POST. If unspecifed, defaults to "GET".
param_location [optional]: the location of the OAuth parameters
in the request. May be "url", "header", or "body". If unspecified,
defaults to "header".
The <Access> element is identical to the <Request> element, but
describes an access token URL instead of a request token URL.
The <Authorization> element has a single attribute:
url [required]: the authorization URL for the service provider. | todo: translate to xsd | |
. | FILTER_TYPE-001 | opensocial.DataRequest.FilterType = {
/**
* Retrieves only the user's top friends as defined by the container. Not supported by all containers.
*
* @member opensocial.DataRequest.FilterType
*/
TOP_FRIENDS : 'topFriends',
...
} | x | |
. | MAKE_REQUEST-003 |
/**
* Fetches content from the provided URL and feeds that content into the
* callback function.
...
* If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set
to gadgets.io.AuthorizationType.SIGNED:
* This indicates that the container needs to vouch for the user's
identity to the destination server.
* The container will
* - remove any request parameters with names that begin with
oauth, xoauth, or opensocial (ignoring whether the parameter names are
upper or lower case.
* - add the following parameters to the request query string
* opensocial_viewer_id: (optional) The id of the current
viewer, which will match the
* getId() value on the viewer person object.
* opensocial_owner_id: (required) The id of the current
owner, which will match the
* getId() value on the owner person object.
* opensocial_app_url: (required) The URL of the application
making the request. Containers may alias multiple application URLs to
a single canonical application URL in the case where an application
changes URLs.
* opensocial_instance_id: (optional) An opaque identifier
used to distinguish between multiple instances of the same application
in a single container. If a container does not allow multiple
instances of the same application to coexist, this parameter may be
omitted. The combination of opensocial_app_url and
opensocial_instance_id will always uniquely identify an instance of an
application in a container.
* opensocial_app_id: (optional) An opaque identifier for the
application, unique to a particular container. This parameter is
optional. Containers that wish to maintain backwards compatibility
with the opensocial-0.7 specification may include this parameter.
* xoauth_public_key: (optional) An opaque identifier for the
public key used to sign the request. This parameter may be omitted by
containers that do not use public keys to sign requests, or if the
container arranges other means of key distribution with the target of
the request.
* - sign the resulting request according to section 9 of the OAuth
specification (http://oauth.net/core/1.0/#signing_process)
*
* Key management for gadgets.io.AuthorizationType.SIGNED:
*
* If a container uses public keys to sign request, the container may
choose to use either
* self-signed certificates or certificates signed by a well-known
certificate authority.
* If a container does not distribute their oauth signing key over
https, they should use a certificate signed by a well-known
certificate authority.
*
* The commonName attribute of the certificate should match the
hostname of the container server, and should also match the value of
the oauth_consumer_key parameter specified in the request.
*
* The container should make their public key available for download
at a well-known location. The location
* https://<container-hostname>/opensocial/certificates/<xoauth_public_key
value> is recommended.
*
* Recipients of signed requests must verify that the signature on
the request is correct, and that the timestamp on the request is
within a reasonable time window. A time window of +-5 minutes from
the current time is recommended.
*
* Recipients of signed requests may use the oauth_consumer_key and
xoauth_public_key parameters to automatically detect when a container
deploys new certificates. If the container deploys certificates at a
well-known location, the recipient may automatically download the new
certificate. Recipients who automatically download new certificates
should cache the resulting certificates.
*
* If a container's certificate is not downloaded from
https://<container-hostname>, the recipient should verify that the
certificat is signed by a well-known certificate authority before
trusting the certificate. | x | |
. | DATA_RESPONSE-001 | add dataResponse.getErrorMessage() | x | |
. | MESSAGES-002 | Add two new message fields: titleId and bodyId for use with templates. In the docs, activity templates will be renamed message templates and their description will be taken out of the activity.js file. | x - still need to move the message template description somewhere better though - outside of activity.js | |
. | MEDIA_ITEMS-001 | Rename opensocial.Activity.MediaItem to just opensocial.MediaItem. Rename opensocial.newActivityMediaItem to opensocial.newMediaItem.
| x | |
. | GET_PROXY_URL-001 |
Change
gadgets.io.getProxyUrl(url)
to
gadgets.io.getProxyUrl(url, opt_params)
Add a new option REFRESH_INTERVAL to control the TTL for proxied
content. Recommend that the default be 1h (3600 seconds)
Add
<static> object REFRESH_INTERVAL
Attempt to use content caching. The Refresh Interval is the number
of seconds we want to cache the given response. The default is 3600
(1 hour). Note that Signed requests and object with POST_DATA
present will generally not be cached.
to gadgets.io.RequestParameters | x | |
. | MAKE_REQUEST-003 | /**
* Fetches content from the provided URL and feeds that content into the
* callback function.
...
If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set
to gadgets.io.AuthorizationType.OAUTH:
This indicates that the container needs to use OAuth to gain access to
the resource specified in the request.
This may require that the gadget obtain the user's content by
directing the user to the service provider to gain access.
The following additional parameters may be specified in opt_params:
gadgets.io.RequestParameters.OAUTH_SERVICE_NAME:
The nickname the gadget uses to refer to the OAuth <Service>
element from it's XML spec. If unspecified, defaults to "".
gadgets.io.RequestParameters.OAUTH_TOKEN_NAME:
The nickname the gadget uses to refer to an oauth token granting
access to a particular resources. If unspecified, defaults to "".
Gadgets can use multiple token names if they have access to
multiple resources from the same service provider. For example, a
gadget with access to a contact list and a calendar might use a token
name of "contacts" to use the contact list token, and a contact list
of "calendar" to use the calendar token.
gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN
A service provider may be able to automatically provision a
gadget with a request token that is preapproved for access to a
resource. The gadget can use that token with the OAUTH_REQUEST_TOKEN
parameter. This parameter is optional.
gadgets.io.RequestParamters.OAUTH_REQUEST_TOKEN_SECRET
The secret corresponding to a preapproved request token. This
parameter is optional.
If OAuth is used, the container should execute the OAuth protocol on
behalf of the gadget. If the gadget has not registered a consumer key
for use with this service provider, the container may choose to use a
default RSA signing key corresponding to a well-known certificate to sign
requests. If the container uses a default consumer key, it will include
an additional OAuth parameter xoauth_app_url that identifies the gadget
making the request.
The makeRequest callback parameter is passed a javascript object with
several OAuth specific fields in addition to the normal values returned
by makeRequest:
"oauthApprovalUrl": if this value is specified, the user needs to
visit an external page to approve the gadget's request to access
data. Use of a pop-up window to direct the user to the external
page is recommended. Once the user has approved access, the gadget
can repeate the makeRequest call to retrieve the data.
"oauthError": if this value is specified, it indicates an OAuth
related error occurred. The value will one of a set of string
constants that can be used for programmatically detecting errors.
The constants are undefined for opensocial-0.8, but implementers
should attempt to agree on a set of useful constant values for
standardization in opensocial-0.9.
"oauthErrorText": if this value is specified, it indicates an
OAuth related error occurred. The value is free-form text that
can be used to provide debugging information for gadget developers. | x | |