Table of Contents
Viral Settings Tab
The Viral Settings tab is where you customize your friend invitations and News Feed stories.
The custom friend invites and News Feed stories that you set up in the Viral Settings Tab will make use of the newsfeed special values described below.
News Feed Special Values
Widgetbox offers various special values for use within custom invitations and News Feed stories. The syntax: ${some.value}. The values:
| Parameter | Meaning |
|---|---|
fbapp.addLink |
URL to the "Add This App" page. |
fbapp.canvasPage |
URL to canvas page, where widget is displayed. |
fbapp.managePage |
URL of manage page, where profile owner can edit widget. |
fbapp.profilePage |
URL to the current profile page. |
fbapp.apiKey |
The app's API key. |
fbapp.loggedInUser |
The ID of the logged in Facebook user. |
fbapp.appOwnerId |
The ID of the owner of the current profile. |
fbapp.thumbnail |
URL of the base widget's thumbnail. |
fbapp.randomTermOfEndearment |
Chooses randomly from a set of lighthearted, informal terms of endearment. Examples: dude, bro, homie. |
fbapp.randomTermMeaningConfigured |
Chooses randomly from a set of lighthearted, informal terms synonymous with "configured". Examples: pimped out, tricked out, polished up. |
widget.id |
The internal Widgetbox ID of the Facebook application. |
widget.name |
The name of the application as set in Widgetbox. |
Example:
Say you want a News Feed story saying "It rocks. Get it now!". And the "Get it now!" links to the app's installation page in Facebook. It would look like this:
Notifications API
Widgetbox provides a Javascript and Flash API that you can use inside your widget to:- Send stories to the Facebook News Feed.
- Send events to your app's profile box.
This API can be used in your existing Flash and HTML/Javascript widgets. It will not break the widget when the widget is used outside of Facebook.
| Function | Description |
|---|---|
WbxAppWidget.getFbSigUser |
Get the id of the logged in user. Inputs: None Returns: The id of the logged in user viewing the app. |
WbxAppWidget.getAppOwnerId |
Get the id of the app owner. Inputs: None Returns: The id of the owner of the app being viewed. |
WbxAppWidget.goToAppOwnerProfile |
Call this to cause the user's browser to navigate to the owner's profile page. Inputs: None Returns: Nothing |
WbxAppWidget.updateCallback |
Define this function to execute when the call to update() returns. Inputs: obj:XMLHttpResponse Returns: Nothing |
WbxAppWidget.update |
Called when you want to process the following actions/updates. This is generally the last call in your update code. Inputs: None Returns: Nothing |
WbxAppWidget.sendActionToProfile |
Updates the users profile with FBML. Inputs: headerFBML:String - Displays above all the actions. footerFBML:String - Displays below all the actions. actionFBML:String - FBML for one action to be added to the profile. maxShown:int - The max number of actions displayed on the profile? Returns: Nothing |
WbxAppWidget.sendActionToFeed |
Updates the user's minifeed with FBML. Inputs: feedTitleFBML:String - FBML string for the title of the feed entry. feedContentFBML:String - FBML string for the content of the feed entry. feedImages:String - Up to 4 URLs to images (comma separated) Facebook automatically resizes images to 75px/75px Returns: Nothing |
WbxAppWidget.updateAnnouncementRef |
Updates the space atop of your widget with an annoucement. Inputs: fbml:String - FBML defining the announcement to post Returns: Nothing |
News Feed Example:
If you have a game widget, you could send a News Feed story after the game is played:
Profile Box Example:
You can also post events to your app's profile:
API Limitations:
Flash widgets can only use this API on the canvas page. This is because Facebook doesn't allow Flash on the profile to access Javascript.
Hello World Example The following example is of a Magic 8 Ball Widget. When clicked, it:
- Displays an answer to the user.
- Sends a Facebook News Feed story about the answer.
- Modifies the app's profilebox to show that the user got an answer.
<!-- This Magic 8 Ball is just a DIV that says "Click me!" -->
<div id="eightball" onClick="askQuestion()">Click for answer.</div>
<script type="text/javascript">
//
// Display answer to question
//
function askQuestion() {
// The answers
var answers = new Array(3)
answers[0] = "Yes.";
answers[1] = "No.";
answers[2] = "Maybe.";
// Pick an answer
var answerIndex = Math.round(Math.random() * (answers.length -1));
var answer = answers[answerIndex];
// Display answer to user
document.getElementById("eightball").innerHTML = answer;
// Send notifications to Facebook
sendFacebookNotifications(answer);
}
//
// Send notifications to Facebook
//
function sendFacebookNotifications(answer) {
var debug = true;
try {
//
// Outputs debugging on a successful sending of the News Feed.
//
if (debug) {
parent.WbxAppWidget.updateCallback = function(obj) {
alert("done: " + obj.responseText);
}
}
//
// Create action for the Facebook News Feed
// The feed will read something like: "Pam has been answered: "Yes."
// Get your own answer!"
//
var feedTitle = "has been answered: \"" + answer + "\"";
var feedBody = "<strong>Get your answer!</strong>";
var feedImages = "http://domain.com/someImage.png";
parent.WbxAppWidget.sendActionToFeed(feedTitle, feedBody, feedImages);
//
// Create action for the profile owner's profilebox
// The profilebox will now contain something like:
// [Pam's image] Pam has been answered: "Yes!"
//
var uid = parent.WbxAppWidget.getFbSigUser(); // ID of the current user
var fbml += "<fb:profile-pic uid=\"" + uid + "\"/>";
fbml += "<fb:name uid=\""+ uid +"\" />";
fbml += " has been answered: " + answer;
// The max # actions to display in the profilebox.
// After the widget sends 5 actions, the oldest is dropped
var maxActions = 5;
// Displays above all the actions
var header = "<hr />";
// Displays below all the actions
var footer = "";
parent.WbxAppWidget.sendActionToProfile(header, footer, fbml, maxActions);
//
// Actually send both actions
//
parent.WbxAppWidget.update();
} catch (e) {
if (debug) {
alert("Error sending Facebook notification: " + e);
}
}
}
</script>
Example of Using API in Flash
The notifications API can be used in a Flash widget via ActionScript. Here's a sample widget that puts captions on photos:
Useful Facebook Tools
Some useful Facebook tools for working with newsfeed stories:Feed Preview Console Facebook's console for testing your feeds.
Feed API Doc Facebook's API documentation for publishActionOfUser, the event that Widgetbox sends out on application installs and edits.
Useful Newsfeed Button Images
One useful technique for newsfeed stories is to use a button image. Example: