English | Site Directory

Orkut Developer Home

Orkut Developer Guidelines

The guidelines below detail the dos and don'ts of the orkut development process including where advertising can be placed, limitations on text size and style for app-generated updates, recommendations for making your application load faster, and more. Items that start with Always and Never must be followed or your app may be removed from the orkut directory (see the Violations section below) while items beginning with Consider are general recommendations that you can use as you see fit.

Roles

There are two actors in OpenSocial. The owner of an application represents the individual whose profile hosts it while the viewer represents the individual using it.

When a user interacts with an application installed on his own profile, viewer and owner represent the same person. This is a special case—many times, the viewer and owner will be different. Viewers can have three different relationships with the owner: they may be friends, friends-of-friends (FoF), or unrelated.

Aside from their relationship to the owner, viewers also have a relationship with the app itself—they either have it installed on their own profile or they don't. The following figure establishes these relationships graphically.

General

MUSTs

MUST NOTs

  • Never include content that is inappropriate for persons under 18 years of age. This includes:
    • Mature sexual themes, nudity, and/or sexual activity
    • Offensive or inappropriate content
    • Crude or indecent language

User Experience

MUSTs

  • Always include error handling routines to generate a user-friendly message. HTML alert boxes are strongly discouraged as they're interruptive.
  • Always call the gadgets.window.adjustHeight() method when the application's content changes to prevent scrollbars from appearing.

SHOULDs

  • The app should fit all content within the horizontal bounds of the current view (543 pixels for profile view, 835 pixels for canvas view) so horizontal scrollbars won't appear. Use relative widths (e.g. style="width:100%") to ensure your content is wrapped appropriately.
  • To ensure against broken images in updates and the application views, use a highly available service or a high-bandwidth content distribution network (CDN).
  • Apps may request and render user-submitted HTML snippets such as the <object> tag provided by YouTube for embedding videos in a web page.
  • 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 (referred to as FA below)
    • Guest - everyone else

MUST NOTs

  • Don't show a blank screen as the app is loading. Instead, display a "loading..." message or graphic.

    Tip: Use http://www.ajaxload.info/ to generate Ajax loader icon.

Profile View

The profile page is a user's face to the orkut community, so the owner should be able to easily see how their profile will appear to others.

MUSTs

  • The content displayed in the profile view must be the same for the app's owner as well as other users. For example, all users should see the owner's top friends, favorite movies, and so forth. The available actions may be different, however. Owners, for example, may be able to rearrange their top friends while viewers with the app installed can comment on the arrangement. Guest viewers will only be able to see the arrangement until they install the app themselves.

    • Tip: Design for guest viewers first, then add actions for FA viewers. Design for the app owner last.

SHOULDs

  • Apps in the profile view are 280 pixels tall by default, expandable to 500 pixels. All content should fit within 500 pixels to prevent vertical scrollbars from appearing.

MUST NOTs

  • Never autoplay in the profile view. Since up to three apps can be displayed on the profile, automatically starting a music or video clip may distract users, especially if several applications start playing simultaneously. Autoplay is permitted in the canvas view, however.
  • Never display a message to guest viewers forcing them to install the app on their own profile before using it. The app's owner and all viewers must see the same content as stated above and actions shouldn't be presented if they're not available to the current user. For example, guest viewers shouldn't see a link to "add a favorite book" since app data is only available to viewers that have the app installed.
  • Never include a link to add the application if the current user hasn't installed it. Orkut automatically places a link below each app in the profile view to "add this app to your profile," so the user can already easily install your app without any advertising on your part.

Canvas Page

SHOULDs

  • Canvas pages should support a guest mode that lets users experience the app before installing it. For example:
    • A game like myHangman should let guest users play a game and compare their score with the app owner's.
    • An interactive app like PhotoAttack should allow guest users to create a photo-attack using the app owner's photos.
  • Since the API doesn't currently support app install callbacks, you can use browser cookies to achieve this use case until support is added in the API.
  • Autoplay of music and video IS allowed since the issue of multiple apps autoplaying simultaneously doesn't apply on the canvas page.

MUST NOTs

  • Never assume that the user is navigating to the canvas from the profile view. Since users may land in the canvas view, follow the profile view guidelines provided above except those explicitly overridden below.
  • Never include automatic redirects—all redirects should be triggered by a user action (e.g. clicking a link).
  • Never redirect guest viewers to the app install page.

