Tuesday, December 18, 2007

How to get VIEWER and OWNER.

This tutorial will show you how to use the Person request methods to gather information about specific people.

The ability to utilize information about OWNER, VIEWER, OWNER_FRIENDS, and VIEWER_FRIENDS is one of the most important aspects of any Opensocial application. Without these options, it would just be another application, wouldn't it? Well, we think so.

In this article we'll show you how to gather information about OWNER and VIEWER and it'll be up to you to decide what to do with it.

We won't build any objects here, I'll just show you how to use the functionality.

Getting Started The first thing we'll need to do is instantiate an opensocial.DataRequest. Since the Opensocial object is already available to us in any Opensocial container, all we need to do is call the constructor method.

I'm going to catch the resulting instance in a variable called reqObj.


        var reqObj = opensocial.newDataRequest();

The reqObj we just created has a couple of functions we'll need to use:

add: adds a new request item to our overall data request.
send: sends and retrieves the data request (including all the additions)

Getting OWNER and VIEWER The OWNER of an application is defined as the Person (user) who owns the page on which the app is running. This is the person who added the app to his/her page.

In contrast, the VIEWER of an application is defined as the Person (user) who is viewing the page/app. He or She is the one utilizing your app or playing your game. This Person is your targeted user.

The good news is that getting and utilizing these Persons is relatively easy.

Since OWNER and VIEWER are both single Persons, we'll need to Add (2) newFetchPersonRequests to our opensocial.DataRequest instance before we send it. Very straight forward.

Notice that the reqObj.add method takes (2) arguments: the actual request, and a String containing a label. The label is used to retrieve the data from the object that will be returned from the data server. Below, I've chosen to label them 'myOwner' and 'myViewer'.

            var reqObj = opensocial.newDataRequest();
            
            reqObj.add( reqObj.newFetchPersonRequest( 'OWNER' ), 'myOwner' );
            reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER' ), 'myViewer' );

Cake! Now all we have to do is send the DataRequest. The send method takes a single argument: a function to fire when the data has been retrieved.

I'm going to define an external function to handle the returned data, so all I need to do is pass in a function reference as an argument.

            var reqObj = opensocial.newDataRequest();
            
            reqObj.add( reqObj.newFetchPersonRequest( 'OWNER' ), 'myOwner' );
            reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER' ), 'myViewer' );
            
            reqObj.send( handleReturnedData );

Handling The Returned Data Object We now need to assemble the handleReturnedData function. The send method will pass one argument to our custom method: the returned data object, so we'll need to be sure to define an argument to catch that data. (retDataObject)

The returned data object has a couple of methods that we can use for error handling. First, the Data Response object (retDataObject) has a hadError() function that can be used to retrieve a boolean value. On top of that, each of our individual Response Items have hadError() and getError() methods.

We'll just check all of them.

            var reqObj = opensocial.newDataRequest();
            
            reqObj.add( reqObj.newFetchPersonRequest( 'OWNER' ), 'myOwner' );
            reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER' ), 'myViewer' );
            
            reqObj.send( handleReturnedData );
            
            function handleReturnedData( retDataObject ){
                if( retDataObject.hadError() || retDataObject.get('myOwner').hadError() || retDataObject.get('myViewer').hadError()){
                    // handle the error
                    return; // exit the function
                }
            }

Now that we've done error handling, we can grab our VIEWER and OWNER Person Objects. We'll use the Response Item's getData() method to retrieve these.

            var reqObj = opensocial.newDataRequest();
            
            reqObj.add( reqObj.newFetchPersonRequest( 'OWNER' ), 'myOwner' );
            reqObj.add( reqObj.newFetchPersonRequest( 'VIEWER' ), 'myViewer' );
            
            reqObj.send( handleReturnedData );
            
            function handleReturnedData( retDataObject ){
                if( retDataObject.hadError() || retDataObject.get('myOwner').hadError() || retDataObject.get('myViewer').hadError()){
                    // handle the error
                    return; // exit the function
                }
                var owner = retDataObject.get('myOwner').getData();
                var viewer = retDataObject.get('myViewer').getData();
            }

The opensocial.Person Object Both of the variables we just defined (owner and viewer) are now opensocial.Person Objects. They can now be utilized to gather information.

Please check our opensocial.Person Tutorial information about retrieving data from the opensocial.Person object.

Also, read our Getting Friends Tutorial for information on how to retrieve OWNER_FRIENDS and VIEWER_FRIENDS.