Gadgets for GFC

Contents

1. Introduction
2. What's different?
3. OpenSocial 0.9 support
4. Signed request public key
5. Google Friend Connect APIs for gadget developers
   1. Disabling gadget caching
   2. Passing data into a Friend Connect gadget
6. Skinning gadgets
7. Gadget preferences
8. Tips and tricks
   1. Building a Friend Connect gadget for your website
9. Submitting your gadget
10. For more information

Introduction

OpenSocial gadget developers have new audience - the millions of sites that are already GFC-enabled, and are thus OpenSocial containers. Here are a few examples of OpenSocial gadgets that have been tuned for Google Friend Connect:

• iLike gadget : This gadget illustrates some of the techniques described in this document. To install it, visit the Google Friend Connect admin site, go to Social gadgets > Playlist gadget, and follow the instructions.
  
• Google sample gadget: This sample gadget illustrates some of the techniques described in this document. To install it, visit the Google Friend Connect admin site, go to Social gadgets > OpenSocial demonstration, and follow the instructions.
  

There are a variety of ways to take advantage of GFC as a gadget developer:

• Modify an existing gadget so that it runs gracefully in a GFC site.
• Design a new gadget to run effectively in Friend Connect sites.
• Host your own Friend Connect site to showcase your gadget.

This document describes how to develop gadgets to run effectively in Friend Connect. If you are new to OpenSocial and gadgets, see For more information for a list of documents you can read as an introduction.

Google Friend Connect supports the OpenSocial 0.9 specification for gadgets.

What's different?

This document focuses on what you need to know to write a OpenSocial gadget that works well in a GFC site. GFC sites have a few differences from traditional social networks such as hi5 or orkut:

• Site owners decide what gadgets to include in their site, not the visitor.
• Many of the visitors who visit the site never login, so your gadget needs to have a UI and presentation model that work for signed-in and unsigned-in visitors alike.
• OpenSocial people roles have a different mapping than in standard social networks. Read OpenSocial and GFC for a more detailed explanation of these differences.

If you prefer to do the bulk of your programming server-side rather than in JavaScript, see OpenSocial REST/RPC Protocol.

OpenSocial 0.9 support

Google Friend Connect supports OpenSocial Specification v0.9 for gadget development. This version added a number of important features for gadget developers to improve the gadget development process and the performance of their gadgets. These features include OSML, templates, proxied content, data pipelining and more.

Signed request public key

For authentication, Friend Connect uses the RSA_SHA1 signature method (as defined in the OAuth standard) and the following public key, presented here as a self-signed certificate that should be easy to import into OAuth libraries. For more discussion of this topic, see the articles Introduction to Signed Requests and Validating Signed Requests.

Certificate Location

http://www.google.com/friendconnect/certs/friendconnect.pem.

Certificate Text

-----BEGIN CERTIFICATE-----
MIICSjCCAbOgAwIBAgIJAKy5FQe8xeW/MA0GCSqGSIb3DQEBBQUAMCMxITAfBgNV
BAMTGGZyaWVuZGNvbm5lY3QuZ29vZ2xlLmNvbTAeFw0wODEyMTkxOTQ3NDlaFw0w
OTEyMTkxOTQ3NDlaMCMxITAfBgNVBAMTGGZyaWVuZGNvbm5lY3QuZ29vZ2xlLmNv
bTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAvvHLRIP0tKwFGExqfIOf25Ad
2WHq/Oz4CuuspA75pvXg5+w9E4P5oMNmGNENO7LAA+xSrXLND+FdDg4STH/5FW0Y
ycPhw7LvqsefQwnntn1oHGTYffWRPbovHZBDcCBJZ2cgzXnmsXG9D7rO06fikTaa
6aSw1mVt7sFvwZDegEkCAwEAAaOBhTCBgjAdBgNVHQ4EFgQUITh3OCFLiiyTPEsq
LKmuALCpfXwwUwYDVR0jBEwwSoAUITh3OCFLiiyTPEsqLKmuALCpfXyhJ6QlMCMx
ITAfBgNVBAMTGGZyaWVuZGNvbm5lY3QuZ29vZ2xlLmNvbYIJAKy5FQe8xeW/MAwG
A1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEAvnVl15uganMvEwABVxRwMAys
ICPuzrxvdgAHXDl1/FCv68CEbTatHYPHBTLiY66DL8HICWwFuIx4j0DTuj6IWHRG
iP2BFvtcRvogURixojA+JXsvIjafoShzqAioDptVUx1aIHM+af3B5zE6+wDVmRUz
1WeG3BvhoqPq1pUdWig=
-----END CERTIFICATE-----

