Supporting Clearspring widgets on your site

What is this?

This guide provides companies that want to provide Clearspring widgets to their users and want to be on the Clearspring Launchpad menu an overview on how to integrate with the Clearspring platform. This will give users of your site the ability to grab widgets and post them to your site with just a few clicks.

For example, Alice uses your destination site. As she is surfing the net she comes across a widget she would like to add to her destination page. When she selects the widgets "get & share" button you destination site will be listed. Alice selects your destination and the widget will be placed on her page at your destination.

The integration to the Clearspring Platform is accomplished using URL Exchange, which is described in detail in this guide.

Who's this for?

This guide is primarily for developers who are tasked with the integration of the Clearspring platform into their site.

Introduction

URL Exchange is a process that facilitates integration between different Web sites allowing both parties maximum flexibility in implementation without compromising user security. The process requires both sides to create a minimal contract for communication to support integration. In this guide the process of integrating content, widgets, from the Clearspring platform into a 3rd-party Web site is described.

How it works

URL Exchange is based on the premise that the content-providing site (Clearspring) will provide the content-receiving site (integrating site) the URL to the desired content (called Content URL). The content URL is supplied as a parameter to a URL provided by the content receiving site (called Target URL)

Integration URL Bar

When the integrating site makes an HTTP request to the Content URL the content is returned. Clearspring provides the content that represents a widget as a well-defined XML document. The integrating site consumes this XML document.

The XML document schema is agreed upon as part of the contract for communications. By leveraging the nature of XML both Clearspring and the integrating site have maximum flexibility. Both Clearspring and the integrating site can update their respective implementations without impacting user experience on the other site.

	Step 1		Step 2
	Clearspring sharing tools cause the user's browser to send an HTTP request to Target URL provided by integrating site.		Integrating site receives the HTTP request from the user's browser with the Content URL provided by Clearspring, to retrieve the widget data as an agreed upon parameter.

	Step 3		Step 4
	3. Integrating site sends an HTTP request to the Content URL provided by Clearspring.		4. Clearspring serves a valid XML document that represents the content to the integrating site.

Implementation Details

When integrating a site that requires user authentication prior to successful posting of content then the site should direct the user to a login page, and after successful login call the Content URL to retrieve the content that is being posted.

The integrating site will parse the XML document provided by Clearspring and add the widget to the Web site.

The Content URL will vary for each widget though the requirement is simply that it is a publicly accessible URL.

XML Content Specification

The XML document specification is a subset of the Google Gadget specification (see here for more details). This specification allows for the maximum flexibility from both parties. There may be additional information specified in the XML at a future time, but these fields and attributes be filled out for every widget.

Sample XML:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
 <ModulePrefs title="Sample Widget Title"
    title_url="http://www.clearspring.com/widgets/33388380/"
    author="Jane Smith"
    author_email="xxx@clearspring.com"
    author_affiliation="Sample Widget Creator Company"
    description="Sample Widget Description"
    screenshot="http://www.clearspring.com/img/33388380/full.png"
    thumbnail="http://www.clearspring.com/img/33388380/small.png"
    provider="Clearspring"
    providerWidgetId=33388380
    providerUniqueId=33388380_11123830
    category="Miscellaneous"/>
 <Content><![CDATA[
   <object type="application/x-shockwave-flash"
    data="http://widgets.clearspring.com/o/33388380/11123830"
    id="W3338838011123830" height="324" width="404"></object>]]>
 </Content>
</Module>

Next Steps for Integrating Site

The following steps should be followed to start the process of integrating your Web site with Clearspring:

Provide Clearspring with the Target URL, for example: “http://www.integratingsite.com/add_widget.php?url=”
Provide your logo graphics to Clearspring. The preferred logo format is Adobe Illustrator .ai file or Enhanced Postscript .eps file. This logo will be used in the Clearspring Sharing Menu to initiate sending content to the your site.
Engage Clearspring with these two pieces of information. We will work with you on scheduling the remainder of the work involved.
Develop support, in your Web site, for accepting specified XML document (see above) returned by Content URL.

Questions / Comments / Concerns

We welcome and encourage all feedback in this process.

Please feel free to reach us via our contact form.

clearspring - the widget network.

Platform