Open Social Summit Korea

1

OpenSocialKorea - November 2008

Arne Roomann-KurrikDeveloper Relations

Yung Choi Software Engineer

2

GadgetsNot widgets, not sprockets, not gidgets, not wadgets

Gadgets

3

A gadget spec:• Is an XML file.• Defines metadata about an OpenSocial app.• Is highly cacheable and does not need a high performance server.

Gadgets use existing web standards• XML to define metadata.• HTML for markup.• JavaScript for interactivity.• CSS for presentation.

Gadgets

4

A gadget server:• Takes the gadget spec as input.• Performs optimizations on the gadget spec.• Outputs HTML, JavaScript, and CSS as one document.

Gadgets

5

A container:• Displays the social network’s user interface.• Opens an IFrame to the rendered gadget.

Gadgets

6

Example gadget XML spec:• Uses HTML to print “Hello World”.• Colors the text red with CSS.• Dynamically adjusts the height of the gadget with JavaScript.

<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Hello World!"> <Require feature="dynamic-height" /> </ModulePrefs> <Content type="html"> <![CDATA[ <h1>Hello World</h1>

<style type="text/css"> h1 { color: #dd0000; }</style><script type="text/javascript"> gadgets.window.adjustHeight();</script>

]]> </Content></Module>

Gadgets

7

Content sections:• Define the current view:

<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Hello World!"> <Require feature="dynamic-height" /> </ModulePrefs> <Content type="html" view="canvas"> <![CDATA[ <h1>Hello World</h1>

<style type="text/css"> h1 { color: #dd0000; }</style><script type="text/javascript"> gadgets.window.adjustHeight();</script>

]]> </Content></Module>

Gadgets

8

What are views?• Gadgets can render in different locations on a container.• Rendering area changes from small to large.• Certain pages might be public, some are private.• Containers may have different policies depending on the page,

especially when the gadget displays ads.• Views provide a way for gadgets to provide different functionality

depending on where it is rendered.

Gadgets

9

iGoogle "home" view:• On iGoogle, the "home" view is a small,

private page that does not allow ads.

Gadgets

10

iGoogle "canvas" view:• Large private view, allows ads.

Gadgets

11

Working with views in the gadget XML:• <Content> sections are repeated for each view.• Add a view="view name" attribute to each section.• Content sections may support multiple views, for example

view="home,canvas"<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Hello World!"> <Require feature="dynamic-height" /> </ModulePrefs> <Content type="html" view="home"> <![CDATA[ ... ]]> </Content> <Content type="html" view="canvas"> <![CDATA[ ... ]]> </Content></Module>

Gadgets

12

Add extra features to your gadget:• dynamic-height - Change the size of your gadget in the container.• views - Navigate between different surfaces of the container.• skins - Make your gadget change its styles to match the container. • Containers may offer custom features...

<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Hello World!"> <Require feature="dynamic-height" /> </ModulePrefs> <Content type="html"> <![CDATA[ ... ]]> </Content></Module>

Gadgets

13

<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Hello Social!"> <Require feature="opensocial-0.8" /> </ModulePrefs> <Content type="html"> <![CDATA[ ... ]]> </Content></Module>

The OpenSocial JavaScript API is a gadget feature, too!

Gadgets

14

Requesting the gadget XML spec:1. The client requests an app to be rendered.

Gadgets

15

Requesting the gadget XML spec:1. The client requests an app to be rendered.2. The container fetches the gadget XML spec from its host.

Gadgets

16

Requesting the gadget XML spec:1. The client requests an app to be rendered.2. The container fetches the gadget XML spec from its host. 3. The container renders the gadget into HTML, which is displayed

to the client.

17

GadgetsScaling is hard:

• Easy to start and get some users.

18


• Being popular on one social network can push your server to the limit...

19


• ...being popular on many networks can be disastrous.

Caching can help!

Gadgets

20

Requesting a cached gadget XML spec:1.The client requests an app to be rendered. The container already

has a copy of the spec stored in its cache.

Gadgets

21


has a copy of the spec stored in its cache.2.The container renders the gadget into HTML, which is displayed

to the client.

Gadgets

22


