clearspring - the widget network.

Contents

• Overview
• Using API Services
  • JavaScript
  • ActionScript 2
  • ActionScript 3
• Example Conventions
• API Reference

 

Overview

Clearspring provides a number of APIs that you can use from within your widget. These APIs allow you to do things like invoke our viral sharing services programmatically, get information on the viewer of your widget, access properties of the widget and where it is located, and more.

The APIs are divided into five logical categories, each with its own properties and methods:

• Context
• Menu
• Placement
  
• Share
• Track
• Widget

Functions and constants in each category are accessed using the category namespace, as illustrated in examples throughout this document.

Container Versus Kernel

Differences in Service Access

All services are available both in our regular widget container and a standalone services kernel, for applications where our widget container is unsuitable (for example, where an application must be first to load, or not dependent on third-party services for display). The Clearspring Kernel is a library loader that pulls in all our services as needed, from tracking to run-time context to viral sharing. When you wrap a widget on our platform, all services are automatically available at run-time. To use the kernel, you must either

• register it using our console
• use our dynamic registration API

and explicitly load it in your widget's source code.

All the kernel method signatures are the same as in our container API. However, since it's loaded at runtime, slightly different means of access are required.

Differences in Tracking in Kernel Mode

Since we're not first to load, we're unable to reliably determine the URL of a widget placement. If you'd like to have domain information in your Clearspring reports, you must pass us the HTTP referrer your widget server receives by appending it, urlencoded, to the kernel URL as the querystring _cs_pur=[URL]. Note that the URL must be valid; i.e., http://example.com is valid, but example.com will be ignored.

Examples:

_cs_pur=http%3Aclearspring.com
_cs_pur=http%3Aexample.com/test/one?foo=a&bar=b

Moreover, in the simplest case, all your placements will share the same ID, and therefore no parentage or spread reports will be available. To support these more advanced tracking features in kernel mode, our share services support templating of content with variables we're uniquely positioned to know--like placement ID--as well as placement-specific data provided by you. That way, whether your widget is Flash, JavaScript or an HTML hybrid, you'll be able to include our kernel with a unique placement ID, ensuring the same level of detail in your reports as with the container, and to persist placement-specific metadata in our system.

Kernels Within Containers

Loading a kernel within a containerized widget is not recommended, nor supported.

Dynamic Kernel Registration

For your convenience, you can dynamically register a kernel at run-time--meaning you don't have to set up a kernel instance in our console at all--using this URL scheme:

http://widgets.clearspring.com/k/user-id/language/widget-name

• user-id is your Clearspring user ID, available from the Settings page when logged in to our site. For security purposes, we strongly suggest you don't expose your user ID in production code.
• language is the desired kernel language. Possible values are as2, as3, and js, for ActionScript 2, ActionScript 3, and JavaScript, respectively.
• widget-name is your widget's name for internal use; it'll show up in our console. Since this is a URL, it must be URL-encoded (e.g., 'my%20widget%20name' instead of 'my widget name').

Dynamic registration of kernels is useful for testing, since you don't have to use our web interface at all. It's also useful if you have to quickly create many kernels--note, though, that we limit you to 50 dynamically-registered kernels per day.

 

Using API Services

The APIs are made available to your widget in a variety of ways, depending on the language you're developing in.

Flash Widgets (ActionScript 2)

In Container

When loaded by our container, the in-widget API services are loaded into an object stored on _level0 and accessible to the domain of your contained widget. (Note that content from other domains will not be granted access.) Function calls take the following form:

_level0.cs.category.method();

This general access method can be used to call any method in the function list from within your Flash application. For example, to call the method track.event() from within the Actionscript 2 container, you would use code like this:

_level0.cs.track.event(eventCode);

N.B. Due to Flash player object serialization bug, you must allow access to your movie from our domains:

System.security.allowDomain("bin.clearspring.com");
System.security.allowDomain("widgets.clearspring.com");

If you cannot grant us access, you will not be able to use any API that takes a native object (e.g., {foo: 1, bar: 2}) as an argument. All others will function normally.

With Kernel

After loading our AS2 kernel, services may be called as when in the container, just with a different object root. Because externally libraries used by our kernel must be loaded before all methods are available, you must provide an onLoad callback so your application knows when we're fully initialized. onLoad is relative to your _root, so make sure to attach a reference there if you're not developing a timeline-based movie; if desired, you can pass a fully-qualified path to a callback function defined off root. (For example, if onLoad was "foo.bar.onLoad", we'd call _root.foo.bar.onLoad().) To use the callback, make sure you allow access to your SWF from our CDN domain bin.clearspring.com. We call your onLoad function with a reference to our library as a sole argument.

Kernel URL:
http://widgets.clearspring.com/o/your-widget-id/-/-TRK/1/lib.as2.swf?onLoad=onLoad

Example:

System.security.allowDomain("bin.clearspring.com");
System.security.allowDomain("widgets.clearspring.com");

function onLibLoad(lib:MovieClip)
{
	lib.track.event('kernelLoaded');
}
var wid:String = "47173dfefb2b18e8";
var kernel:String = "http://widgets.clearspring.com/o/"+wid+"/-/-TRK/1/lib.as2.swf?onLoad=onLibLoad";

var api:MovieClip = _root.createEmptyMovieClip("clearspring", _root.getNextHighestDepth());
var mcl:MovieClipLoader = new MovieClipLoader();
mcl.loadClip(kernel, api);

Flash/Flex Widgets (ActionScript 3)

As in AS2, we register all our services on objects accessible to you at run-time.

In Container

Your application can access our service classes at runtime without having to do any fancy loading; they're defined as static objects on the root of our container.

Example:

package test 
{
        import flash.display.*;
        import flash.events.*;
        import flash.system.*;
        import flash.utils.*;
        import flash.net.*;

	public class ContainerTest extends Sprite
	{
		private var _api:Object;

		public function ContainerTest()
		{
			Security.allowDomain("bin.clearspring.com");
			Security.allowDomain("widgets.clearspring.com");

			// Services not necessarily initialized until the load COMPLETE event fires
			this.loaderInfo.addEventListener(flash.events.Event.COMPLETE, initHandler);
		}

		public function initHandler(e:Event)
		{
			// Grab a reference to the root of the Clearspring container
			_api = this.root.loaderInfo.loader.root; 
			trace('User has viewed me ' + _api.context.user.WIDGET_VIEWS + ' times');
		}
	}
}	

When accessing our service classes at runtime from your widget you need to add the listener event to be notified when the container is fully initialized. †When debugging locally, outside the container, this event will not trigger and cause other events to fails. †To prevent event handlers from failing and to help in debugging your widget locally, you should do a simple check for the load. †The following snippet, added to the document class, will check that the container load the listener event. †If the check fails the listener is not added and all other listeners will continue to operate.

try {
    // Services not necessarily initialized until the load COMPLETE event fires
	this.loaderInfo.addEventListener(flash.events.Event.COMPLETE, initHandler);
}
catch(e) {
  trace("WARNING: Not able to add loader event listener. Normal if not running in the Clearspring container.");
}

 

With Kernel

When using the Clearspring API in kernel mode, you must load our kernel into your application. After loading, our services are available much like in container mode.

URL: http://widgets.clearspring.com/o/your-widget-id/-/-TRK/1/lib.v3.as3.swf

This example shows how to load the kernel dynamically, and then, once loaded, how to pull data from the in-widget context service and show the service menu.

package {
        import flash.display.*;
        import flash.events.*;
        import flash.system.*;
        import flash.utils.*;
        import flash.net.*;

	public class MyApiTest extends Sprite
	{
		private static const wid:String = 'my-widget-id';
		private var _api:Object;

		public function MyApiTest()
		{
			var kernelUrl:String = 'http://widgets.clearspring.com/o/'+wid+
					       '/-/-TRK/1/lib.as3.swf';
			var url:URLRequest = new URLRequest(kernelUrl);

			var api:Loader = new Loader();
            api.addEventListener('on_ready', this.onApiLoad);
			addChild(api);

			// Load Clearspring kernel into our security domain
			api.load(url, new LoaderContext(false, ApplicationDomain.currentDomain,
				      SecurityDomain.currentDomain));
		}

		private function onApiLoad(e:Event):void 
		{
			// Grab API reference
			_api = e.target.loader.content;

			trace('User has viewed me ' + _api.context.user.WIDGET_VIEWS + ' times');

			// Show service menu
			_api.menu.show();
		}
	}
}

HTML/JavaScript Widgets

In Container

Our widget container writes your widgets into an iframe, and therefore API functions are not available. You can, however, use the kernel mode described below.

With Kernel

Whether your widget is pure JavaScript or a web page widget, you can include our services library by using this basic script tag, customized for your widget ID.

<script src="http://widgets.clearspring.com/o/your-widget-id/-/-TRK/1/lib.js" 
type="text/javascript"></script>

Because a key component of the library is written in Flash, rather than poll for availability, you may specify a callback that fires when the library has completed loading.

Callback format: _cs_onload=function.name

The function is called with a handle to the actual library JavaScript object. Much like _level0.cs in the AS2 container, all service groups are registered at this root.

Example:

<script type="text/javascript">
function onLibLoad(library)
{
        alert('library loaded; user country: ' + library.context.user.geo.getCountry());
}
</script>
<script type="text/javascript"
src="http://widgets.clearspring.com/o/47173dfefb2b18e8/-/-TRK/1/lib.js?_cs_onload=onLibLoad">
</script>

What's that /-TRK/1?

Normally, when the widget type is overridden by appending it to one of our /o URLs, we assume it's for testing and discard tracking data. /-TRK/1 forces all tracking data to be counted, regardless of whether the widget type is being overridden.

If for any reason you need to turn off tracking, simply change /-TRK/1 to /-TRK/0.

Summary of Access Methods

Here's how you'd use the context service in all available environments. (The same format is used for all other service groups.)

Platform	Method
JS Container	Not available... yet
JS Kernel	(lib object).context
AS2 Container	_level0.cs.context
AS2 Kernel	(load point).context
AS3 Container	(this.root.loaderInfo.loader.root).context
AS3 Kernel	(e.target.loader.content).context;