clearspring - the widget network.

Introduction

Launchpad Advanced is an embedded viral sharing solution built for widget creators who want full control and customization of the sharing experience.  The power of Launchpad Advanced‘s comprehensive API and code library provides the widget creator the capabilities to build into their widgets viral sharing, runtime contextual intelligence and tracking.

This guide discusses how to jumpstart development with Clearspring Launchpad Advanced.  It will lead the reader through the process of adding the sharing menu to a simple Adobe Flash widget.

Audience for this Guide

This guide is for widget creators and developers who are tasked with implementing Clearspring Launchpad Advanced with their existing Adobe Flash widget.

This guide assumes that the reader is familiar with Adobe Flash development, specifically Adobe Action Script 3.  If you are not familiar with Action Script 3 (AS3) please review the Adobe documentation at: http://livedocs.adobe.com/flash/9.0/main/

Prerequisites

To run the sample application, you must have an account with Clearspring.  To get your account simply register at the Clearspring Web site at: http://www.clearspring.com/register

In addition to the Clearspring account you must have Adobe Flash CS3 installed.  You can obtain a demonstration copy at Adobe’s Web site: https://www.adobe.com/cfusion/tdrc/index.cfm?promoid=BONQS&product=flash

Resources

You can download the sample Hello World widget used in this guide here.

Full description of all the available Launchpad Advanced APIs can be found at: http://www.clearspring.com/docs/tech/apis/in-widget.  If you need some assistance check out the Clearspring Forum at: http://www.clearspring.com/forum/

Adding the Sharing Menu

Launchpad Advanced provides capabilities to add viral sharing and tracking to you widget while giving you full customization of the widget.  In this section we will be adding the Sharing Menu to a simple “Hello World” widget.  We will use the Clearspring console to generate a new Widget ID, generate the code to add the Sharing Menu and finally share the widget.

Lets just get started.

Hello World Sample

The Hello World widget it a simple Flash application that has a button that when clicked prints “Hello World!”.   The widget has a second button, “Grab Me”, that we will use to launch the Clearspring Sharing Menu.

Generating the Widget ID

Each widget has a unique widget ID, a WID, which is used to distinguish the widget from others and for tracking widget activity.  One method for generating a WID is to register the widget using the Clearspring console.

Log into the Clearspring console.  Next click the “Add Widget” button in the upper right hand corner of the console.

To register a custom widget scroll down the add widget page to the Launchpad Advanced section, then click “Go”

Next we will define some parameters that will be used to generate the WID and the stub code we will use within the widget.  The first step is to provide a name for the widget.  The name is used in the console.  Here we will simply use “HelloWorld” as the widget name.

The next step allows for selecting the Launchpad Advanced libraries to include.  We will keep this simple and accept the default, all checked.

Next we will need to enter the Shared Content Template. This is the data that will be shared when a user grabs your widget. Here we are going to use a simple template, the embed tag of the widget we are creating. To learn more about Shared Content Templates please check out http://www.clearspring.com/docs/tech/apis/in-widget/share#sharetemplating.

In this step you will also need to set the actual stage width and height of the widget. For this example we will be using 300x250.

Once you have complete these three steps simply press the “Generate Code” button. The process of generating the code will register the widget with the Clearspring Platform and generate a WID.

In this guide we will be using AS3, so select the “Flash (AS3)” tab and press the “Copy” button. This will place the code onto your clipboard, which we will use in the next section.

Adding the Sharing Menu

Now that we have generated the Clearspring code we need to begin integrating it into the HelloWorld widget.  The widget is a simple single .fla file.  The Clearspring AS3 code leverages the “package” capabilities of AS3, so we will add the generated code into its own package file. 

With Flash open with the HelloWorld widget, we will create a new ActionScript file.  Select File | New and choose ActionScript File from the New Document selector.  Paste the generated code from the Clearspring console into this new file and save the file as “csGrabMe.as”.

After creating the new package file, we want to make some updates and additions. The generate code provide insight into a number of API features, but in this document we will only be concerned with displaying the Share Menu in the widget.

First we will want to replace the class name and constructor from “MyApiTest” to “csGrabMe”. The class name and the file name are required to be the same in AS3. We’re doing this simply to associate this package to the button, which you will see later.

The generated code will automatically display the Share Menu when the API is loaded. In this guide we will show you how to associate the Share Menu with a “Grab Me” button. Before we add a function to display the menu we need to comment out the show.menu method call in the generated code. In the onApiLoad method locate the show.menu method and add two slashes, //, at the beginning of that line to comment out this method call.

Next we will create a new private function call “openMenu” in the csGrabMe class. This function will simply call the Launchpad Advanced show menu function, which will display the Sharing Menu, when a user presses the “Grab Me” button. The menu.show method allows for two parameters to be set, which we will use. The first parameter is an empty string, as we want all values of the Sharing Menu, and the second is the x and y coordinates where we want the Sharing Menu to be displayed on the widget.

Now that we have the function defined to open the menu we need to associate this function with a user mouse click.  In the constructor, “csGrabMe, we will add a mouse click event listener, with a call back to the “openMenu” function you have created.

This completes our changes to the generated code.  Your code should look like the following (note that in your code the value of WID, on line 10, will be an alphanumeric string unique to your implementation of this widget):

Now that we have created our class to launch the Sharing Menu we will need to link this to the “Grab Me” button in the widget.  Select the “csHelloWorld.fla” tab in Flash application.  Open the Library, if it is not already open and select the “GrabMe” library item.  Control-click (on Mac) or right-click (on Windows) to display the context menu and select Linkage.

In the Linkage Properties dialog box check “Export for ActionScript”.  Set the Base Class to the class we just created, “csGrabMe”.  Set the Class name to GrabMe and press OK.  A warning message maybe display, “A definition for this class…”, just click OK to continue.  Note that the “csHelloWorld.fla” and the “csGrabMe.as” files must be located in the same folder.

At this point you have completed the integration of the Clearspring Sharing Menu into the widget.  All we have to do now is test the widget.

Testing the Sharing Menu

Now that we have completed the integration of the Clearspring Sharing Menu we need to verify all is working.  From the Flash menu select Control | Test Movie.  This will build and launch the movie.  If all was done correctly when you click the “Grab Me” the menu will not show up. 

The reason for this is that the Clearspring generate code adds security domains to the loader, which is needed to communicate with the platform, however locally executed Flash applications, cannot use the security domain properties in this configuration.  To resolve the issue post the csHelloWorld.swf file to your Web server.  Once posted, launch the page with the widget and click the “Grab Me” button will display the Sharing Menu. 

If you select a social network or other service, which you have an account, you can post the widget to that service.  Give it a try.

Questions / Comments / Concerns

We welcome and encourage all feedback for the Clearspring products and documentation.

Please feel free to contact us.