Personalization API Developer Guide

The Personalization API introduced in 5.5 contains a ranking engine to help you sort items that users can click. For example, a gadget that displays items from an RSS feed can use the ranking engine to sort feed items.

Contents

1. Overview
2. Sample Code
3. Attributes that Affect Ranking
4. Changing How Items Are Ranked

Overview

You can use the ranking engine any time your gadget displays an ordered list of items. Just provide an array of rankable items or content items to the ranking engine, and the engine will return a sorted array of those items.

The ranking engine uses attributes such as clicks and the amount of time spent viewing items to determine how to sort the items. For example, if the user clicks every item except one, then by default that unclicked item will be the first item.

You can change how the ranking engine sorts items. For example, you can specify that a particular item should always be first or last. You can also group related items by specifying a data source for each group. Finally, you can not only set the values of attributes (such as clicks), but also specify how the ranking engine uses those attributes to sort items.

Sample Code

Here's how you typically use the ranking API.

1. Register to use the API by putting a <personalizationAPI> element in your gadget's gadget.gmanifest file. For example:

   <gadget minimumGoogleDesktopVersion="...">
     <about>
     <--! ... usual items such as name, description, and id go here ... -->
     <personalizationAPI />
     </about>
   </gadget>
   

2. Create a profile for your gadget. You'll use this profile to identify your gadget whenever you call the ranking API. Here's an example of creating the profile:

   var profile = google.pers.ranking.createProfile("MyGadget");
   

3. Unless you're ranking the items in a content area, create a rankableItem object for each item you want to be sorted.

   Note: Skip this step if you use a content area. This method is automatically called whenever the user adds a content item.

   For each rankable item, you need to specify an item identifier, a data-source identifier, and the profile. The item identifier can be anything that your gadget uses to identify the item; it might be a string or an array index. The data-source identifier is an application-specific number that you can use to group items. If you don't group items, just use the same data-source identifier for each item. Here's an example of creating rankableItem objects for items:

   var imageArray = new Array(); //one image per item
   var rankArray = new Array();  //one rankableItem per item
   ...
   //Just after an array of clickable items is created:
   for (var i = 0; i < numItems; i++) {
     var rankItem = google.pers.ranking.createRankableItem();
     rankItem.identifier = i;  //set item ID
     rankItem.updateRankingProfile(1, profile); //set ID & profile
     rankArray.push(rankItem); //add the rankable item to an array
   }

4. Unless you're ranking the items in a content area, call an item's incrementClicksAndUpdateClickedTime method whenever the user clicks the item.

   Note: Skip this step if you use a content area. This method is automatically called whenever the user clicks a content item or its details view's title.

   Usually, the value you specify to this method should be 1, but you can use a higher number to indicate that a click was more important. For example, you might use the value 2 for a double-click, or 5 for a click that was somehow as important as 5 ordinary clicks. Here's an example of calling incrementClicksAndUpdateClickedTime from an onclick handler:

   //rankIndex is the index of the selected item
   rankArray[rankIndex].incrementClicksAndUpdateClickedTime(1);
   

5. Whenever you want to sort items — such as after a click or data refresh — call the rankAllItems() method, specifying the maximum # of items to show from each data source. Use toArray() if you need to convert the return value to a JavaScript array.

   //Typical code for a gadget that displays an array of items
   var selectedItemID = rankArray[rankIndex].identifier;
   rankArray = google.pers.ranking.rankAllItems(
     profile, rankArray, rankArray.length).toArray();
     
   //Keep the same selected item as before
   for (var i = 0; i < rankArray.length; i++) {
     if (rankArray[i].identifier == selectedItemID) {
       rankIndex = i;
       break;
     }
   }

   If you're using a content area, use this code:

   //Code for a content area
   var itemsToRank = contentArea.contentItems;
   var rankedItems = google.pers.ranking.rankAllItems(
     profile, itemsToRank, itemsToRank.toArray().length);
   contentArea.contentItems = rankedItems;
   

Back to top

Attributes that Affect Ranking

The ranking engine sorts items using the attributes shown in the following table. If your gadget has items from multiple data sources — from multiple RSS feeds, for example — then the data source can also affect the item order, as described in the following table.

In general, the higher an item's score is, the more prominent the item should be in your gadget's GUI. You don't directly use item scores. Instead, your gadget requests the ranking API to return an ordered array of items, where the first item in the array (index 0) has the highest score. For example, if the user clicks every item except one, then by default that unclicked item will be the first item in the returned array, and your gadget should display it in the most prominent position.

Changing How Items Are Ranked

If you want to change how items are ranked, you can add code to do so. For example, you can specify that an item always should be at the top (item.rankType = contentRankingFlag.AlwaysTop) or bottom (item.rankType = contentRankingFlag.AlwaysBottom), or undo your change to make the item be ranked normally (item.rankType = contentRankingFlag.None).

Although you can't directly set the score for any item, you can change an item's attribute values, and you can tweak the algorithm the ranking engine uses to calculate scores. For example, to rank items by time, you need to set the "ItemTime" attribute value for each item using code like this:

//Parse the data source to get date and time for an item.
...
//Create a Date and set the value of the ItemTime attribute.
var date = new Date(year, month, day, hours, minutes, seconds, ms);
item.updateAttributeValue("ItemTime", date.getTime()/1000);

The "ItemTime" attribute supports two kinds of date formats:

• UTC date as an integer: the number of seconds since 1/1/1970 UTC. Use the code date.getTime()/1000 to convert a JavaScript Date object to this format.
• UTC date in VT_DATE format, as returned by JScript Date objects (see the getVarDate() method) and by some COM and ActiveX objects.

Back to top