If anyone is heading to the OpenSocial Birthday party at MySpace next week, I'll be there to give a presentation on the OpenSocial Dev App and to talk to developers about getting their apps running on multiple containers. See you there!
In October, I was fortunate enough to be able to travel to Shanghai and Beijing for Google's DevFest developer events in those cities.
Presenting OpenSocial to developers who hadn't had as much exposure to the technology was a refreshing challenge. It made me look at our existing slide decks a bit more critically (especially since the slides were going to be translated) and I wound up creating a lot of content to explain the basic OpenSocial concepts.
If you're a developer interested in OpenSocial but can't seem to find an overview of the entire technology stack (as of October 2008, at least), check out these slides - hopefully they'll give you some insight:
Presenting OpenSocial to developers who hadn't had as much exposure to the technology was a refreshing challenge. It made me look at our existing slide decks a bit more critically (especially since the slides were going to be translated) and I wound up creating a lot of content to explain the basic OpenSocial concepts.
If you're a developer interested in OpenSocial but can't seem to find an overview of the entire technology stack (as of October 2008, at least), check out these slides - hopefully they'll give you some insight:
Here they are translated into Chinese. My goal is to get some of the new images and diagrams into the official documentation soon.
I had to write a quick sample today to send a private message to the OWNER on Friendster. The following sends a message to your Friendster message inbox:
Also note that this is for OpenSocial 0.7. If you're migrating this code to another container on 0.8, you'll need to change the IdSpec stuff (as I've covered before).
function sendNotification() {
var params = {};
params[opensocial.Message.Field.TITLE] =
"Title of the notification goes here";
params[opensocial.Message.Field.TYPE] =
opensocial.Message.Type.PRIVATE_MESSAGE;
var body="Text of the notification goes here";
var message = opensocial.newMessage(body, params);
var recipient = opensocial.DataRequest.PersonId.OWNER;
opensocial.requestSendMessage(recipient, message,
onSendNotification);
};
function onSendNotification(resp) {
if (!resp.hadError() && resp.getData().status == "sent") {
alert("The message was sent to the OWNER");
} else {
alert("There was a problem: " + resp.getErrorMessage());
}
};
sendNotification();
Note the message type is set to PRIVATE_MESSAGE. Friendster also supports type NOTIFICATION, but I haven't quite figured out where that shows up, and I get a "Insufficient permissions for action 'publicMessage'" error message when trying PUBLIC_MESSAGE.Also note that this is for OpenSocial 0.7. If you're migrating this code to another container on 0.8, you'll need to change the IdSpec stuff (as I've covered before).
I needed to write the following sample of code to test fetching people by ID number. This is an interesting sample because it demonstrates handling an error condition - namely, the "unauthorized" response that you should get when you try to access an account that you don't have permission to request. On orkut, this means people who don't have your app installed, even if they're your friends.
The following runs in DAfOS:
On orkut, if a user doesn't have DAfOS installed, you'll get an "unauthorized" error:
In your applications, make sure to handle cases like this, since you won't always be able to guarantee that all containers will have the same policies around which user accounts you may directly access.
The following runs in DAfOS:
function onPersonGot(result) {
var response = result.get("person");
if (response.hadError()) {
output("There was a problem fetching this user: " +
response.getErrorCode());
} else {
output("Fetched " +
result.get("person").getData().getDisplayName());
}
gadgets.window.adjustHeight();
};
function closeGetPerson(id) {
return function() {
var params = {};
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(id, params), "person");
req.send(onPersonGot);
};
};
function closePrintFriend(list) {
return function(friend) {
var item = document.createElement("li");
var link = document.createElement("a");
var text = document.createTextNode(friend.getDisplayName());
list.appendChild(item);
item.appendChild(link);
item.appendChild(document.createTextNode(" [" +
friend.getId() + "]"));
link.appendChild(text);
link.onclick = closeGetPerson(friend.getId());
link.href = "javascript:void(0);";
};
};
function gotFriends(data) {
var friends = data.get("of").getData();
var list = document.createElement("ul");
var main = document.getElementById("dom_handle")
main.innerHTML = "";
main.appendChild(list);
friends.each(closePrintFriend(list));
gadgets.window.adjustHeight();
};
function getFriends() {
var params = {};
params[opensocial.DataRequest.PeopleRequestFields.MAX] = 1000;
var req = opensocial.newDataRequest();
req.add(req.newFetchPeopleRequest(
opensocial.DataRequest.Group.OWNER_FRIENDS, params), "of");
req.send(gotFriends);
};
getFriends();Note that the example lists the friends of the owner as links. Clicking on each name will attempt to retrieve that user by ID number. On orkut, if a user doesn't have DAfOS installed, you'll get an "unauthorized" error:
In your applications, make sure to handle cases like this, since you won't always be able to guarantee that all containers will have the same policies around which user accounts you may directly access.
Lately I've been updating some documentation to use version of 0.8 of the OpenSocial specification. If you've developed on the 0.7 version of the API, you'll probably be happy to see that not a lot of breaking changes have been introduced in the new version, with one major exception: the
In the past, when you wanted to specify a single person or a group of people, you would use one of the following:
Single person specifiers (OpenSocial 0.7):
To convert your app, update all functions that take a single person identifier to one of the following:
Seleting a group of people requires a bit more of a code change, though. Where you might write something like this in OpenSocial 0.7:
You can use these for the following functions:
The
IdSpec object.In the past, when you wanted to specify a single person or a group of people, you would use one of the following:
Single person specifiers (OpenSocial 0.7):
opensocial.DataRequest.Person.OWNERopensocial.DataRequest.Person.VIEWER- A string representing the OpenSocial ID of a person.
opensocial.DataRequest.Group.OWNER_FRIENDSopensocial.DataRequest.Group.VIEWER_FRIENDS- An array of strings, each representing the OpenSocial ID of a person.
IdSpec object was introduced. IdSpec allows you to be much more expressive when specifying groups of people (including friends-of-friends, covered later) but introduces some additional complexity. Single person specifiers still use the OWNER and VIEWER objects, but these have been moved to the opensocial.IdSpec.PersonId namespace.To convert your app, update all functions that take a single person identifier to one of the following:
opensocial.IdSpec.PersonId.OWNERopensocial.IdSpec.PersonId.VIEWER- A string representing the OpenSocial ID of a person.
opensocial.DataRequest.newFetchPersonRequestopensocial.DataRequest.newUpdatePersonAppDataRequestopensocial.DataRequest.newRemovePersonAppDataRequest
opensocial.IdSpec.PersonId.VIEWER, so this is a pretty straightforward change.Seleting a group of people requires a bit more of a code change, though. Where you might write something like this in OpenSocial 0.7:
var params = {};
var req = opensocial.newDataRequest();
...
req.add(req.newFetchPeopleRequest(
opensocial.DataRequest.Group.OWNER_FRIENDS, params);
req.send();
Now you need to create an IdSpec instead:var params = {};
var idspec = opensocial.newIdSpec({
"userId" : "OWNER",
"groupId" : "FRIENDS"
});
...
req.add(req.newFetchPeopleRequest(
idspec, params);
req.send();
You can actually create IdSpec equivalents to all of the old person/people identifiers:| Identifier | IdSpec code |
|---|---|
| OWNER | var idspec = opensocial.newIdSpec({
"userId" : "OWNER", "groupId" : "SELF"
}); |
| VIEWER | var idspec = opensocial.newIdSpec({
"userId" : "VIEWER", "groupId" : "SELF"
}); |
| OWNER_FRIENDS | var idspec = opensocial.newIdSpec({
"userId" : "OWNER", "groupId" : "FRIENDS"
}); |
| VIEWER_FRIENDS | var idspec = opensocial.newIdSpec({
"userId" : "VIEWER", "groupId" : "FRIENDS"
}); |
You can use these for the following functions:
opensocial.DataRequest.newFetchActivitiesRequestopensocial.DataRequest.newFetchPeopleRequestopensocial.DataRequest.newFetchPersonAppDataRequest
The
IdSpec object exposes some additional functionality like NETWORK_DISTANCE that I'll cover later, but for the time being, this should be enough information to get you to start porting your existing code to 0.8.
When teaching myself the OpenSocial API, I found the standard "edit XML file" -> "upload to server" -> "reload gadget" process to be too slow for my liking, especially when working with code that was almost completely client-side JavaScript.
A strength (or weakness, depending on who you ask) of JavaScript is that you can compile and execute JavaScript source code at runtime using the
CodeRunner wound up working quite well, but I wanted more space for storage, and I wanted to offer some capabilities that only a server-side solution would be able to satisfy. Because Google released their App Engine product around this time, I decided to turn CodeRunner into an App Engine application, called the Developer Application for OpenSocial, or DAfOS for short.
You can get links to use DAfOS on different containers by visiting dafos.appspot.com. Eventually that site will be filled out with more documentation.
Here's a shot of DAfOS in action (it looks a lot like CodeRunner at the moment):
Samples are entered into the yellow input box. You can run a sample by clicking the "Execute" button in the top right hand corner of the gadget. The JavaScript entered in the box will execute as if it were part of the gadget itself. That means that you can execute social data queries, post Activity Stream entries, send messages, and anything else that the OpenSocial API allows.
DAfOS also defines a method called
Since DAfOS runs on App Engine, the samples are no longer stored in AppData. When you save a sample, it is actually hosted at dafos.appspot.com, and accessible by clicking on the name of the sample after you save it. This URL can be sent out to help supply code for reporting issues or helping other developers with problems.
Because I use DAfOS to write most of my samples, you'll be able to copy and paste most of the code snippets from this blog directly into DAfOS and watch them run.
You can still use CodeRunner by installing this gadget XML spec to a container, but there will not be any future development on it, meaning it will likely stop functioning once containers switch to OpenSocial 0.8
A strength (or weakness, depending on who you ask) of JavaScript is that you can compile and execute JavaScript source code at runtime using the
eval function. It made sense to create a simple gadget to help developers prototype simple OpenSocial calls, so I released CodeRunner, an OpenSocial application that let developers execute JavaScript snippets inside of a live OpenSocial container. These snippets could also be saved to AppData, which was convenient as long as you didn't run out of quota space (currently 10k on orkut and 1k on MySpace).CodeRunner wound up working quite well, but I wanted more space for storage, and I wanted to offer some capabilities that only a server-side solution would be able to satisfy. Because Google released their App Engine product around this time, I decided to turn CodeRunner into an App Engine application, called the Developer Application for OpenSocial, or DAfOS for short.
You can get links to use DAfOS on different containers by visiting dafos.appspot.com. Eventually that site will be filled out with more documentation.
Here's a shot of DAfOS in action (it looks a lot like CodeRunner at the moment):
Samples are entered into the yellow input box. You can run a sample by clicking the "Execute" button in the top right hand corner of the gadget. The JavaScript entered in the box will execute as if it were part of the gadget itself. That means that you can execute social data queries, post Activity Stream entries, send messages, and anything else that the OpenSocial API allows.DAfOS also defines a method called
output. Everything you pass to this method will be printed out in an output box at the bottom of the application. If you have Firebug installed (you really should!), then you'll see this output in Firebug's console, as well.Since DAfOS runs on App Engine, the samples are no longer stored in AppData. When you save a sample, it is actually hosted at dafos.appspot.com, and accessible by clicking on the name of the sample after you save it. This URL can be sent out to help supply code for reporting issues or helping other developers with problems.
Because I use DAfOS to write most of my samples, you'll be able to copy and paste most of the code snippets from this blog directly into DAfOS and watch them run.
You can still use CodeRunner by installing this gadget XML spec to a container, but there will not be any future development on it, meaning it will likely stop functioning once containers switch to OpenSocial 0.8
