OpenSocial and GFC

When a website uses Friend Connect, it turns the site into an OpenSocial container. This means that the site can:

• Run OpenSocial gadgets with full access to the OpenSocial API, just as these gadgets would run on MySpace and other OpenSocial containers.
• Access the OpenSocial API from its pages.
• Use the REST API to access social data.

As a developer writing gadgets for a Friend Connect site, you should note that a container powered by Google Friend Connect has some differences from the more common social network model (represented by OpenSocial containers such as orkut, MySpace, and so on). If you want your gadget to run effectively in Friend Connect, you need to design it to gracefully handle these differences.

Currently Friend Connect supports the OpenSocial 0.9 specification for gadgets and the 0.8 specification for the site-owner JS API. The OpenSocial API includes these major features:

• People -- Members of social networks have friends. OpenSocial applications use the connections between people and their friends. For a general discussion of this topic, see the OpenSocial Developer's Guide. For more discussion of people within Friend Connect, see Accessing people and profiles .
• Activities -- OpenSocial exposes activity streams, which are a collection of actions a user has taken in the context of a given container. For a general discussion of this topic, see the OpenSocial Developer's Guide. For a discussion of activities within the context of Friend Connect, see Activities.
• Persistence (app data) -- OpenSocial defines a data store that applications can use to read and write per-user and per-application data. For a general discussion of this topic, see the OpenSocial Developer's Guide. For a discussion of app data within the context of Friend Connect, see Persistence (app data).

Contents

1. Accessing people and profiles
   1. OWNER
   2. OWNER FRIENDS
   3. VIEWER
   4. VIEWER FRIENDS
   5. ADMINS
   6. People API summary
   7. Profile data
2. Tips and tricks
   1. Detecting when a user is not logged in
   2. Accessing site admins programmatically
3. Activities
   1. Activities API summary
4. Persistence (app data)

Accessing people and profiles

In conventional social network containers such as orkut and hi5, concepts such as owner and viewer have a particular meaning. The names are the same in Friend Connect container, but the meanings are different, as described below.

OWNER

req.newFetchPersonRequest('OWNER') returns the site's profile information.

In other words, you can't use this method to access the user that created the site. To programmatically access the site's owner and other administrators, see Accessing site admins programmatically.

OWNER FRIENDS

req.newFetchPeopleRequest(new opensocial.IdSpec({'userId' : 'OWNER', 'groupId' : 'FRIENDS'})) returns the site's members.

VIEWER

req.newFetchPersonRequest('VIEWER') returns the logged-in user. Remember that you need to handle the anonymous user case. This is because all users start out not logged-in until they join this specific site.

VIEWER FRIENDS

req.newFetchPeopleRequest(new opensocial.IdSpec({'userId' : 'VIEWER', 'groupId' : 'FRIENDS'})) returns the user's friends who are also members of the site. Again this is often an empty set initially (unless it is a popular site that is visited by a number of people in the user's friend graph), both for non-logged-in users and for those who have no friends who have yet joined the site. Make sure your gadget makes sense in this state, as it will often be the first impression people get of it.

ADMINS

opensocial.DataRequest.newFetchPeopleRequest(new opensocial.IdSpec({'userId' : 'OWNER', 'groupId' : 'ADMINS'})) returns profile information for the site's administrators.

People API Summary

This table summarizes the data that is returned when you use the OpenSocial API to fetch data for different roles in GFC.

Profile data

The OpenSocial API provides access to information about a Friend Connect site's members in the form of profile data. This section describes which profile fields are available in Friend Connect.

Supported fields

Friend Connect supports the following profile fields:

• opensocial.Person.Field.NAME -- The user's human-readable name.
• opensocial.Person.Field.ID -- The user's unique ID.
• opensocial.Person.Field.THUMBNAIL_URL -- The URL of the user's thumbnail image.
• opensocial.Person.Field.URLS (by request) -- The URLs the user has put on his or her profile.
• opensocial.Person.Field.ABOUT_ME (by request) -- The content of the user's "about" field.
• opensocial.Person.Field.PROFILE_URL (by request) -- a URL that points to the user's profile page.
  
