3. Getting Additional MySpace Data

In the preceding chapter we covered how to fetch and make use of the Person object on the MySpace platform. But there’s a lot more data out there—such as the user’s friend list and the photos the user has uploaded. It’s the use of all this data that will propel your app from a lifeless Web game to a dynamic and social application with viral potential.

Most application developers use the friend list in order to spread and share their applications (see Chapter 5, Communication and Viral Features, to learn how) and other endpoints like albums and videos to make their apps more personal and engaging for the user.

In this chapter we’ll do just that by covering how to access and use your users’ data to make your app more dynamic and appealing. We’ll show how to retrieve your users’ friends; use paging to sort, sift, and display the data; as well as explore viewing albums, photos, and videos. We’ll also discuss some extras, such as how to check whether a user already has an app installed and how to check for and request permissions from a user. As we start to request more and more sensitive data, such as a user’s photos, permissions will start to come into play more and more.

From now on, our Tic-Tac-Toe game is no longer a boring JavaScript applet. It’s a feature-packed app that actually uses the power of the MySpace social network.

How to Fetch a Friend List and Make Use of the Data

This section will show you how to fetch a list of friends and then page through that list. You’ll also learn the various ways you can sort and filter a friend list, such as restricting it to only friends who have the app installed.

In our example Tic-Tac-Toe app, we’ll use the list of friends in two ways:

• Provide a list of all the Viewer’s friends so the Viewer can send invitations to those friends to add the app.

• Provide a list of friends who already have the app installed so the Viewer can challenge those friends to a game of Tic-Tac-Toe.

The actual invitation sending and game play challenges will be covered in Chapter 5, Communication and Viral Features. This section will lay the foundation for those functions by showing you how to pull out the friend list and filter it accordingly.

Getting the Friend List

This is the same request/response idea from Chapter 2, Getting Basic MySpace Data, that helps define OpenSocial. In fact, the friend list is just an opensocial.Collection of opensocial.Person objects, but instead of dealing with just one Person as in Chapter 2, we’re dealing with a list of them.

There are two major differences between fetching a single Person and fetching a friend list:

• Call newFetchPeopleRequest instead of newFetchPersonRequest.

• Instead of passing in an ID (such as Viewer or Owner), pass in an opensocial.IdSpec object.

An IdSpec object is a different way to specify a group of IDs. It requires you to define two parameters: the user ID and the network distance. The user ID specifies the context for the IdSpec—basically letting MySpace know if you’re asking for a group involving the Owner or the Viewer. MySpace supports the contexts of only Viewer and Owner. In other words, you can’t get a friend list for a random user; it has to be for either the Viewer or the Owner.

The network distance defines how far out the connections go. For example, specifying a network distance of 0 would denote just the Owner or the Viewer, and a network distance of 1 would denote the friends of the Owner or the Viewer. At this time MySpace supports a network distance only to a maximum of 1, so you can’t fetch the friends of your friends.

Let’s create a fetchFriendList() function to get a basic friend list. This function wraps the newFetchPeopleRequest. Our example is heavily simplified, though, so it isn’t our final version of the function. We’ll expand on it as we see what else you can do with a friend list. We’ll be inserting this function into the code of our Tic-Tac-Toe app found in Chapter 2. For those of you following along at home, place this function anywhere in the script tag in that code:

First, the IdSpec object is created using a user ID of VIEWER and a network distance of 1 to specify that we want the friends of the Viewer. Next, an opensocial.DataRequest object is instantiated and the request is added to the queue with a custom key of TTT.RequestKeys.VIEWER_FRIENDS. Finally, the request is sent off (and the response will find its way back to the specified callback).

Filters and Sorts

The first example we showed you just fetches an arbitrary subset of friends of the Viewer. This list is typically returned in the order in which the friendships were made and is not terribly complex. OpenSocial, however, defines a number of ways to sort and filter fetched lists, making them a lot more useful. Before getting to the code, let’s look at the available options. The MySpace-supported filter types and sorts are shown in Table 3.1.

Table 3.1 Supported Friend List Filters and Sorts on MySpace

Let’s revisit the fetchFriendList() function, but this time with support for sorts and filters. Again, we’re not quite at the final version of our function, but this code brings us a step closer:

You can see that the filters and sorts are specified by adding opensocial.DataRequest.PeopleRequestFields.FILTER and opensocial.DataRequest.PeopleRequestFields.SORT_ORDER to the parameters.

Paging

According to the OpenSocial spec, the default number of items returned for a request is 20. That means our fetchFriendList() function returns the first 20 friends in the list. But what if a user has more than 20 friends? Enter paging.

