ptg 74 Chapter 5 Communication and Viral Features // Update the UI for the failures for(var i = 0; i < failure.length; i++){ clicked = current_list.list_dom["myspace.com:" + failure[i]]; if(clicked) clicked.style.backgroundColor = "red"; } } } } So, there is a lot going on here.The callback for requestShareApp is especially important.The first thing that really happens is that the various types of errors are trapped, and an error message is displayed if one is found. If there was no error, we cycle through the list of currently selected users, revert the background of the corresponding div tags to white, and reset the list.There are now two possibilities: the user either canceled the pop-up or hit Send. If the pop-up was canceled, there’s no more work to do. If the pop-up wasn’t canceled, the user must have hit the Send button, so we need to figure out who the actual recipients were.We do this by accessing the responseValues object in the ResponseItem that’s passed back to us. responseValues contains two arrays: One, success , contains the list of users who were successfully sent an invite.The other, failure , contains the list of users who had an error occur when the invite was sent. Both arrays contain the integer IDs of the specified users. There are a couple of things to note when accessing the success and failure arrays. First, users who already have the app installed won’t get the invite, but neither will they show up in either array. Second, the IDs in the array are integers, so they don’t exactly match the IDs that are sent by the API (in the format "myspace.com:6221" ). Back to the function at hand.We extract the success and failure arrays and loop through them.We turn the background color of all the successful recipients to green, and that of all the failures to red.You’ll notice that we have to append "myspace.com : " to the beginning of each ID so it matches up with the IDs we fetched from the API. It may be useful to add a More button to your app, something like “Select Random 20” that will randomly select 20 of the user’s friends.This will help encourage users to share the app with a larger group of friends; turning 20 clicks into one click makes it much easier for your users. Using opensocial.requestSendMessage to Send Messages and Communications Let’s examine how opensocial.requestSendMessage works.The requestSendMessage function provides a number of ways for apps to communicate with users. MySpace supports the following message types: n Send Message: a private one-to-one message that will arrive in the user’s Mail Center in-box n Comment: a public one-to-one message that will appear on the user’s Profile page in the Comments section From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg n Bulletin: a one-to-many message that will appear in the Bulletins module of each of the user’s friends’ Home pages n Blog: a one-to-many message that will appear on a MySpace user’s Blog n Profile: not a message per se; allows an app to edit/update the user’s Profile.The following Profile sections can be edited and are chosen by the user in a drop- down menu: About Me I’d Like to Meet Interests Edit Artist Profile Movies Television Books Heroes Defining requestSendMessage opensocial.requestSendMessage has the following signature: opensocial.requestSendMessage = function(recipients, message, opt_callback, opt_params) You probably noticed that the signature for opensocial.requestSendMessage is very similar to that of opensocial.requestShareApp .The big difference is that you’re allowed to define only one recipient ID at a time; the container will reject an array of IDs. Similar to requestShareApp , however, are opt_callback , which is the function that’s invoked when the pop-up modal has closed, and opt_params , which is unused. Note Some targets don’t require a recipient; these are Bulletin, Profile, and Blog. Any recipient value passed in for these targets will be ignored. The message parameter is an object of type opensocial.Message .The supported content of the message depends on the message type; here’s a quick breakdown: n Types that support a message title are Send Message, Comment, Bulletin, and Blog. The title doesn’t support any HTML markup. n All of the message types support a message body. All support some HTML markup in the body.Tags like <div>, <script>, and <span> are stripped out, but tags like <a>, <img>, <b>, and <em> are allowed. When creating the opensocial.Message object, you need to specify the opensocial.Message.Field.Type property; this specifies which of the message types Using opensocial.requestSendMessage to Send Messages and Communications 75 From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg will be sent.Table 5.1 shows the list of supported types and the opensocial.Message. Field.Type fields to which they correspond. Profile and Blog are MySpace-specific extensions and not in the OpenSocial spec, which is why they’re namespaced a little differently. In the code that follows, we’ll show you how to make use of the message types when using requestSendMessage . Writing the requestSendMessage Code Now that we’ve defined our requestSendMessage function, let’s plug it into our Tic-Tac- Toe app and try it out.The following example function wraps requestSendMessage and is useful if you want to use requestSendMessage in multiple places throughout your app: function rsmWrapper(id, subject, body, type, callback){ var param = {}; param[opensocial.Message.Field.TYPE] = type; param[opensocial.Message.Field.TITLE] = subject; var message = opensocial.newMessage(body, param); opensocial.requestSendMessage(id, message, callback); } Note that the function is fairly similar to the requestShareApp wrapper.This function just requires two additional parameters to construct the opensocial.Message object: subject and type .The type parameter corresponds to one of the opensocial.Message.Field.Type values found in Table 5.1. Now that we have our requestSendMessage wrapper, we can make use of it in the app by creating different types of messages.A fairly simple and effective type of message is a bulletin; it is a one-to-many message that gets blasted out to all the user’s friends. function rsmBulletin(){ var this_app = opensocial.getEnvironment().currentApplication; var profile_link = this_app.getField(MyOpenSpace.Application.Field.PROFILE_URL); var image_link = this_app.getField(MyOpenSpace.Application.Field.ICON_LARGE); 76 Chapter 5 Communication and Viral Features Table 5.1 Supported Message Types Message Type Value of opensocial.Message.Field.Type Send Message opensocial.Message.Type.PRIVATE_MESSAGE Comment opensocial.Message.Type.PUBLIC_MESSAGE Bulletin opensocial.Message.Type.NOTIFICATION Blog MyOpenSpace.PostTo.Targets.BLOG Profile MyOpenSpace.PostTo.Targets.PROFILE From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg var subject = "Social Tic-Tac-Toe is Here!"; var body = "Hey everyone! I' m playing TTT online with my friends, come"; body += "<a href='" + profile_link + "'>play a game</a> with me!"; body += "<center><img src='" + image_link + "'/></center>"; rsmWrapper(opensocial.IdSpec.PersonId.VIEWER, subject, body, opensocial.Message.Type.NOTIFICATION, rsmBulletinCallback); } Since bulletins don’t use any template messaging, we have to generate all the links ourselves.To do this, we make use of the instance of a MyOpenSpace.Application object for this app.When an app is rendered, the MySpace platform pushes down a script-accessible representation of the app’s information.This object may be accessed from the environment with the call opensocial.getEnvironment().currentApplication Specific data that may be found in this object includes: 1. App ID, accessed via the field enum MyOpenSpace.Application.Field.ID 2. Name, accessed via the field enum MyOpenSpace.Application.Field.Name 3. Profile URL, accessed via the field enum MyOpenSpace.Application.Field. PROFILE_URL 4. Install URL, which for right now is the same as the Profile URL (which is where the app is installed from), accessed via the field enum MyOpenSpace. Application.Field.INSTALL_URL 5. Canvas URL, accessed via the field enum MyOpenSpace.Application. Field.CANVAS_URL 6. The 64ϫ64 icon URL, accessed via the field enum MyOpenSpace.Application. Field.ICON_LARGE 7. The 16ϫ16 icon URL, accessed via the field enum MyOpenSpace.Application. Field.ICON_SMALL The Application object behaves just like the Person object—data is accessed through the getField function. For example, to access the app’s name in your script code, you would make the following call: opensocial.getEnvironment().currentApplication.getField( MyOpenSpace.Application.Field.NAME); Here we use the app’s Profile URL and the large icon to generate the bulletin mes- sage. Some of the supported HTML tags are also used for the body.Then the wrapper function is called and voilà! We’ve sent our first message! Bulletins are great for getting the word out to a large audience, but they lack a per- sonal touch. In our Tic-Tac-Toe app, one user can challenge another user to a game. Using opensocial.requestSendMessage to Send Messages and Communications 77 From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg When this challenge is initiated, we send out a message from the challenger to the challenged.The code for that looks like this: function rsmMessage(){ var current_list = TTT.Lists.getCurrentList(); var id = this.list_index; TTT.Lists.itemClicked = id; var this_app = opensocial.getEnvironment().currentApplication; var profile_link = this_app.getField(MyOpenSpace.Application.Field.PROFILE_URL); var image_link = this_app.getField(MyOpenSpace.Application.Field.ICON_LARGE); var subject = "I challenge you to a TTT duel!"; var name = ""; for(var i = 0; i < current_list.list.length; i++){ if(current_list.list[i].getId() == id){ name = current_list.list[i].getDisplayName(); break; } } // If the name isn't empty, add a space before the name name = ("" === name) ? name : " " + name; var body = "Hey" + name + "! You've been challenged to "; body += "a game of Tic-Tac-Toe, click <a href='" + profile_link + "'>"; body += "here</a> to accept the challenge!<center>"; body += "<img src='" + image_link + "' /></center>"; rsmWrapper(id, subject, body, opensocial.Message.Type.PRIVATE_MESSAGE, rsmMessageCallback); } This code is fairly similar to the bulletins code.We use the MyOpenSpace. Application object to generate a message and then invoke the wrapper.There is also some app-specific code in this function that determines the ID and name of the challenged user; this ID is sent into the wrapper while the name is used to personalize the message. Adding a person’s name to a message is an old trick that helps the message seem a little less like a form letter. Callback in requestSendMessage The callback for requestSendMessage works the same as requestShareApp . An error could be generated before the modal dialog is shown; otherwise the value 1, 0, or Ϫ1 is returned. 78 Chapter 5 Communication and Viral Features From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg Let’s take a look at one quick example: function rsmMessageCallback(response){ var div = TTT.Tabs.getCurrentContainer().firstChild; if(response && !response.hadError()){ if(0 === response.getData()){ div.innerHTML += "challenge cancelled ."; } else if(1 === response.getData()){ div.innerHTML = "challenge sent!"; } } else{ log("Oops, there was an error, try refreshing the page!"); } } First we check for an error. If one was found, we display an error message asking the user to refresh the page. Most errors that occur with the messaging system are intermittent and can be fixed with a refresh. If there was no error, a simple message is displayed reaffirming the user’s action. Getting Your App Listed on the Friend Updates with opensocial.requestCreateActivity Basics On every user’s MySpace Home page there is a module that displays the user’s Friend Updates.These updates are a feed and might include information like “John added a new photo,”“Mary and John are now friends,” or “Susan installed the Tic-Tac-Toe application.”These updates are ordered by date, and the newest information is always displayed on top. When an app creates an activity, the activity appears in this feed.That makes any app activity a one-to-many message that will appear in the Friend Updates feed for each of the user’s friends.With activities, applications can define numerous custom messages that will appear in a user’s Friend Updates. Activities can be created only from the app’s Canvas surface, but they’re a great way to embed your app into a user’s MySpace experience and promote your application at the same time. Defining opensocial.requestCreateActivity opensocial.requestCreateActivity has the following signature: opensocial.requestCreateActivity = function(activity, priority, opt_callback) This means it’s a function that must include an activity ( opensocial.Activity ), a priority ( opensocial.CreateActivityPriority ) setting for the request, and opt_callback as the function to call once the request has been processed. Getting Your App Listed on the Friend Updates 79 From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg Note At the time of this writing, opensocial.CreateActivityPriority is not being checked or used by MySpace. You’ll notice in the code that follows that we always pass in a value of high ( opensocial.CreateActivityPriority.HIGH ) as opposed to low ( opensocial.CreateActivityPriority.LOW ). If you have opensocial.CreateActivityPriority in your code and MySpace starts making use of it, the behavior of your app may be affected, so it’s good to keep this in mind should your app suddenly start doing something. Let’s take a quick look at how OpenSocial defines the priorities: High: If the activity is of high importance, it is created even if this requires asking the user for permission.This might cause the container to open a user flow that navi- gates away from your gadget. Low: If the activity is of low importance, it is not created if the user has not given permission for the current app to create activities.With this priority, the requestCreateActivity call never opens a user flow. Using the Template System to Create Activities One of the most important elements of creating and raising activities is the template system. In fact, it’s so important that it needs to be explained before we start looking at code. Unlike messages, which are completely defined and passed into the function as static text, activities make use of a custom template system. Basically, you create a template for your activities’ messages and the variables are resolved at runtime.Templates must be used for activities. Every template must have a title containing up to a maximum of 160 visible characters. Each template may also optionally specify a body having up to 260 visible characters. Your message template is based on a text string with some optional variables (which you may occasionally hear referred to as “tokens”) thrown in.These variables are replaced by real data once the activity is raised. A basic activity’s message might look something like this: "Susan installed Tic-Tac-Toe on: ${date}." When the template is run, you’ll specify that ${date} will be replaced with a string containing the current date and time. So, if you give the variable ${date} a value like “September 28, 2010,” the resulting message would read “Susan installed Tic-Tac-Toe on: September 28, 2010.” Data Types In our first example, the ${date} variable was a string. However, you can also specify the data type of a variable.The two currently available data types are Literal and Person. 80 Chapter 5 Communication and Viral Features From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg A Literal data type, used in our first date example, is any string.Your variable is then simply replaced by that straightforward string. A Person data type is slightly more complex. If a variable is defined as a Person data type, the variable is then replaced by a person’s display name and a link to the person’s Profile when it appears in the feed. For example, let’s say we have a template where the variable ${opponent} is of type Person. It might look like this: "You've been bested at Tic-Tac-Toe by ${opponent}." To get this template message to display correctly, you need to pass in the opponent’s user ID. For example, if we pass in the string "6221" (Tom’s ID) for our ${opponent} variable, our message would read “You’ve been bested at Tic-Tac-Toe by Tom.” The word To m would then link to Tom’s Profile. Reserved Variable Names There are a number of variables that are reserved (see Table 5.2), but the most interesting one is ${sender} . This is because ${sender} is actually a required variable in your template title, meaning you’ll be using it a lot. The variable ${sender} is a Person-type variable, which means it’s replaced by the Viewer’s name and Profile link. For example, let’s say we changed our template to read "${sender} raised this event, making ${sender} the Viewer!" If Susan were to raise an event with that variable, the resulting message would read “Susan raised this event, making Susan the Viewer!” Getting Your App Listed on the Friend Updates 81 Table 5.2 Reserved Variable Names Reserved Variable Name Use ${subject} Replaced with a link to the Viewer’s Profile and the Viewer’s display name as the corresponding text ${subject.DisplayName} Replaced by the Viewer’s display name (no link) ${subject.Id} Replaced by the Viewer’s ID ${subject.ProfileUrl} Replaced by the Viewer’s Profile URL ${canvasUrl} Replaced by the app’s Canvas URL ${variable_name.Count} Used when variables are aggregated and where variable_name is the name of a variable used in the template From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg But if her arch-nemesis,Tom, raised the event, the message would read “Tom raised this event, making Tom the Viewer!” In each instance the Viewer’s information is used for the ${sender} variable. Aggregation When a user has a large number of applications, and friends who like applications, the user’s feeds can get crowded with information and updates. Because of this, activity feeds are aggregated. If a user has five friends all playing Tic-Tac-Toe and raising activities for the app, all of those activities are aggregated into a single feed entry for Tic-Tac-Toe. For example, let’s create a new message template and see what would happen when it’s raised multiple times. Let’s start with a new template: "${sender} is playing Tic-Tac-Toe with ${opponent}." In this example we’d want to aggregate the ${opponent} variable (you can learn how to specify aggregated variables by skipping ahead to the section on using the Template Editor). The first time I raise the event, my opponent’s ID is "6221" (Tom, again!).The resulting message reads “Susan is playing Tic-Tac-Toe with Tom.” If Susan raises the event again, this time challenging her friend Matt to a game, the resulting message reads “Susan is playing Tic-Tac-Toe with Tom and Matt.” And if Susan raises the event a third time, but this time challenging Tila Tequila to a battle of Tic-Tac-Toe, the resulting message would read “Susan is playing Tic-Tac-Toe with Tom, Matt, and Tila!” Now that’s a game I would like to see. Notice that not only does the templating sys- tem keep aggregating your message feeds, it also makes them grammatically correct by adding commas and the word and. Body and Media Items We have variables and data types, but there’s more to a message template than that. What about pictures and the message itself? That’s where body and media items come into play. The body is similar to a template’s title, but it’s optional and can hold more charac- ters. If you include a body, it displays on the second line under your specified title. 82 Chapter 5 Communication and Viral Features From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. ptg Media items can be any picture on MySpace that’s accessible to the Viewer. In Chapter 3, Getting Additional MySpace Data, we fetched a list of the Viewer’s photos, displayed them on the page, and allowed the player to select one for a custom board back- ground. If a custom background is selected, it is used as a media item in any raised activity. You’re allowed to include a maximum of three media items in a message template. All will be rendered on the second line of the message. Using the Template Editor to Create Templates Now that you know how templates work, you’re ready to create some new templates for your app.To do this, you’ll use the Template Editor tool found on your My Apps page. Under each application there is a tool entitled Templates (Figure 5.6); click it to be taken to your Templates page (shown in Figure 5.7). Click on Create Template to create new templates for your app.This will take you to the template creation screen. From this screen (Figure 5.8) you can edit existing templates or create a new one. Let’s look at an existing template for our Tic-Tac-Toe application. Getting Your App Listed on the Friend Updates 83 Figure 5.6 Screen shot of My Apps S Templates link Figure 5.7 Screen shot of an existing Templates list From the Library of Lee Bogdanoff Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... www.verypdf.com to remove this watermark From the Library of Lee Bogdanoff 86 Chapter 5 Communication and Viral Features // Create the opensocial. Activity object var activity = opensocial. newActivity(param); // Raise the activity! opensocial. requestCreateActivity(activity, opensocial. CreateActivityPriority.HIGH, raiseActivityCallback); } First, the activity template is defined as "x_and_y_started_game".This... currentGame.customBG.photo; // Parse out the URI var uri = photo.getField(MyOpenSpace.Photo.Field.PHOTO_URI); // Create the opensocial. MediaItem object var media_item = opensocial. newMediaItem("image/jpeg", uri) // Stick it in an array var media_item_array = [ media_item ]; // Insert the array into the parameters param [opensocial. Activity.Field.MEDIA_ITEMS] = media_item_array; } Please purchase PDF Split-Merge on www.verypdf.com... container’s cache implementation *Reprinted from Google (http://code.google.com/apis /opensocial/ articles/makerequest-0.8.html) and used according to terms described in the Creative Commons 2.5 Attribution License (http://creativecommons.org/licenses/by/2.5/) Find the latest specification at www .opensocial. org or http://wiki .opensocial. org/index.php?title=Gadgets.io_(v0.9) Response Structure The response... actual code to raise the event looks like the following: function raiseActivity(){ // Create the parameters var param = {}; // Required template name param [opensocial. Activity.Field.TITLE_ID] = "x_and_y_started_game"; // The actual parameter values param [opensocial. Activity.Field.TEMPLATE_PARAMS] = { "opponent" : currentGame.opponentId, "params" : "{\"from\":\"act\"}" }; // Check if a custom background... necessarily; opensocial. requestPermission to the rescue again! In a method similar to one used in Chapter 3, Getting Additional MySpace Data, where we requested permission to fetch photos, we can request permission here to raise an activity: function raiseActivityCallback(response) { // Check for an error if(response.hadError()){ // Was the error a permission issue? if(response.getErrorCode() === opensocial. ResponseItem.Error.UNAUTHORIZED){... recipient’s Mail Center page; see Figure 5.9 for exactly how it’ll look Tip Notifications use the permission MyOpenSpace.Permission.VIEWER_SEND_ NOTIFICATIONS You may want to use opensocial. hasPermission (followed possibly by opensocial. requestPermission) to check that permission before attempting to send the message See Chapter 3 to learn how to check and request permissions Summary The primary source... use your needs are so specific that you have to write your own services.Whatever your needs, you will likely reach a point where the “out-of-the-box” offerings from OpenSocial on MySpace are just not enough to satisfy your needs.Thankfully, OpenSocial recognizes these needs and provides you with a mechanism or two for communicating with external servers In this chapter we’ll add two different features... the data to pass to the other server Data can be passed to the MySpace container either as an object containing key/value pairs or as an encoded string The OpenSocial specification currently states that data should be only a string, but the MySpace OpenSocial container still honors both the object and the string format Example as an object: { data1 : "test", data2 : 123456 } Example as a string: data1=test&data2=123456... template Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark From the Library of Lee Bogdanoff Getting Your App Listed on the Friend Updates 85 Using opensocial. requestCreateActivity Now that we understand what opensocial. requestCreateActivity looks like and how to construct a template, let’s actually use the function Raising the Event The template we’re using for our activity is... showFeedResults(response.data); } } You will notice that the error handling from a makeRequest call is somewhat different from that of some of the other OpenSocial data calls.The makeRequest call holds its errors in a simple array, whereas the other OpenSocial calls use getter functions to test for errors In that regard, the error handling from a makeRequest call is a little more straightforward.We . param [opensocial. Message.Field.TYPE] = type; param [opensocial. Message.Field.TITLE] = subject; var message = opensocial. newMessage(body, param); opensocial. requestSendMessage(id,. Value of opensocial. Message.Field.Type Send Message opensocial. Message.Type.PRIVATE_MESSAGE Comment opensocial. Message.Type.PUBLIC_MESSAGE Bulletin opensocial. Message.Type.NOTIFICATION