• profileExtensions (by request) -- Google Friend Connect visitor interests data.
• profileAggregates (by request on the OWNER) -- aggregate Google Friend Connect visitor interests data for all visitors to the site.

Given a Person object, you can access the following fields by default:

• person.getId() - Returns a unique identifier for this user.
• person.getDisplayName() - Returns this user's human-readable display name.
• person.getField(opensocial.Person.Field.THUMBNAIL_URL) - Returns the URL of this person's thumbnail image.

You can request additional fields by passing the optional "profileDetail" parameter to your request:

var params = { 
  "profileDetail" : [ opensocial.Person.Field.ABOUT_ME,
     opensocial.Person.Field.PROFILE_URL,
     opensocial.Person.Field.URLS ] 
};

var req = opensocial.newDataRequest();
req.add(req.newFetchPeopleRequest(opensocial.newIdSpec({"userId" : "OWNER", "groupId" : "FRIENDS"}), params), "req");
req.send(callback);

profileDetail should be set to an array containing one or more of the following fields:

• opensocial.Person.Field.ABOUT_ME - Returns a the user's "about" field.
• opensocial.Person.Field.PROFILE_URL - Returns a URL that points to the user's profile page.
• opensocial.Person.Field.URLS - Returns a list of urls that the user has placed on his or her profile.

Access these fields by using the person.getField call.

Tips and tricks

This section shows a few of the useful tricks that gadgets can use to interact with people data on a GFC site.

Detecting when a user is not logged in

You can detect when a user is not logged in as follows:

// load the data using open social 
function loadData() {
  var req = opensocial.newDataRequest();
  req.add(req.newFetchPersonRequest('VIEWER'), 'viewer');
  req.send(onLoadCallback);
}


// called after data is loaded
 function onLoadCallback(data) {         
  if(data.get('viewer').getData()) {
    var viewer = data.get('viewer').getData();
    var name = viewer.getDisplayName();
    alert('Viewer is ' + name);
  } else {
    alert('Viewer is anonymous');
  }
}

Accessing site admins programmatically

Accessing the site's owner programmatically can present a challenge in Friend Connect. This is because in Friend Connect, OWNER maps to the site's profile information, not to the user who created the site.

Gadgets can access the site's admins using the 'ADMINS' group spec. For example:

// Will return the list of admins:
opensocial.DataRequest.newFetchPeopleRequest(
new opensocial.IdSpec({'userId' : 'OWNER', 'groupId' : 'ADMINS'}))

Activities

The OpenSocial API lets you share activities with your friends through an activity stream. An activity stream is a feed in which each entry represents an action performed by the user. An activity could be anything from modifying an application's state to writing an online review for a movie.

You can see the OpenSocial Developers Guide for an example on how to use the activities API.

Friend Connect provides an activities gadget that webmasters can add to their sites. This gadget displays the activities of the site's users. To add the activities gadget, go to Social gadgets > Activities gadget, and follow the instructions on that page to add the gadget.

A Friend Connect site's members can specify whether they want their activities posted to to other Friend Connect-enabled sites, and linked in social networks. To do this, members click the Settings link to display the profile editor. They then click the checkbox for "Publish my activities to other sites I have joined."

Activities API summary

This table summarizes the data that is returned when you use the OpenSocial API to fetch activities in GFC:

Persistence (app data)

OpenSocial defines a data store that applications can use to read and write per-user and per-application data, otherwise known as "app data." GFC supports this feature. To learn more about how to use the OpenSocial persistence API, see the OpenSocial Developer's Guide, and the article The Persistence API. The Friend Connect per-user limit for stored data is 10K.

If you use the inline Friend Connect library, as described in In-page Integration of GFC JS API, app data is accessible across the whole site, not just in a particular gadget.