Benefits of Registering Your Flash Widget With Widgetbox

Widgetbox provides the following Flash-specific benefits to widget developers:

• No-paste installation into MySpace and many, many other sites. Flash widgets are supported by more sites than Javascript/HTML widgets because some sites simply don't allow Javascript code to be added.
• MySpace linking. We enable your widget to link out of MySpace. Learn more.
• User configuration of Flash. Allow bloggers and other subscribers to configure your widget. This actually changes the generated <EMBED> tag. Users get a live preview of their changes as they make them.

In addition, Flash developers get everything we offer all widgets, such as:

• Widget Syndication Metrics. Track the spread of your widget across the internet with your own widget analytics dashboard. Learn more.
• Viral adoption. Widgetbox provides a simple, direct mechanism for people that see a widget in the wild to get it for themselves.

Get started! Below are some details about how Flash widgets work in Widgetbox:

The Basics of Flash Registration

When you register a Flash-based widget with Widgetbox, you register the URL to your Flash movie/application (the SWF file). Widgetbox generates an <EMBED> tag each time the widget is viewed.

Widgetbox does not download or otherwise cache the SWF file; the end viewer of the widget downloads it from wherever you specified.

Flash wrapper. Widgetbox wraps your Flash in a Widgetbox wrapper SWF which retrieves the user’s configuration info from Widgetbox every time a someone views the widget, and supplies it to your SWF.

AS2 NOTE:

• While running in a Flash wrapper, you cannot use references to _level0; instead use_root.

Flash 9 Player Requirement Our Flash wrapper is written in ActionScript 3.0 and published for Flash Player 9. End viewers of the widget are required to have Flash Player 9 or later installed. As of January 2008, between 2% and 3% of all Flash Player installations are NOT Flash Player 9.

JavaScript wrapper. When a user chooses to use our JavaScript wrapper instead of the default (the Flash wrapper), the <EMBED> tag is generated by the JavaScript every time a user views the page.

Flash Widget Configuration

Widgetbox lets you graphically create a configuration form for users to customize their copy of your widget, as explained here. Widgetbox supplies this configuration info to the Flash application via the <EMBED> tag.

Here's what the Widget Settings form looks like from a user's perspective:

You, the developer, can control where configuration parameters show up in the <EMBED> tag. These are described in the following sections.

SWF Query String Parameters

By default, Widgetbox config parameters are appended to the URL to the SWF file in standard HTTP query string format.

For example, if you have a movie at http://domain.com/movie.swf and your Widgetbox configuration form has a parameter named ‘username’with a value of ‘Ed’, the movie will load from http://domain.com/movie.swf?username=Ed.

The <EMBED> tag would look like this:

Parameters sent this way can be retrieved with Flash Actionscript by referencing ActionScript’s_root object. So in this
example, the value of _root.username would be ‘Ed’.

If the height and width of your widget are user-configurable, Widgetbox will pass in widget_width and widget_height on the URL querystring.

Plugin Parameters

Widgetbox config parameters that start with "plugin." set Flash plugin parameters.

For example, Flash’s standard “wmode” parameter is used to make a Flash movie transparent.

When you build the Widgetbox configuration form, naming a parameter "plugin.wmode" and giving it a value of "transparent" will set the wmode
parameter in the <EMBED> tag, like this:

Hiding config items from end users

You can hide config elements from end users. This is a screenshot of a hidden Widget Setting called "My Hidden Setting". The name of the hidden param is called my_hidden_setting.

The plugin.scale configuration parameter vs Stage.scaleMode inside your ActionScript

In Flash 6 and above, you can specify the scale mode for your Flash movie. By setting the Stage.scaleMode attribute you tell your widget how it should stretch and grow. When you register a widget with us, if you set this attribute within your Actionscript code, you must also include the widget configuration parameter plugin.scale. This is because our wrapper does not know anything about your code, only what you tell us. In order for your widget to display correctly in our wrapper, we need to know if you have any special scaling mode turned on. (If your widget does not look like it is scaling correctly when installed via our Flash embed code, it may indicate a problem with this setting.)

FlashVars Parameters

Widgetbox config parameters that start with "flashvar." are added to the FlashVars string.

What is FlashVars? The Flash <EMBED> tag supports a FlashVars parameter that is used to send a querystring-encoded set of variables to a Flash movie. For example, if your widget has a parameter "flashvar.param1" and has a value of "xxx" the <EMBED> tag will look like this:

Actionscript 2.0 Users: Your flashvars aren’t accessible via _root

Since Flash widgets on Widgetbox run within a Flash wrapper, referencing _root will NOTreturn your FlashVars. Instead, refer to them by name without the prefix.

For example, a FlashVar that has a parameter name of “siteURL” is not referenced as “_root.siteURL”. Instead, your ActionScript code becomes simply “siteURL”

Default Flash Widget Parameters

When you input the URL to your SWF file in the widget wizard, Widgetbox inspects the SWF and adds parameters (hidden to the user) containing your SWF’s background color, width,height, framerate. These help the Widgetbox Flash wrapper to function (if the stage size or framerate of your widget changes, you will need to update these values to match.)