has a copy of the spec stored in its cache.2.The container renders the gadget into HTML, which is displayed

to the client.Your server does not even get a request!

Gadgets

23

Optimizations?• Cache, cache, cache.• Rewrite links to use content proxies.• Rewrite relative links to full paths.• Concatenate JS and CSS.• Return only content for the current view.

24

The JavaScript APIs

Gadgets JavaScript

25

gadgets.* utility functions:• gadgets.io.makeRequest()

Make cross-domain AJAX calls to remote servers.

Gadgets JavaScript

26


Make cross-domain AJAX calls to remote servers.• gadgets.json.parse() and gadgets.json.stringify()

Native JSON support.

Gadgets JavaScript

27



Native JSON support.• gadgets.util.escapeString()

Make text safe for display via innerHTML.

Gadgets JavaScript

28



Native JSON support.• gadgets.util.escapeString()

Make text safe for display via innerHTML.• gadgets.util.registerOnLoadHandler()

Execute code when the page is finished loading.

Gadgets JavaScript

29

gadgets.io.makeRequest():• Make cross-domain AJAX calls to remote servers.

Remote content:• Work with different servers.• AJAX is not cross-domain!• JSONP is only one-way.• Data needs to be cached for millions

of users.

Gadgets JavaScript

30

Requesting remote content:1.The rendered app calls gadgets.io.makeRequest() to fetch

remote content.

Gadgets JavaScript

31


remote content. 2.The container requests content from the specified URL.

Gadgets JavaScript

32


remote content. 2.The container requests content from the specified URL.3.The container returns the response to the application, which renders

the data.

The OpenSocial JavaScript API

33

Representing users:• Client-side, users must work with the VIEWER and the OWNER.


34

Multiple personalities:• When you visit your own profile, you are both the VIEWER and the

OWNER.


35

Representing users:• Sometimes, containers allow anonymous browsing.

??


36

OpenSocial requests:• An OpenSocial DataRequest is created.• Requests are added to the DataRequest.• The DataRequest is sent to the server asynchronously.• When the request finishes, the supplied callback will be called.

function request() { var req = opensocial.newDataRequest(); req.add(...); ... req.send(response);};

function response(data) { ... };

gadgets.util.registerOnLoadHandler(request);


37

OpenSocial requests:• An OpenSocial DataRequest is created.• Requests are added to the DataRequest.• The DataRequest is sent to the server asynchronously.• When the request finishes, the supplied callback will be called.

function request() { var req = opensocial.newDataRequest(); req.add(req.newFetchPersonRequest("OWNER"), "get_owner"); req.add(req.newFetchPersonRequest("VIEWER"), "get_viewer"); req.add(req.newFetchActivitiesRequest("VIEWER"), "vactivities"); req.add(req.newFetchPersonAppDataRequest("OWNER", "*"), "odata"); ... req.send(response);};

function response(data) { ... };

gadgets.util.registerOnLoadHandler(request);


38

OpenSocial responses:• Responses are bundled according to the keys specified in the request.• Check for an error at the global response level.• Check for an error at the specific response level.• Use getData() to retrieve the actual information in a request.

function response(data) { if (data.hadError()) { if (data.get("get_owner").hadError()) { ... } if (data.get("get_viewer").hadError()) { ... } ... } var owner = data.get("get_owner").getData(); var viewer = data.get("get_viewer").getData();};


39

Working with people:

• opensocial.Person - JavaScript representation of a user.


40

Request one person:req.add(req.newFetchPersonRequest(idspec, opt_params), "key");

• idspec can be either “VIEWER”, “OWNER” or an ID number.• opt_params contains extra request parameters, such as which profile

fields to fetch.

newFetchPersonRequest responses:

var owner = data.get("key").getData();alert(owner.getDisplayName());

• Data contains a single opensocial.Person object.

• Person objects can contain lots of information, such as addresses, companies, phone numbers, favorite movies, and thumbnail urls.


41

Methods available on an OpenSocial Person:

• getDisplayName()Gets a text display name for this person; guaranteed to return a useful string.

• getField(key, opt_params)Gets data for this person that is associated with the specified key.

• getId()Gets an ID that can be permanently associated with this person.

