Official ORKUT DEVELOPER GUIDELINES Released

ROLES

There are two actors in Opensocial. The OWNER refers to the person that has installed the app on their profile. The VIEWER refers to the person visiting the profile.

• Viewers can have three different relationships with the owner: either they are FRIENDS, they are FOF (friends-of-friends) or they are UNRELATED (referred to as everyone in Orkut).
• The viewer has two relationships with the app - either they have installed the app or they haven't.

Users will likely be confused with 6 viewer states as they navigate across the network. So, we recommend just 2 states for viewers:

• Friends with App (FA)
• Guest - everyone else

PROFILEBOX

MUST DO

1 - A user's profile is their face to the orkut community. Therefore, the owner should be able to easily see how their profile will appear to others. This requires that:

• the content being shown on ProfileBox to OWNER, FA and GUEST viewers must be the same. Examples of content: top friends, favorite movies, cities visited, etc
• it is permissible to have different actions for OWNER and FA viewer. for example, a FA viewer can leave a comment or an OWNER can rearrange songs in a playlist

What is NOT allowed:

• Message that says "you must install this app to see stuff". This violates the principle that OWNER, FA and GUEST viewers see the same content.
• Showing an action that the user cannot perform without installing an app. For example - "want to play me?" or "find out how lazy you are" that lead to the app install page. If the user cannot take an action without installing app, don't display the action.
• "add xyz to your profile" which are ads for the app. Orkut automatically places a link below each ProfileBox to "add this app to your profile". So, if the user wants to install the app, they already can.

Tip: Design for GUEST viewer first. Then, add actions for FA viewers - like allowing them to comment. Design for OWNER last - like letting them update their status, rearrange songs in a playlist, etc.

2 - Autoplay is NOT allowed in ProfileBox. Users do like it when their page plays music or video when their friends visit. But, there are two issues in the v1 of platform:

• media streaming prevents other apps on the page from loading
• multiple apps autoplay together creating a cacophonous experience

Until we sort out these issues, no autoplay is allowed on profile page.

SHOULD DO

The height for profileBox is 280 pixels by default and expandable to 500 pixels. The profileBox should fit within 500 pixels - to avoid appearance of vertical scrollbars.

CANVAS PAGE

MUST DO

Due to the limit of 3 Profile boxes on profile, the app's profileBox may not be visible on the user's profile at all. So, the app must not assume that the OWNER or VIEWER are navigating to the canvas from the profileBox. The canvas page may be the first view that the OWNER or VIEWER may have of the application. So, the FIRST VIEW presented on the canvas page must follow the same rules as ProfileBox. Additionally, apps are NOT allowed to:

• Redirect of any kind as they break the browser's back button
• Redirect GUEST viewers to App install page

MAY DO

Autoplay on the canvas page IS allowed. This is because the issue of traffic congestion between apps and multiple apps autoplaying at the same time don't apply on the canvas page.

SHOULD DO

1 - Apps are encouraged to support a GUEST mode that lets the user experience the app before they install it. for example:

• Games: Let the GUEST play a game (like Hangman) and show how their score ranks with the OWNER of the canvas page.
• Interaction: Let the GUEST create a photo-attack using the OWNER's photos
• Music, movies, books, travel: Let the GUEST create a collection of their favorite songs / movies / books / cities.

2 - The API doesn't allow for params to be passed from GUEST mode to INSTALL flow and back to the OWNER mode once the app has been installed. We will soon support this usecase in the API. In the meantime, you can accomplish this usecase by using a cookie.

GENERAL USER EXPERIENCE

MUST DO

• Don't show a blank screen as the app is loading. Show a "loading..." message. Tip: Use http://www.ajaxload.info/ to generate Ajax loader icon.
• Use error handling in your app. When an error occurs, generate a user-friendly message. Html alerts boxes are strongly discouraged as they're modal and interruptive.
• Call the adjustheight() method when the height changes. This will remove double-scrollbars.

SHOULD DO

• The app should try to fit the content so horizontal scrollbars don't appear in the app.

UPDATES

MUST DO

• Updates must reflect an action that the user took. For example, user adding an artist, sending a gift to someone else or writing a review for a movie.
• If there's an image, it must be about something that the user created, bookmarked or posted.
• Profile pictures of friends are allowed if the owner interacted with their friend - like adding someone to their top friends list, for example.
• Profile picture of activity owner are NOT allowed - as it does not add unique information to the update.
• Generic message that says "User is using app" are NOT allowed.
• Application logos are NOT allowed in the updates. The app already gets attribution in title and soon, we'll add the app's fav-icon as well.
• Ads to add the application or any links that point to the AppInfo page are NOT allowed.
• Fonts must be 12pt or smaller.
• Use of bold is not allowed.
• Information shown in title and body must be different and no information can repeat.