Google Friend Connect APIs for gadget developers

The GFC JavaScript API provides the following methods specifically applicable to gadget developers:

Disabling gadget caching

To disable gadget caching, add the following line to the portion of the snippet (which you copied from the Friend Connect gadget set up page) that renders your gadget:

google.friendconnect.container.setNoCache(1);

For example:

<script type="text/javascript">

google.friendconnect.container.setNoCache(1);
google.friendconnect.container.renderOpenSocialGadget(
 { 'id': 'div-1234xxxxxx297',
   'url':'http://gadget-doc-examples.googlecode.com/svn/trunk/igoogle-profile-08.xml',
   'site': '05532xxxxxx509606791' });

</script>

Passing data into a Friend Connect gadget

To pass data into a Friend Connect gadget, use view-params. For example:

google.friendconnect.container.renderOpenSocialGadget(
  { id: 'div-1231709480881',
    url:'http://www.google.com/friendconnect/gadgets/lamegame.xml',
    'view-params': { 'name':'value'},
    site: '10563088438957768212'},
  skin);

Inside the gadget you can get the value as follows:

var params = gadgets.views.getParams();
var value = params['name'];

To use this technique, include <Require feature="views" /> in the ModulePrefs of your XML gadget spec.

Skinning gadgets

Each of the millions of the sites which use Google Friend Connect have their own color palettes. When designing and developing a gadget for Google Friend Connect, you should ensure that you allow the gadget to integrate well within all types of websites, whether they have white, black, or purple backgrounds and text.

At the time a site administrator installs a gadget, they can set the colors they want to use for that gadget, so the gadget integrates well with the style of the site. These colors are passed to the gadgets using the OpenSocial Gadgets.skins API.

Skin properties available for GFC gadgets:

In your gadget, you can use these properties by declaring the skins feature:

<Optional feature="skins"/>

Next, you can set the colors of your gadget using JavaScript:

$("someElement").style.borderColor = gadgets.skins.getProperty('BORDER_COLOR'); 

For more information on OpenSocial skins, see the gadgets.skins API reference.

Configuration prefs

Google Friend Connect uses the gadgets.Prefs functionality to define and configure preferences for a gadget. All preferences are defined in the XML gadgets specification, and site administrators are asked to provide the values for the preferences at the time they install the gadget on their site. More information on the XML definition for these preferences is available in the OpenSocial XML Reference.

Tips and tricks

Building a Friend Connect website for your gadget

Another popular use for Friend Connect is to create a standalone site for your OpenSocial gadget. To do this, pick a domain, and configure the site for Friend Connect in the usual way:

1. Add a sign-in gadget, so users can login.
2. Embed your gadget using the custom gadget page to start in canvas mode rather than profile mode in the code generator. This prevents the gadget from being switched back to profile mode.
3. Make sure the gadget URL you enter includes the 'http://' prefix. Edit the div sizes accordingly - you may want to use 100% width instead of a fixed-size div, and you probably have a better idea of the height than the default, so you can avoid odd resizing when the gadget loads.

Submitting your gadget

If you want to submit your gadget for inclusion in the Google Friend Connect Gadgets Gallery, follow the instructions on the gadgets submission page.

For more information

For more information on OpenSocial and gadgets, see the following:

• OpenSocial community wiki
• Official OpenSocial site: opensocial.org
• OpenSocial API Developer's Guide
• The OpenSocial Tutorial
• OpenSocial JavaScript API Reference
• Gadgets API Developer's Guide