• isOwner()Returns true if this person object represents the owner of the current page.

• isViewer()Returns true if this person object represents the currently logged in user.

• ABOUT_ME• ACTIVITIES• ADDRESSES• AGE• BODY_TYPE• BOOKS• CARS• CHILDREN• CURRENT_LOCATION• DATE_OF_BIRTH• DRINKER• EMAILS• ETHNICITY• FASHION• FOOD• GENDER• HAPPIEST_WHEN• HAS_APP• HEROES• HUMOR• ID• INTERESTS

• JOB_INTERESTS• JOBS• LANGUAGES_SPOKEN• LIVING_ARRANGEMENT• LOOKING_FOR• MOVIES• MUSIC• NAME• NETWORK_PRESENCE• NICKNAME• PETS• PHONE_NUMBERS• POLITICAL_VIEWS• PROFILE_SONG• PROFILE_URL• PROFILE_VIDEO• QUOTES• RELATIONSHIP_STATUS• RELIGION• ROMANCE• SCARED_OF• SCHOOLS


42

An OpenSocial Person's fields:• SEXUAL_ORIENTATION• SMOKER• SPORTS• STATUS• TAGS• THUMBNAIL_URL• TIME_ZONE• TURN_OFFS• TURN_ONS• TV_SHOWS• URLS


43

Working with people:

• A Collection represents many opensocial.Person objects.


45

Request many people:var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS"});req.add(req.newFetchPeopleRequest(idspec, opt_params), "key");

• Pass an idspec object to the newFetchPeopleRequest function.• opt_params contains extra request parameters, such as which profile

fields to fetch, and how to order or filter the returned people.

newFetchPersonRequest responses:var owner_friends = data.get("key").getData();owner_friends.each(function (person) { alert(person.getDisplayName());});

• Data contains a Collection of opensocial.Person objects. Iterate over these by using the each() method.


46

Working with data:

• Persistent data gives apps key, value storage directly on the container. • String only, but conversion to JSON allows for storage of complex

objects.• Storage per app per user - scales well with growth.• Ideal for settings, customizations.


47

Set persistent data:req.add(req.newUpdatePersonAppDataRequest(idspec, key, value));

• idspec can only be “VIEWER”.• key is the name under which this data will be stored.• value is a string representing the data to store.


48

Fetch persistent data:var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "SELF"});req.add(req.newFetchPersonAppDataRequest(idspec, keys), "key");req.add(req.newFetchPersonRequest("OWNER"), "ownerkey");

• idspec is an object that can represent groups of people, the same as newFetchPeopleRequest.

• keys is a list of persistent data keys to retrieve the data for.• The owner is requested because the data returned is indexed by user ID

and we want the owner’s data.

newFetchPersonAppDataRequest responses:

var app_data = data.get("key").getData();var value = app_data[owner.getId()][key];


49

Fetch persistent data:

{ "1234567890" : { "key1" : "value1" }, "2345678901" : { "key1" : "value2" }}

• Data is returned as an object indexed by ID number, then as an object indexed by key name, even if there is only data returned for one user!

{ "1234567890" : { "key1" : "value1" } }

• Multiple people:

{ "1234567890" : { "key1" : "value1", "key2" : "value2" }}

• One person, multiple keys:


50

Working with activities:

• API to post information about what users are doing with your app.• Many containers have support for images and some HTML.• Channel to grow your application.

orkut MySpace hi5


51

Post an activity:

function postActivity(text) { var params = {}; params[opensocial.Activity.Field.TITLE] = text; var activity = opensocial.newActivity(params); opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, callback);};

• Assign the activity text to the TITLE field.• Call opensocial.newActivity() to create a new Activity instance.• Call opensocial.requestCreateActivity() to post the activity to the

container.

Building apps across containers

52

53

Challenges

Cross container development is still tricky:• Containers may not follow the standard.• Containers may follow the standard but have different policies.• Follow best practices:

http://tinyurl.com/4nuzll

http://www.youtube.com/watch?v=NGDjQGjK79A

http://www.youtube.com/watch?v=NGDjQGjK79A

54

Robustness - Be Explicit

• Spot the bug in this code! Let's request the owner:

• And access their profile URL:

function request() { var req = opensocial.newDataRequest(); req.add(req.newFetchPersonRequest( "VIEWER"), "req"); req.send(response);};

function response(data) { var url = data.get("req").getData().getField( opensocial.Person.Field.PROFILE_URL)); ...}

55


• On hi5, url is:

• On orkut, url is:

http://www.hi5.com/friend/profile/ displayProfile.do?userid=XXXXXXXXXX

• The OpenSocial specification only states the following about fields available on Person objects:

"The server will always include ID, NAME, and THUMBNAIL_URL."*

null

*http://rurl.org/qoo

http://www.hi5.com/friend/profile/


56


• Introducing

• Assign an array of properties you want to access to this optional parameter

opensocial.DataRequest .PeopleRequestFields.PROFILE_DETAILS

var params = {}; params[opensocial.DataRequest .PeopleRequestFields.PROFILE_DETAILS] = [ opensocial.Person.Field.ABOUT_ME, opensocial.Person.Field.ADDRESSES, opensocial.Person.Field.AGE ];

57


• Fixing the request: From this...

function request() { var req = opensocial.newDataRequest();

req.add(req.newFetchPersonRequest( "VIEWER"), "req"); req.send(response);};

58


• ...to this:

function request() { var req = opensocial.newDataRequest(); var params = {}; params[opensocial.DataRequest.PeopleRequestFields .PROFILE_DETAILS] = [ opensocial.Person.Field.PROFILE_URL ]; req.add(req.newFetchPersonRequest( "VIEWER", params), "req"); req.send(response);};

59


• On hi5, url is:

• On orkut, url is:

http://www.hi5.com/friend/profile/ displayProfile.do?userid=XXXXXXXXXX

http://www.orkut.com/ Profile.aspx?uid=YYYYYYYYY



http://www.orkut.com

http://www.orkut.com

60

Robustness - Check For Errors

61


• Why is the following code brittle? Request a user by ID:

function request() { var req = opensocial.newDataRequest(); req.add(req.newFetchPersonRequest( "14088281537290874435"), "req"); req.send(response);};

function response(data) { var name = data.get("req").getData() .getDisplayName(); ...};

• And get the display name:

62


• If the passed ID is invalid for any reason, the previous code throws a JavaScript error:

• Check for problems! DataRequest.send callbacks get DataResponse arguments with hadError methods:

function response(data) { if (!data.hadError()) { var name = data.get("req").getData() .getDisplayName(); ... }};

data.get("req").getData() has no properties

63


• Inside of these DataResponse objects are nested ResponseItem objects, which also have hadError methods:

• You can check each response individually to see where the point of failure is.

function response(data) { if (!data.hadError()) { ... } else { if (data.get("req").hadError()) { ... } }};

64


• Handling errors gracefully:

• getErrorMessage() provides a human-readable error message, but varies by container.

function response(data) { if (!data.hadError()) { ... } else if (data.get("req").hadError()) { alert(data.get("req").getErrorMessage()); } else { alert("An unknown error occurred"); }};

• This may not be ideal for display to an end user.

• getErrorCode() provides an enum indicating the type of error

65


data.get("req").getErrorCode()

• Check for the type of error and fall back where possible.

66


• opensocial.ResponseItem.Error.BAD_REQUEST• The request was invalid

• opensocial.ResponseItem.Error.FORBIDDEN• The gadget can never have access to this data

• opensocial.ResponseItem.Error.INTERNAL_ERROR• Server problem

• opensocial.ResponseItem.Error.LIMIT_EXCEEDED• Over quota

• opensocial.ResponseItem.Error.NOT_IMPLEMENTED• No container support