SHOULD DO

• Provide notification inside the app that an update was added.
• Summarize. It's much better to create a digest update rather than multiple updates. The app can pool updates and post on the canvas window.unload event.

Examples:

1. this update is basically an Ad for the app and so not allowed. the app should correct this by showing names and covers of books that the user is reading.
   
2. this update is good - it shows the song name and album cover. but, it also includes an ad to add the app to profile. the app should correct this by removing the ad.
   
3. this update repeats the user's name 3 times and mentions ReadingSocial 3 times. The app should correct this by only mentioning the user's name, name of book and name of app just once in the update. Also, the sentence is gramatically incorrect - it should say "his ReadingSocial bookshelf" not "their".
   
4. this update should summarize for better information density - perhaps the title says "Eduardo Cordeiro added Regina Spektor to his Artists iLike" and the body shows the album cover and lists the 2 songs "Ghost of Corporate Future" and "Little Rich Boy".
   
5. this update repeats the user's name and uses bold and bigger fonts than allowed.
   

Still to do:
summarization ...TODO...
localization ...TODO...

USER DATA ON THIRD-PARTY APPLICATION SERVERS

MUST DO

When the user gives access to their data to an app, the app can access and keep that data on their servers till the user uninstalls the app. But, orkut doesn't yet support app uninstall events. Until Orkut implements that, the app must not keep any data about the user obtained via Orkut APIs for a maximum period of 7 days.

BROKEN IMAGES

SHOULD DO

To ensure against broken images in updates and profileBox, either use a highly available service or use a CDN (content distribution network).

SITE MAINTENANCE

SHOULD DO

Apps should implement the following sequence to avoid apps breaking

• update the gadget spec to 'in maintenance version'
• wait for the cache to pick it up
• go into maintenance
• update the gadget spec to normal
• wait for the cache to pick it up

USING SCRAPBOOK FOR USER-TO-USER MESSAGING

MAY DO

Let users copy-paste Html scraps ...TODO

DIRECTORY LISTING

MUST DO

• List all the required fields ... TODO
• The app logo will be used against different colored backgrounds. So, the App logo must use transparent background for app logo and favicons.
• Recommended screenshot size ... TODO

SHOULD DO

• Incorporate name of your app in logo.

HELP AND SUPPORT

In order to create the best possible user experience and quickly grow your application's popularity, we recommend that you create comprehensive help resources. Users are more likely to continue to use your application and to share it with their friends if they understand how it works, how it relates to orkut, and how to contact you with questions or to report bugs. The orkut team won't provide user support for individual apps. By offering support for your app you'll not only help create a great user experience, but also be able to leverage user feedback to enhance, improve, and grow your application.

MUST DO

• You MUST have name of your developer company/organization name in-app so that users can identify the creators of the app. Fill out ModulePrefs/TODO
• You MUST provide a basic level of FAQ/help content hosted somewhere externally (on your site or even a blog). This might include: a summary of app's purpose, information on the basic functionality and how to use the app, as well as any questions you frequently receive from users. Fill out ModulePrefs/TODO
• When submitting an app, you MUST provide us with the URL to the help content so that we can link to it from the "About this App" page. Fill out ModulePrefs/TODO
• You MUST provide users with a way to contact you (email address, group, forum, or orkut community which you regularly monitor and participate in). This is an important part of creating a positive community surrounding your app, getting user feedback, and providing assistance with troubleshooting bugs. You MUST provide us with this contact information so that we can link to it from the "About this App" page. Fill out ModulePrefs/TODO

SHOULD DO

• You SHOULD have a basic level of FAQ/help content within the app itself. This can be a "Help" link on the app canvas page that opens an in-app help page describing the best ways to use your application, frequently asked questions, and your support contact inf
  
• We strongly recommend putting your help in-app so users can understand your app without leaving it. If you don't put your help in-app, it is suggested that you link to your external help content from within the UI (rather than just the "About this app" page).
• You SHOULD have a way for users to contact you in-app (email address, Group, or orkut community).
  

LOW LATENCY

MUST DO - PROFILEBOX

(pending verification of technique with Emote)

• The app must make no network calls in rendering the ProfileBox as that adds latency
• Images and Flash are allowed
• DataRequest calls are not allowed. The app must use the AppData store for content that will be displayed on the ProfileBox. AppData content will be pre-fetched and so will not incur network latency