Paging is a way to get a large collection of data one chunk at a time. That means that once we have fetched friends 1 to 20, we can then fetch friends 21 to 40, then 41 to 60, and so on. OpenSocial also provides a way to specify which chunk of friends you want for a given request.

To demonstrate paging, let’s expand one final time on our fetchFriendList() function:

You’ll notice that opensocial.DataRequest.PeopleRequestFields.FIRST and opensocial.DataRequest.PeopleRequestFields.MAX have been added to the parameters. MAX defines the maximum number of friends to fetch at a time, so if you specified a MAX of 100 (the maximum allowed by MySpace), you’d get the friend list in chunks of 100. FIRST specifies which friend to start fetching from, so if you specified that FIRST is 201 and MAX is 100, you’d get friends 201 to 300.

That means you’ll want to keep MAX at a constant value and increment FIRST by that value for each request. Assume we define MAX to be 50; we’d start out with a value of FIRST as 1. If the user requested the next page, we’d change FIRST to 51, and then 101, and so forth. The API provides you with the total number of friends in the list (in addition to the number fetched with the current request) to aid you in paging.

In our Tic-Tac-Toe app we fetch 20 friends at a time. You can see a successful friend list request in Figure 3.1.

Figure 3.1 Screen shot of a successful friend list request.

Let’s take a look at the paging object we used:

The Pager object in our Tic-Tac-Toe app does three things:

1. Provides HTML markup for Next and Prev buttons that we can use to allow the user to actually navigate between pages.

2. Stores the value of FIRST that is the current value.

3. Handles what happens when the Next and Prev buttons are clicked.

Meanwhile, the getMarkUp() function handles the actual paging algorithm. With this function there are three possible outcomes:

1. The number of records fetched is less than the number requested (MAX). This means there is only one page of data, so no paging is required.

2. The value of FIRST is greater than the size of a page. Therefore, there is at least one previous page, so we need the Prev link.

3. The total number of friends is greater than all the friends fetched so far. Therefore, there are more friends who can be fetched, so a Next link must be added.

Using the Data

We’ve now defined a function that wraps the OpenSocial function newFetchPeopleRequest(). In our Tic-Tac-Toe app we call that function like so:

First we get a reference to the currently selected list. If it’s the list of friends who have the app installed, we add that filter (TTT.ListTypes.HASAPP_FRIENDS) and send it into the wrapper.

The callback function we passed in, TTT.Lists.callback, will be executed once the friend request has been made and the API responds with some data. Let’s take a look at the callback function’s code and walk through it in detail. You’ll recognize a lot of the OpenSocial aspects from when we discussed callbacks and data parsing in Chapter 2, Getting Basic MySpace Data:

The callback checks for errors in the request and handles any retry attempts. Each list maintains its own retry count, and a failed request is retried the specified number of times.

If there was no error, the response is looped through in an attempt to find out what data it contains. This allows the callback to handle any kind of response. It can currently handle the friend list responses, and as you’ll see later on, it can also handle the response for the photo list.

If everything works (and it should), the data is saved to the TTT.List object, along with the total size of the collection for paging purposes, and the filtered list is drawn.

Since each friend is represented by an opensocial.Person object, actually parsing out the data for each friend is similar to how it was done in Chapter 2. For details, refer to that chapter, or for a complete code reference for the function TTT.Lists.draw(), check the Chapter 3 sample code found here: http://code.google.com/p/opensocialtictactoe/source/browse/#svn/trunk/chapter3.

Fetching Media

Media includes a user’s albums, photos, and videos. Dealing with media items is very similar to the other requests we’ve covered so far, including how they’re fetched, how you page through a list, and how the response is parsed.

Photos

You can fetch all of the photos your user has uploaded to his or her MySpace Profile, provided the user grants your app proper permissions. Users can limit permissions, but we’ll explore how to deal with that later in the permissions section of this chapter. By default, though, you should have access to all of a user’s public photos. Photos are defined by the MyOpenSpace.Photo object, which contains the fields shown in Table 3.2. These fields are accessed in the same way as for a Person, for example, photo.getField(MyOpenSpace.Photo.Field.CAPTION).

Table 3.2 Fields for the MyOpenSpace.Photo Object

Let’s take a look at the function signature that’s used to fetch photos. You’ll notice that it’s slightly different from how we fetch people:

MyOpenSpace.DataRequest.newFetchPhotosRequest = function(id, opt_params)

id is a string used to identify who owns the photos. The value can be either opensocial.IdSpec.PersonId.VIEWER or opensocial.IdSpec.PersonId.OWNER.

opt_params is an object that specifies optional parameters. In this case only the paging parameters opensocial.DataRequest.PeopleRequestFields.FIRST and opensocial.DataRequest.PeopleRequestFields.MAX are allowed.