Updates

OpenSocial activities are presented as orkut updates. Activities posted by an app on a user's behalf are viewable on that user's "My updates" page and all friend activities are collected in the "updates from my friends" panel on the home page. Currently, each app can post one update per person per day.

MUSTs

  • Updates must reflect a user action within your app (e.g. adding an artist, sending a gift to a friend, writing a review, etc.).
  • Any images used must be relevant to something the user created, bookmarked or posted.
  • Information shown in the title and body must be different with no overlap.

SHOULDs

  • Provide notification inside the app that an update was added.
  • Display the profile picture of a friend if the owner interacted with that friend (e.g. adding a new friend using Top Friends).
  • 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. Here are some examples:
    • This update repeats the user's name 3 times and mentions ReadingSocial 3 times. The user's name, app name, and book title should be mentioned only once in the update. The sentence is also grammatically incorrect—it should read "his ReadingSocial bookshelf" and not "their."

      Tip: Use opensocial.Person.getField(opensocial.Person.Field.GENDER) to return an opensocial.Enum.Gender object indicating the appropriate gender.

    • This update should be condensed for better information density. For example, the title can read "Eduardo Cordeiro added Regina Spektor to his Artists iLike" while the body shows the album cover and lists the 2 songs added.

MUST NOTs

  • Never post an update just because the user views an application. If they are viewing the app for the first time (i.e. they just installed the app) the app should not post an update because installing an app represents an orkut action, not an action within the application. Only post updates when a user does something meaningful within your application (e.g. changes status or beats a high score).
  • Never display the profile picture of the activity owner since it does not add unique information to the update.
  • Never display application logos in the updates. The app already gets attribution in the title and its fav-icon will be added soon.
  • Never display generic updates. Updates like the following are basically an advertisement for the app and are not allowed. The activity should display more information such as the titles of books that the user is reading.
  • Never include links to add the application or to the AppInfo page—orkut adds these automatically. The update below is not acceptable:
  • Never use bold text or font sizes larger than 12pt. The following example violates both and is not permitted:
  • Never include animated GIF images in updates—any images used in updates should be static graphics that represent a specific user action without distractions such as animation.

User Data on Third-Party Servers

MUSTs

  • All user information must be removed from third-party servers after 7 days with the exception of the following fields which may be stored indefinitely:
    • ID
    • NAME
    • PROFILE_URL
    • THUMBNAIL_URL
    Once support is added for uninstall event handlers, extended user profile information may be stored until the application is removed, but 7 days is the maximum duration until then.

MUST NOTs

  • Never expose any user data retrieved using the OpenSocial APIs outside of the application. You are not permitted to expose profile information "scraped" using the API on your application's website or any other channel—instead, this information must be used within the context of the app that retrieved it.

Maintenance

SHOULDs

  • To prevent apps from breaking during back-end maintenance periods, the following procedure should be followed:
    1. Update the app spec to a maintenance version and wait until this new spec is cached.
    2. Perform any required maintenance and test your changes in the sandbox.
    3. Replace the maintenance version with the updated app spec.
    4. Wait for the updated app specification to be re-cached.

    • If no back-end changes are needed, you shouldn't need to replace the current application with a maintenance version—just place the updated spec in a new file, test your changes in the sandbox, and replace the current spec with the new code when ready.

Directory Listing

MUSTs

  • Always specify the following ModulePrefs attributes before submitting your application to the directory.
    • title
    • description
    • author
    • author_email
    • screenshot
    • thumbnail
  • Always use a transparent background for the app logo and fav-icons since these may be displayed against various colored backgrounds.

SHOULDs

  • Incorporate the name of your app in its logo.
  • While the ModulePrefs screenshot attribute is not required, it is recommended. Screenshots should be no larger than 400x400 pixels.

MUST NOTs

  • Never use "Google" or "Orkut" in the title of your application.
  • Never use trademarked logos, including Google or Orkut logos, in the thumbnail or screenshot of your application.
  • Never specify an animated GIF image as an application's thumbnail or screenshot—both should be static graphics that represent the application without distractions such as animation.

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 bugs. The orkut team won't provide user support for individual apps. By offering support for your application, you'll not only help create a great user experience, but also be able to leverage user feedback to enhance and grow your application.

