clearspring - the widget network.

Platform Services Developers About Us Sign In Create Account

Platform

You are here: Docs → Technical Documentation → Clearspring APIs → Widget Placement API
 

Widget Placement API

Note: This call is deprecated, please use the getCode call in the Platform API to generate placements.

The URL endpoint for this HTTP API is located at: 
https://api.clearspring.com/current/add/tag/post
This call generates and returns a block of code that can be used to place a widget anywhere on the web. The call will actually generate a new Placement, with the correct configuration, in the Clearspring platform. Refer back to the WID/PID overview and configuration discussion for details on what Placements are and why they matter. Also note that there are a variety of other options as well for seeding your widget.

The call requires your standard API key, widget ID, parent placement ID, and (optionally) a code indicating which type of tag to return. The width and height of the returned widget are pulled directly from our registry.

You should invoke the API over HTTPS, to protect your API key.

Parameter Details

Name Type Notes Required?

key

string

your valid Clearspring API key

yes

widgetId

string

 The widget ID of widget to generate the code for

yes

placementId

string

Placement ID to use as the parent of the new placement (if idOverride is NOT set) (more)

yes
idOverride string The placement ID of the widget to generate the code for (this does not create a new placement) no
hostname string Host name to server the widget from (as opposed to widgets.clearspring.com). This should ONLY bed used if the widget has a CNAME assosciated. no
useWrapper boolean (true or false) surround the widget code with the values of the HTML Header/Footer no
width number width of the new placement no
height number height of the new placement no

vars

key-value pairs

URL encoded configuration parameters (e.g., foo%3D1%26bar%3D2) that are used only if flashvars is empty/null (read more)

no
email string teh email address of the owner of the placement - used for configurable widget no

tagType*

enum

0: object, 2: hybrid (embed inside object)

no--default is object

* Note that tagType is only meaningful for Flash widgets. JavaScript widgets always get <script> tags.

Returns

Success Failure

HTML snippet

Error code

Error codes

Value Meaning

error:1

Invalid request -- invalid widget ID, some required field was omitted, or improperly formatted
error:7

invalid email address for placement owner

Calling the API

The parameters must be sent via a standard POST request, with variables form-encoded.

Example:

POST to https://api.clearspring.com/current/add/tag/post with the appropriate form-encoded arguments

returns...

<embed allowScriptAccess="always" allowNetworking="all"
	src="http://widgets.clearspring.com/o/464caeaa084ec44"
	width="400" height="300" align="center" quality="high" wmode="transparent"
	id="W464caeaa084ec44"
	pluginspage="http://www.macromedia.com/go/getflashplayer" 
	type="application/x-shockwave-flash">
</embed> 
In this example, notice that the vars argument does not appear in the output code block. This goes back to the fundamental purpose of the Placement system -- configuration data is managed in the server rather than in the code embedded across the web.

When Would I Use This?

This API is specifically useful if you want to generate code blocks to pass back to end users or other systems that will be placing widgets in pages. This is essentially a programmatic way to get the code that you could also get by clicking on any of the share services from the widget itself, or from the Widget Homepage. Note that you should NOT call the API to get code just to render it on your own site, as that will generate a new placement every time your page is rendered, which will give you inaccurate analytics.

Understanding the Placement ID Parameter

Recall that in the Clearspring platform, all Placements are tied to Parent Placements (identified by so-called PPIDs). That is, for any given placement, it is possible to see which other Placement was the original viral source. This system allows viral distribution from user to user across the web to be tracked and monitored.

You need to specify a Placement ID in this call, in order to track all placements across the web that derived from the particular place you're giving the user this code. By specifying a PID, the generated placement will treat that as its parent Placement. By doing this, you will be able to get analytics on the viral spread from this initial location.

For the actual PID, you'll need to follow a few simple rules. Check out this core topic for more information on the form of PIDs.

If you want to associate these new placements with a Placement that you put somewhere manually using embed code from the widget itself, you can get that placement's ID by looking at it's URL and understanding the widget URL format.

Specifying Configuration Parameters

The ability to pass specific configuration parameters to this call is important -- this is how you configure your new Placement. Note that the paramters must be properly URL-encoded, and that the overall value of this API parameter must be URL-encoded as well.

The argument should therefore be of the general form:

urlencode(name=urlencode(val)&name=urlencode(val))
This is critical in cases in which, as often happens, the configuration values are things like URLs.

 

Hey, if you've gotten this far, you're officially a Clearspring Widget Ninja! Let us know in the Forums if you need any help.

Overview
Docs
Forum