MUST DO - CANVAS PAGE

Orkut can dynamically detect a pattern of JSON requests that your application makes at startup, and "prefetch" these results before you even ask for them. To get the biggest win, you need to carefully control what is in your first OpenSocial DataRequest:

• DO make your first DataRequest predictable
• DO request data that you will always or nearly always need, even if it's not needed immediately
• DO try to batch up multiple DataRequests into one
• DON'T request data you don't need
• DON'T add an Update Person App Data item to your first DataRequest
• DON'T call openSocial.requestCreateActivity() before sending your first DataRequest

MUST DO - PROFILEBOX AND CANVAS

• Turn on gzip for any content you deliver

SHOULD DO - PROFILEBOX AND CANVAS

• Combine multiple Javascript and CSS into single Javascript and CSS files
• Minimize JS and CSS using tool at ...
• Use CSS image spriting using tool at ...
• Set "Expires" headers on your content
• Split CSS and image files across 2-4 servers
• Place JS as late in the page as possible
• Take advantage of the multiple content sections in your gadget spec to render more tailored views for canvas and profile pages. In particular focus on making your profile view as lean as possible

Not sure:

• Take advantage of the Orkut Open Social request prefetcher - isn't this automatic?
• use Orkut albums to store and serve images?

SECURITY

MUST DO

Escape all user input before displaying onscreen.

• In general, user input should be handled carefully. In order to prevent user-entered JavaScript from being executed inadvertently, all input should be escaped using gadgets.util.escapeString() before being output (e.g. by assigning an element's 'innerHTML' property).
• App data is a special class of user input and is automatically escaped when fetched. This means that app data does not need escaping if used to store single string values. If a JSON string is stored in app data, however, it must first be unescaped before being passed into gadgets.json.parse(). But because this also unescapes all property values of the returned JavaScript object, the original problem reappears. In this case, all property values must be escaped before being output in case they contain malicious or mischievous script.
• When in doubt, go ahead and escape all string data before displaying it. Because escaping is a repeatable operatation, escaping an already escaped string will not have any effect.

Sign and verify all requests for third-party resources

• When using gadgets.io.makeRequest(), sign the request first using this technique. Signed requests provide a way of verifying whether a request is genuine -- that is, whether it originated from orkut -- and whether the requester is legitimate since the viewer's OpenSocial ID is signed and sent with the request. Sample code for verifying signed requests using PHP is available now and examples in other languages will be forthcoming.

ADS / MONETIZATION

The developer does not need to share any revenue with orkut.com. If you're using Adsense (by Google) then the usual adsense terms apply.

MUST DO

• Ads are not allowed in ProfileBox
• Promotion of other applications or products is not allowed in ProfileBox
• Ads are allowed on Canvas. The developer is free to use any Ad network or place Ads by direct arrangement
• Ads must say it is an Ad or sponsored link/message
• Ads must meet the guidelines laid out for Google Adwords. Some specific items of note:
  • Ads must not mimic system functionality or warnings
  • Ads must only use FamilySafe content - no adult content
  • Ads must not promote copyrighted content without permissoin
  • Ads must stay inbounds to the Ads region - they must not expand beyond the Ad rectangle
  • Flash Ads must be smaller than 50K
  • Animation is restricted to a maximum of 15 seconds, after which point they must remain static
  • Don't use strobing, flashing backgrounds or otherwise distracting ads are not allowed
• In addition:
  • Ads must not show any misleading content such as "update from your friend" or "scrap from your friend"

MAY DO

• Co-branding is allowed in ProfileBox and Canvas page as long as the user put it there and there is a non-commercial option available. Examples:
  • "Peter gave Amar a Heineken beer" is ok as long as Peter can also give Amar something else like a high-five.
  • Using a movie-sponsored skin for a slideshow is ok as long as the user chose it and there is also a default skin available for the slideshow.
• Cross-promotion of other apps is allowed on Canvas page as long as installing the app is not tied to unlocking any other functionality in the app.

PENALTIES

• If you are caught in violation of the policy, your app will be removed from the directory for 10 days; users who have installed your app will be able to continue to use it, but you will not be able to grow your user base during this time frame.
• If you are caught again, all apps produced by your company or organization will be removed from the directory for 30 days or for however long your app continues to violate these terms (whichever is longer).
  

---

Scratch space

• app as home and rooms
• app philosophy. preventing http://en.wikipedia.org/wiki/Tragedy_of_the_commons