MUSTs

  • Always provide the name of your developer company/organization name so users can easily identify the authors.
  • Always provide a basic level of FAQ/help content hosted somewhere externally (e.g. on your site or blog). This could include a summary of the app's purpose, information on basic functionality and use, and any questions you frequently receive from users. Here's an example from Books iRead:
  • Always provide the URL to the help content so that it can be linked from the "About this App" page.
  • Always provide users with a way to contact you (email address, group, forum, or orkut community which you regularly monitor and participate in), such as the help link provided on ActOnME's PhotoAttack app. This is an important part of creating a positive community surrounding your app, getting user feedback, and troubleshooting assistance with bugs.

Latency

There are a number of things you can do to reduce the amount of time it takes your app to load on orkut. From general web development best practices to orkut-specific tweaks, check out the Latency Combat Field Manual for ways to get your app up to speed. Here are a few highlights:

MUSTs

  • Always batch up multiple request items into a single data request. It is best to request all the data you need in your first DataRequest because orkut can "pre-fetch" this data and have it ready when your app start to load.
  • Always compress any data returned from your third-party servers using gzip.

Note: Any HTTP responses returning gzipped data must have the Content-Encoding header set to 'gzip'.

SHOULDs

  • Don't make requests for third-party content in the profile view. Apps should use OpenSocial's persistence API (i.e. app data) to store any data needed for rendering the profile view. App data is pre-fetched and does not incur network latency.
  • Take advantage of the multiple content sections in your gadget spec to render more tailored views for canvas and profile pages, focusing especially on making the profile view as lean as possible.
  • Combine multiple JavaScript files into a single script.
  • Combine multiple stylesheet files into a single stylesheet.
  • Place JavaScript at the end of your app specification.
  • Minimize JavaScript and CSS using a tool like YUI Compressor.
  • Consider using CSS sprites instead of individual graphics.
  • Consider loading images from 2 to 4 domains or subdomains to optimize the number of open HTTP connections.
  • Set the "Expires" header on your server's HTTP responses to an appropriate value in order to take advantage of caching.

Security

MUSTs

  • Always 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.

      Tip: When in doubt, go ahead and escape all string data before displaying it. Because escaping is a repeatable operation, escaping an already escaped string will not have any effect.

  • Always 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 validating 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. Regardless of the ad serving platform chosen, apps must follow the standard AdSense terms.

MUSTs

  • Ads must say it is an Ad or sponsored link/message.
  • Ads must meet the guidelines laid out for Google AdWords. Here are some highlights:
    • Ads must not mimic system functionality or warnings.
    • Ads must only include FamilySafe content suitable for all audiences.
    • Ads are not permitted to directly promote hard alcohol and liquors.
    • Ads must not promote copyrighted content without permission.
    • Ads 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 they must remain static.
    • Strobing, flashing backgrounds or other distractions on ads are not allowed.

SHOULDs

  • Co-branding is allowed in the profile and canvas views as long as the user put it there and there is a non-commercial option available. Examples:
    • "Peter gave Amar a Heineken beer" is okay as long as Peter can also give Amar something else like a high-five.
    • Using a movie-sponsored skin for a slideshow is okay 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 current app.
  • Ads are allowed on Canvas. The developer is free to use any Ad network or place ads by direct arrangement.

MUST NOTs

  • Never display ads in the profile view.
  • Never promote other applications or products in the profile view.
  • Ads must never show text or other content intended to mislead the user such as "click here to message your friends" that links to a product or anything other than the indicated content.
  • Ads must never occupy more than 20% of the app's area visible above the fold on a 1024x768 screen.

Localization

Orkut-specific localization guidelines will be available soon. In the meantime, please conform to the recommendations set forth in the Google Gadgets internationalization doc.

Policy Violations

If your application is found in violation of any policy set above, you will be contacted at the email address provided in the author_email attribute of your app's ModulePrefs element. Depending on the severity of the violation, you may be given 24 hours to address the issue and respond, although your app may be removed immediately if the violation is especially egregious. If your app is removed, it will not appear in the directory for up to 10 days, although users who have installed your app may be able to continue using it. If the violation has not been addressed after 10 days, however, users will no longer be able to access your application on orkut.

If you are found in violation again, all apps produced by your company or organization will be removed from the directory and will not be reinstated for 30 days or until all violations are fixed (whichever is longer).