function response(data) { if (!data.hadError()) { ... } else if (data.get("req").hadError()) { switch (data.get("req").getErrorCode()) { case opensocial.ResponseItem.Error.BAD_REQUEST: ... break; case opensocial.ResponseItem.Error.INTERNAL_ERROR: ... break; } } else { ...

67


• Check for error types at runtime:

• Not all errors need to be fatal!

• An appropriate response to UNAUTHORIZED would be to call opensocial.requestPermission()

68


switch (data.get("req").getErrorCode()) { case opensocial.ResponseItem.Error.UNAUTHORIZED: opensocial.requestPermission( [ "VIEWER" ], "Share a gift with your friend", callback); break;}

• While you can react to an UNAUTHORIZED error, there’s also the opensocial.hasPermission()method, which you can check before making the request:

69

Robustness - Off Track For A Second

var has_permission = opensocial.hasPermission( opensocial.Permission.VIEWER);

• has_permission will be boolean true or false

• Let’s go back to that requestPermission call:

70


opensocial.requestPermission( [ opensocial.Permission.VIEWER ], “Share a gift with your friend”, callback);

• callback will be called when this request completes and get a ResponseItem as a parameter.

• What happens if the container doesn’t support requestPermission?

• Unimplemented methods will get an NOT_IMPLEMENTED error code:

71


function callback(data) { if (!data.hadError()) { ... } else { switch(data.getErrorCode()) { case opensocial.ResponseItem.Error.NOT_IMPLEMENTED: ... break; } }};

• A container may not implement any method and still remain spec compliant as long as they return the NOT_IMPLEMENTED error code.

• This applies to any method where the callback receives a DataResponse or ResponseItem, including:

• requestCreateActivity• requestPermission• requestSendMessage• requestShareApp• all new*Request calls

• So be sure to check for such cases!

72


73

Robustness - Check For Support

74


• Containers have different purposes. Not every field may be available.

opensocial.Person.Field.LOOKING_FOR

MyOpenSpace.Person.Field.DESIRE_TO_MEET

hi5.PersonField.PRESENCE

• hi5: not supported• MySpace: not supported• orkut: supported

• hi5: not supported• MySpace: supported• orkut: not supported

• hi5: supported• MySpace: not supported• orkut: not supported

if (MySpace) { ...} else if (hi5) { ...} else if (orkut) { ...} else { ...}

75


• Your impulse may be to write code like this:

• This is brittle! How do you scale to new containers automatically?

var supports_lookingfor = opensocial.getEnvironment().supportsField( opensocial.Environment.ObjectType.PERSON, opensocial.Person.Field.LOOKING_FOR);

76


• Sounds like a job for capabilities querying:

• Now supports_lookingfor has the following value:• on hi5: false• on MySpace: false• on orkut: true

• Goal: Build apps that programatically utilize extra functionality based on such booleans

• Why is this approach brittle?

var supports_desiretomeet = opensocial.getEnvironment().supportsField( opensocial.Environment.ObjectType.PERSON, MyOpenSpace.Person.Field.DESIRE_TO_MEET);

77


• Try a container-specific profile field:

• Now supports_desiretomeet has the following value:

• Oops!

• on hi5: JavaScript error• on MySpace: true• on orkut: JavaScript error

var supports_desiretomeet = false;if (MyOpenSpace) { var supports_desiretomeet = opensocial.getEnvironment().supportsField( opensocial.Environment.ObjectType.PERSON, MyOpenSpace.Person.Field.DESIRE_TO_MEET);}

78


• What about:

• Now supports_desiretomeet has the following value:• on hi5: false• on MySpace: true• on orkut: false

• This approach defeats the purpose of querying!

var supports_desiretomeet = false;if (MyOpenSpace) { var supports_desiretomeet = opensocial.getEnvironment().supportsField( opensocial.Environment.ObjectType.PERSON, MyOpenSpace.Person.Field.DESIRE_TO_MEET);}

79


• You should be able to see that:

• Is really the same as:

var supports_desiretomeet = (MyOpenSpace) ? true : false;

if (MyOpenSpace) { ...} else if (hi5) { ...} else { ...}

80


• Remember, we don't want to write code like this:

• Apps should query by capability, not container name

var env = opensocial.getEnvironment();var supports_presence = env.supportsField( opensocial.Environment.ObjectType.PERSON, hi5.PersonField.PRESENCE);

var supports_desiretomeet = env.supportsField( opensocial.Environment.ObjectType.PERSON, MyOpenSpace.Person.Field.DESIRE_TO_MEET);

var supports_lookingfor = env.supportsField( opensocial.Environment.ObjectType.PERSON, opensocial.Person.Field.LOOKING_FOR);

81


• Don't do this:

var env = opensocial.getEnvironment();var supports_presence = env.supportsField( opensocial.Environment.ObjectType.PERSON, "presence");

var supports_desiretomeet = env.supportsField( opensocial.Environment.ObjectType.PERSON, "DESIRE_TO_MEET");

var supports_lookingfor = env.supportsField( opensocial.Environment.ObjectType.PERSON, "lookingFor");

82


• A workaround is to ignore the enums and go for string representations:

83


Wait a sec, isn’t this a worst practice?

84


• Thankfully, the specification addresses this issue:

“Extra person, activity or other object fields should be defined in an enum under the container's namespace, and the environment should allow applications to discover these fields.”

85


• Thankfully, the specification addresses this issue:

opensocial.getEnvironment().supportsField( "person", "orkut.specialPersonField")

opensocial.getEnvironment().supportsField( opensocial.Environment.ObjectType.PERSON, orkut.PersonField.SPECIAL_FIELD)

*http://rurl.org/qr4

“For example, if the field orkut.PersonField.SPECIAL_FIELD is defined as 'orkut.specialPersonField', then

should both return true.”*

and

86


• We now have runtime access to capabilities across all containers:

hi5 MySpace orkut

supports_presence

supports_desiretomeet

supports_lookingfor

TRUE FALSE FALSE

FALSE TRUE FALSE

FALSE FALSE TRUE

• Drawback: Now we have to be sensitive to the underlying string value for Profile field enums

if (MyOpenSpace) { ...} else if (hi5) { ...} else { ...}

87


• Now, instead of: • Use:

if (supports_presence) { ...} if (supports_desiretomeet) { ...} if (supports_lookingfor) { ...}

88

Resources / Questions?

Resources

• OpenSocial Tutorial: http://rurl.org/ss3

• OpenSocial Spec, Foundation, Reference: http://opensocial.org

• Caja: http://code.google.com/p/google-caja/

• Shindig: http://incubator.apache.org/shindig/

• OpenSocial Across Containers video: http://tinyurl.com/4nuzll

• OpenSocial Templates: http://ostemplates-demo.appspot.com/

• OpenSocial Dev App: http://osda.appspot.com

• Partuza: http://partuza.nl

• OpenSocial Specification Proposals: http://groups.google.com/group/opensocial-and-gadgets-spec/topics

89

http://rurl.org/ss3

http://rurl.org/ss3

http://opensocial.org

http://opensocial.org

http://code.google.com/p/google-caja/

http://code.google.com/p/google-caja/

http://incubator.apache.org/shindig/

http://incubator.apache.org/shindig/



http://ostemplates-demo.appspot.com

http://ostemplates-demo.appspot.com

http://osda.appspot.com

http://osda.appspot.com

http://partuza.nl

http://partuza.nl

http://groups.google.com/group/opensocial-and-gadgets-spec/topics

http://groups.google.com/group/opensocial-and-gadgets-spec/topics

Hacking!

90

Beginner (http://is.gd/7W05):• Write a gadget to display "Hello World" in your favorite container.• Display a list of your friends.• Display the OWNER's favorite movies.• Post an activity update.• Write an app that uses AppData to store preferences (http://is.gd/7W0g)

Intermediate:• Make an app that works on two containers using the same XML.• Use makeRequest to list the OWNER's favorite movies and

information from a web API such as amazon.com or imdb.com• Write a gift giving app using AppData: (http://is.gd/7W0v)

Advanced:• Write a server-side app that uses the Java (http://is.gd/7W0E) or

PHP (http://is.gd/7W0K) client libraries.

http://code.google.com/apis/opensocial/docs/0.8/devguide.html

http://code.google.com/apis/opensocial/docs/0.8/devguide.html

http://is.gd/7W0g

http://is.gd/7W0g

http://is.gd/7W0v

http://is.gd/7W0v

http://code.google.com/p/opensocial-java-client/

http://code.google.com/p/opensocial-java-client/

http://code.google.com/p/opensocial-php-client/

http://code.google.com/p/opensocial-php-client/

Open Social Summit Korea

Technology

Transcript of Open Social Summit Korea