General information & limitations
Hyves currently supports the OpenSocial 0.7 spec; the spec can be found at http://code.google.com/apis/opensocial/docs/0.7/reference/. In the future we'll be supporting new versions, while remaining backwards compatible with 0.7.
The following things should be taken into consideration when creating OpenSocial applications for Hyves:
- Viewer business rules
- Views sizes
- Linking to the canvas page
- Gadgets caching
- Signed requests
- Localization
- Gadget Messaging and Gadget invites
- Container Compliance test suite
- Appdata
- Additions
- Known limitations
- Relevant links
The Hyves container supports three views: profile, home and canvas (see Anatomy of a gadget). When installing a gadget, the user gets the choice of installing the gadget on the home view (where nobody else can see the gadget), his or her profile view, or both. Clicking on the title in either the home or the profile view navigates to the canvas view. There is also a function available for navigating to the canvas view, see the example on navigating between views
Viewer business rules
The application can get data on the viewer if:
- viewer == owner
- view == canvas (and view == home follows from rule 1)
- viewer has application installed on either home or profile
- viewer gives permission after an opensocial.requestPermission
- viewer has given permission before (after opensocial.requestPermission) and checked the "remember box"
In other cases, requesting the viewer will fail, and first requestPermission should be called
Views sizes
Click here
Linking to the canvas page
For security reasons (Cross Site Request Forgery) we cannot allow universal (=the same for every member) links to the canvas page. The canvas page for an application I have installed on my profile may be http://claude.hyves.nl/gapmember/1234/Nice_App/abcdefgh, whereas if you were to view the same app, the url would be http://claude.hyves.nl/gapmember/1234/Nice_App/abcdhgfe. If I were to share my url, and someone would click the link, he will be taken to a page with nothing but a redirect link to the app.
Gadgets caching
By default we cache the gadget XML. This cache gets refreshed on a regular basis; right now this is once per day somewhere between 12:00 AM and 7:00 AM GMT. This policy is for approved gadgets. If the gadget is not 'Live' and only available in a Sandbox, only minimal caching (title&height) is applied. In addition, we provide a manual way to do an immediate cache refresh of the gadget XML for 'Live' gadgets, located here: http://www.hyves.nl/api/opensocial next to the gadget in your 'Live Apps' list.
If you use external javascripts or images in your gadget, we may cache them as well. If you want to deploy a new version of the external file, use a different name to make sure it isn't cached. A good policy would be to use version numbers or a hash of the content in your file name.
Hyves will attempt to rewrite all of the URLs used in your application to pass through its proxy, caching the resources at those URLs in the process. To disable this URL rewriting mechanism, simply add the following block to your application spec's ModulePrefs element:
<Optional feature="content-rewrite"> <Param name="include-urls">.*</Param> //[REGULAR_EXPRESSION] <Param name="exclude-urls"></Param> //[REGULAR_EXPRESSION] <Param name="include-tags"></Param> //[COMMA SEPARATED LIST OF HTML TAG NAMES] </Optional>
A more detailed overview of Open Social resource caching and invalidation can be found in OpenSocialCaching.
Signed requests
It's possible to make signed requests using io.makeRequest(). Signing the request will make sure no one has tampered with the request and the data you receive was not changed by the user. For this to work you must set opt_params[gadgets.io.RequestParameters.AUTHORIZATION] to gadgets.io.AuthorizationType.SIGNED. The signature is done using the OAuth standard. Third-parties can validate this signature using our public key. The name of this key is sent with each request in parameter xoauth_signature_publickey.
- The full location of the public key is: https://secure.hyves.org/statics/gap/cert/<value of xoauth_signature_publickey>.
The contents of this file must be cached by you. A tutorial on validating the signature can be found here: http://wiki.opensocial.org/index.php?title=Validating_Signed_Requests. An introduction to io.makeRequest() can be found here: http://code.google.com/apis/opensocial/articles/makerequest-0.7.html.
An example of a signed request script can be found here.
Localization
Opensocial supports localization through gadgets.Prefs and the use of the XML Message files. The country is the country of residence of the viewer (as they have filled in on Hyves), the language is the language Hyves is currently in (nl or en). Note that OpenSocial has no way to differentiate between Dutch and Flemish. For example the include of a dutch XML message file: <Locale lang="nl" messages="http://www.example.nl/nl_ALL.xml"/>
Gadget Messaging and Gadget invites
We support 'opensocial.requestSendMessage'. You can find more info at OpenSocialRequestsendmessage (Note: there is a limit on sending messages that can be reached).
We also support 'opensocial.requestShareApp'. You can find more info at OpenSocialRequestshareapp.
Container Compliance test suite
We have tested Google's Container Compliance test suite against our container, some tests still fail but are not blocking. Some comments:
P0 - High priority - People/Person Requests Test Suite :: PPL602 - People/Person Requests Test Suite :: PPL504 - People/Person Requests Test Suite :: PPL502 - People/Person Requests Test Suite :: PPL601
These tests fail because of a timeout, if you use the functionality described in the test you'll find that it actually works. For some (yet unknown) reason the assertion methods in the test framework causes javascript execution to stop, which in turn causes the timeout. We are looking into this but shouldn't stop you from using this functionality.
P2 - Nice to have - People/Person Requests Test Suite :: PPLX03 - People/Person Requests Test Suite :: PPL503 - People/Person Requests Test Suite :: PPL506 - People/Person Requests Test Suite :: PPL801 - AppData Test Suite :: APP302 - AppData Test Suite :: APP004 - AppData Test Suite :: APP102 - AppData Test Suite :: APP002 - MakeRequest Test Suite :: SMKRT001 - MakeRequest Test Suite :: MKRT003 - MakeRequest Test Suite :: MKRT012 - MakeRequest Test Suite :: MKRT005 - MakeRequest Test Suite :: MKRT011
These tests are nice to haves. Mainly fail because of the same timeouts as described under P0. As soon as this issue is resolved they will probably work too.
Appdata
For posting and retrieving appdata you can use our AppData API. The lenght of the key with appdata can be no longer then 32 characters (you can store up to 10kb with each instance).
Note: With the API version 2.0 and beta_2 you will retrieve different ID's then are returned within OpenSocial. The 1.* version uses the same ID's
Additions
- Add params to the item-page-url to pass app_params/variables to the canvaspage, this way you can use this param-data in your gadget, for example:
- Addition to "opensocial.Environment.ObjectType.PERSON", 5 thumbnail sizes with "Hyves.Person.Field"
Known limitations
- Hyves does not support interaction between gadgets and the activity feed (called Buzz in Hyves terminology) yet. This means that the methods opensocial.Activity.*, opensocial.newActivity, and opensocial.requestCreateActivity return a not-implemented error. We hope to resolve this in a future release.
- No support for gadgets.io.ContentType.FEED in gadgets.io.makeRequest Currently, we don't have support for makeRequest calls with content type gadgets.io.ContentType.FEED. This is a bug on our side and we're planning to support this in the near future.
- OpenSocial gadgets can't be placed in groups or hubs (spots, companies, interests, brands, etc). At the moment an OpenSocial gadget is connected to a single Hyver.
- We do not support dynamic generated xml-urls (so ../gadget.xml is ok, but .../xxxxxx/gadget.xml where "xxxxxx" is dynamic is not possible). You can add app_params to the item page url.
- You can't place more than one instance of an OpenSocial gadget on a profile.
- OpenSocial gadgets can't be placed in scraps, messages, blogs, etc. It is possible to add a thumbnail with title, this is in a special format.