The reason the function signature is in a different format from the other request functions is that it is a MySpace-specific extension. The OpenSocial spec defines ways for containers to extend the core functionality of the OpenSocial spec. In this case MySpace has added several new endpoints. Because it’s an extension, the function exists in the MyOpenSpace namespace and not the opensocial namespace.

In our Tic-Tac-Toe app we fetch the list of photos for the user and allow the user to select one. That photo then becomes the background for the Tic-Tac-Toe game board. Let’s take a look at a function that wraps MyOpenSpace.DataRequest.newFetchPhotosRequest:

We set some paging parameters, create the opensocial.DataRequest object, and send off the request. You’ll notice the other big difference here, besides the namespace change, of executing one of the MySpace extensions. Typically the fetch request, such as newFetchPeopleRequest, is called via an instance of an opensocial.DataRequest object. However, when using this MySpace extension, we call it statically from the MyOpenSpace.DataRequest namespace. You can compare and contrast this function with the fetchFriendsList function to see the slight differences. This code can be seen in action in Figure 3.2.

Figure 3.2 Screen shot of a successful photo request.

Albums and Videos

The pattern for fetching albums and videos is actually the same as it is for fetching photos. So, if you know how to request photos, you know how to fetch albums and videos.

Obviously, the fields and objects differ depending on what you’re fetching, but the basic structure remains the same. That said, we’ve included the fields and function signatures here as a reference for you.

Albums

Albums are defined by the MyOpenSpace.Album object, which contains the fields outlined in Table 3.3.

Table 3.3 Fields for the MyOpenSpace.Album Object

The function signature is as follows:

MyOpenSpace.DataRequest.newFetchAlbumsRequest = function(id, opt_params)

id is a string used to identify who owns the albums. The value can be either opensocial.IdSpec.PersonId.VIEWER or opensocial.IdSpec.PersonId.OWNER. opt_params is an object map that specifies optional parameters. In this case only the paging parameters are allowed: opensocial.DataRequest.PeopleRequestFields.FIRST and opensocial.DataRequest.PeopleRequestFields.MAX.

Videos

Videos are defined by the MyOpenSpace.Video object, which contains the fields outlined in Table 3.4.

Table 3.4 Fields for the MyOpenSpace.Video Object

The function signature is as follows:

MyOpenSpace.DataRequest.newFetchVideosRequest = function(id, opt_params)

id is a string used to identify who owns the videos. The value can be either opensocial.IdSpec.PersonId.VIEWER or opensocial.IdSpec.PersonId.OWNER. opt_params is an object map that specifies optional parameters. In this case, only the paging parameters are allowed: opensocial.DataRequest.PeopleRequestFields.FIRST and opensocial.DataRequest.PeopleRequestFields.MAX.

Since the implementation of both the video and album endpoints is so similar to that of photos, which we’ve already discussed, we leave it to you to experiment with these as you wish.

Using opensocial.requestPermission and opensocial.hasPermission to Check a User’s Permission Settings

Permission settings are applied to both data and actions. A user can specify permissions on a per-app basis, but there are a couple of global permission settings that you’ll need to either work with or work around (see Chapter 2, Getting Basic MySpace Data, for details).

In our Tic-Tac-Toe app we display a list of the user’s photos to the user. But public and private photos each have their own permission setting, so we should first check to see if we have permission before we send out the request. In our app we check whether we at least have access to the user’s public photos:

setBackgroundClicked() is called when the appropriate tab is clicked at the top of the app. We’re looking for permission to access public photos, so we call opensocial.hasPermission() to see if we can make this call. If we can, we fetch the photos. If we can’t, we request permission. To do this, we first must provide a reason. The reason is just a string that is displayed to the user. Then we call opensocial.requestPermission(), passing in a callback function. Note that MySpace supports only one permission at a time here, but you’ll need to put the Permission object into an array anyway.

Finally, once the user closes the permission window, the callback function is executed. The main piece of information the response provides is whether or not a permission was granted. If no new permissions were granted, hadError() will be true. If a new permission was granted, hadError() will be false. If there was no error, we know the permission was granted and we can continue on to fetch the photo list. Table 3.5 presents all of the supported Person fields along with their return types.

Table 3.5 Permissions You Can Request on MySpace

Summary

One of the nice things about OpenSocial is that the basic techniques for most tasks are fairly similar. For example, requesting a friend list follows a similar request/response pattern to requesting a photo. Once you have that basic technique down, you can extrapolate and use it again and again.

Just be careful and watch out for permissions—they’re one of the biggest causes of unexpected behavior in apps, and they will trip you up if your code doesn’t work to accommodate them. If you’re running into problems with any requests, always check your permissions.