The default parameters will look something like this:

Code-Free Installation Into MySpace

Widgetbox’s installer sends users to MySpace's Post Content screen:

Alternatively, users can get the MySpace-specific HTML embed code for their widget.

Links in Flash Widgets

How To Avoid Getting Caught by a Popup Blocker

(Update: This is only supported in AS2 widgets)

Adobe's Flash Player Plugin v9 presents some interesting challenges for Flash widget developers when it comes to linking out. When your Flash widget is embeded on a page withallowScriptAccess set, it can affect the behavior of your links. Widgetbox always adds theallowScriptAccess parameter to every subscription of your widget with the value ofsameDomain (to prevent any malicious usage of Javascript.)

Update for AS3 Developers - There appears to be a bug introduced in Flash Player 9.0.0.115 that causes links to be trapped by popup blockers in some browsers. Adobe's bug database has it listed here: http://bugs.adobe.com/jira/browse/SDK-12987. Keep in mind this issue is going to be present with any widget platform that enforces a secure container around flash widgets. (ie. we set the parameter "allowScriptAccess" to "sameDomain" to prevent any JavaScript from executing.) With that in mind, there is a solution that you can use (when not running in Widgetbox) that does require the use of Javascript. If you plan to distribute your widget outside of the Widgetbox platform, you may want to take advantage of the technique described in thisZorked! post.

When your AS2 widget runs in this mode, you need to make sure you do 3 things:

• Any link outs from your widget must target “_blank”.
• The actionscript call that opens the new page (getURL) MUST be called from within the event listener function that handles the user's interaction.
• Use onRelease instead of onPress to capture a user's interaction if it results in a linkout.

How To Make Your Widget’s Links Work In MySpace

MySpace disables all links in Flash files. To make your links useful in MySpace, our wrapper can catch link events and display the following to a user.

This happens automatically when the user installs your widget on MySpace. Everywhere else, the widget appears normally.

Also note that the Get Widget button is embedded in static HTML -- not Flash -- so that it can link directly back to your widget's homepage on Widgetbox.com.

What You’ll Need To Do

You’ll need to do two things to get MySpace linking working:

• In your own SWF file, update any code that generates a link. The code is shown below. It is designed such that your Flash application works whether or not Widgetbox is involved; you can use the same SWF on your own site, or in other widget directories (though won’t link in MySpace) .
• To make the Widgetbox wrap your widget with the MySpace wrapper, you have to add a few parameters to your widget in our widget editor.

Activating MySpace Links in ActionScript 2.0

Example Code

Download the ZIP file containing the working example code for the Echo Test (Flash AS2)example widget.

Initial Setup

Put the following at the top of your Flash file, in global scope so that all parts of your application can access it.

Activating MySpace Links - General Use

This function "openPage" is called where you would normally use getURL().

Activating MySpace Links - From a HTML text link

Any URLs in HTML text links will need to be prefixed with the string "asfunction:openPage,".

Activating MySpace Links in ActionScript 3.0

Example Code

Download the ZIP file containing the working example code for the Echo Test (Flash AS3)example widget.

Initial Setup

Put the following at the top of your Flash file, in global scope so that all parts of your application can access it.

Activating MySpace Links - General Use

This function "openPage" is called where you would normally use navigateToUrl().

Activating MySpace Links - From a HTML text link

Any URLs in HTML text links will need to be prefixed with the string "event:", and a listener needs to be defined to handle the click event.

//Create the prefix and prepend your HTML links with the prefix
var eventPrefix = "event:";
var myTextField = new TextField();
myTextField.html = true;
myTextField.htmlText = "<a href=\"" + eventPrefix + "http://www.widgetbox.com/\">Widgetbox.com</a>";
addChild(myTextField);

//You must define a handler function for Link Events
private function openPageFromLink(event:TextEvent){
    var target = event.text;
    if(wbx_softkey == "true" && wbx_wrapper_channel!= null && wbx_wrapper_channel != ""){
        //setup local connection to activate softkeys
        var sender:LocalConnection = new LocalConnection();
        sender.send(wbx_wrapper_channel, "setSoftKeyURL", target);
    }else{
        navigateToURL(new URLRequest(target), "_blank");
    }
}

//And the textField object must have the TextEvent listener added to it
myTextField.addEventListener(TextEvent.LINK, openPageFromLink);

Final Step: Update Your Widget's Parameters

To make the Widgetbox wrap your widget with the MySpace wrapper, you have to ensure you have a few parameters to your widget in our widget editor.

How to add parameters to a widget:

1. Edit your widget by going to the My Registrations page and clicking 'Edit'. You should now be in the Widget Editor.
2. Go to the Parameters tab.
3. Enter the magic parameters as described below.

These are the parameters your widget needs. They can be of type ”Hidden“ -- they do NOT need to show up in the user's configuration form. Most are actually added automatically by the system when you register the widget, so the only one you should have to deal with is wbx_softkey.

This is what your config screen in the widget editor might look like: