Documentation
On this page you can find detailed information about the click.st Javascript API. This API is designed to serve many different use cases. In the Integration Guide you can learn how to put a share button on your site. The Additional Features section explains more advanced features of the sharing API. And finally, the Action Log section describes an API that can be used for custom event logging.
Integration Guide
Click.st allows users to share your offers via email and social networks, and tracks responses and conversions. In order to get complete information, three integration points must be covered:
- location of the share button,
- the target landing page of a shared link,
- location of conversion.
Button Integration
Click.st provides a default share button with minimal styling. To use this button
you must include the click.st javascript api on your page. Then you call a javascript method
where you would like the button to appear on the page, passing in all the details about
the item you want to share.
<head>
<script type="text/javascript" src="http://click.st/api.js?key=_KEY_">
</head>
...
_KEY_ is a unique identifier provided by us. Now, to
create a button, insert another snippet elsewhere on the page where
you want the button to appear:
<script type="text/javascript">
clickst.button({
/* REQUIRED: An item identifier that is unique within your system */
id: '123',
/* REQUIRED: The URL of link to be shared.
This is where users will land when clicking on a shared link.
We call it the target of the share. */
url: 'http://www.example.com/things/123',
/* REQUIRED: This is a short description of the item. It will appear as
the link text in share channels that support links. It should provide
basic information about the item being shared as well as be enticing. */
summary: 'Check out this marvelous thing!',
/* REQUIRED: A more detailed description of the item */
description: 'This marvelous thing has so many marvelous features.',
/* The /meta/ array provides a number of additional attribute types.
Use as many of these as possible. They allow us to show high quality
information in your shares and help us provide you with
unmatched analytics. */
meta: {
/* REQUIRED: An image of the item, which will appear on
Facebook, etc. */
image: {
href: 'http://www.example.com/images/123.png',
alt: 'A marvelous thing in action'
},
/* A comma-separated list of keywords associated with this item */
keywords: 'marvelous, awesome',
/* A geo tag (at any resolution) */
location: {
address: '123 Fake Lane',
city: 'San Francisco',
state: 'CA',
country: 'United States',
postal_code: '94115',
/* Alternatively or additionally, coordinates may be provided */
lat: 37.73,
lng: -122.46
},
/* A temporal tag */
datetime: 'June 21, 2010'
}
})
</script>
</div>
At a minimum, provide summary, description & image so your shares will look good across all share channels.
Inline buttons
If you'd like inline share buttons instead of the default drop down, use
the clickst.inline_buttons() method instead. For example:
<script type="text/javascript">
clickst.inline_buttons({
id: '123',
url: 'http://www.example.com/things/123',
summary: 'Check out this marvelous thing!',
description: 'This marvelous thing has so many marvelous features.',
meta: {
image: {
href: 'http://www.example.com/images/123.png',
alt: 'A marvelous thing in action'
}
}
})
</script>
</div>
Landing Page (target) Integration
If the location of the share target (the url specified in the call to clickst.button) is different from the location of the button integration, the click.st script must also be loaded here. For example, lets say the button integration above is located at http://www.example.com/list-things. When a user shares item "123", they are sharing the url http://www.example.com/things/123. So in the head of the page located at http://www.example.com/things/123 the following tag must be included to ensure proper response and conversion tracking:
<head>
<script type="text/javascript" src="http://click.st/api.js?key=_KEY_">
</head>
...
Notice that this is the same script include as on the button integration page, and will not penalize you if you stick it in a header include file to be available across the site.
Integration for Conversion Tracking
In order to be as flexible as possible, we provide a simple javascript function to log a conversion. To use it, first include the (by now familiar) click.st script in the head of the page where conversions are tracked. Then call the function clickst.is_converted(ID). Let's look at a couple of scenarios:
Scenario 1: Conversion occurs by visiting a particular page.
In this scenario, do the following:
<head>
<script type="text/javascript" src="http://click.st/api.js?key=_KEY_">
<script type="text/javascript">
clickst.is_converted("123")
</script>
</head>
...
Scenario 2: Conversion occurs by clicking a link.
This scenario can be broken down further depending on what happens when the user clicks the conversion link:
3.2.a) Opens a new page to a new location:
3.2.b) Calls a javascript handler:
<script type="text/javascript">
document.getElementById('the-link').onclick = function (e) {
e.preventDefault()
clickst.is_converted('123')
doAjaxyThing()
}
</script>
Additional Features
There are several other features that provide more flexibility in tracking and integration.
Groups and Multi-Variant Testing
Using the default integration described above, it will only be possible to view analytics across all traffic for your organization. If you'd like to segment traffic you can specify a group and, optionally, a variant when loading the click.st script.
For example:
<head>
<script
type="text/javascript"
src="http://click.st/api.js?key=_KEY_&group=_GROUP_&variant=A">
</head>
...
Sessions and User IDs
It is also possible to pass a user_id parameter if your system has user accounts.
This field has a variety of uses including segmenting analytics, identifying relationships,
and creating a personalized experience.
<head>
<script
type="text/javascript"
src="http://click.st/api.js?key=_KEY_&user_id=_USER_ID_">
</head>
...
Alternatively, you may use the method clickst.login(<string>) after the clickst api is ready. For example:
<head>
<script
type="text/javascript"
src="http://click.st/api.js?key=_KEY_">
<script type="text/javascript">
function clickst_ready()
{
clickst.login(_USER_ID_, function ()
{
// The clickst session object will be updated with any information
// attached to this user id (such as the last referral)
console.log(clickst.session)
})
}
</script>
</head>
...
To clear a user's session so that future actions are logged to a new, anonymous session, use clickst.logout()
Referral Information
If a user landing on your page has arrived via a click.st shared link, it
is possible to retrieve information about the original share that brought
them to your page. Use clickst.get_referral() like so:
clickst.get_referral(function (referral_info)
{
alert('You were referred here by a link on '+referral_info.network)
})
</script>
The referral info object provides several attributes. Some are optional and require you to provide them at share time. Here is the complete list of attributres with example data:
/* The social network the user came from. */
network: 'facebook',
/* The id of the item that was shared. */
item_id: '123abc',
/* The group specified at share time, if any. */
group: 'some-group',
/* The variant specified at share time, if any. */
variant: 'A',
/* The id of the user that created the share, if any. */
user_id: 'FOO'
}
Custom Button Integration
If you have an idea for an integration and the method described above just won't work, there are additional javascript methods that serve almost any case, albeit with a bit more effort.
Load the click.st script as you normally would and then...
// Create your item.
// This method takes the same structure as clickst.button() but it
// returns an object with some useful methods
var my_item = clickst.item({
id: '123',
url: 'http://www.example.com/things/123',
summary: 'Check out this marvelous thing!',
description: 'This marvelous thing has so many marvelous features.'
})
// Here an arbitrary dom element's click handler is set to
// open a share-on-facebook window for the item.
document.getElementById('some-element').onclick = function ()
{
my_item.share('facebook')
}
// When sharing via email, a "trigger" element must be specified.
// The email sharing widget will align with the top left corner
// of this element.
var email_button = document.getElementById('email-button')
email_button.onclick = function ()
{
my_item.share('email', { trigger: email_button })
}
// It's also possible to retrieve a direct share
// URL that users can post anywhere. Retrieving a direct
// URL requires a callback function.
my_item.get_share_url(function (url)
{
document.getElementById('url-field').value = url
})
</script>
Loading api.js Asynchronously
If you wish to load the api.js script somewhere other than the head of the page
you are in luck. When the clickst object is ready, it will look for a function called
clickst_ready to call. All you need to do is put your code that uses clickst
inside this function. Here is an example:
<head>
<title>My Page</title>
</head>
<body>
My Content
<script type="text/javascript">
function clickst_ready()
{
clickst.item(...)
}
</script>
<script type="text/javascript"
src="http://click.st/api.js?key=_KEY_"></script>
</body>
</html>
The Action Log
In addition to the sharing features, the click.st script provides access to our underlying
event logging system. These methods are available from the api.js script
and do not require loading of additional scripts.
A note about implicit data
The following paragraphs describe how to log your own actions. But before you do that it's a good idea to know what information gets logged automatically. Each log record will end up with a number of fields in addition to those you explicitly provide. They are...
- time - The time the action was performed as a UNIX timestamp.
- ip - The IP address of the user that performed the action.
- user_agent - The User-Agent string of the user's browser.
- visitor_id - Algorithmically generated user ID.
- url - The URL of the page where the action was logged.
- referrer - The referring URL, if any.
- tag.site_id - A user ID stored in a 1st party cookie tied to your domain.
- tag.clickst_id - A user ID stored in a 3rd party cookie tied to the click.st domain.
- tag.domain - The domain where the action was performed.
- tag.traffic_source - The source of the referral, if any. This can be one of search, direct, other or click.st.
-
tag.referral - If the user has an active referral it will be present here. This field has the same structure as that returned by
clickst.get_referral()
log(action, tag, [callback])
Use this method to log an action. Note that you must wait for the click.st ready event to fire before logging actions.
- action is the name of the action, for example, "video.play".
-
tag is an object with additional attributes for the action, e.g.,
{ video_id: 'xyz123' }. - callback is a function that takes no arguments. If provided, it will be called when the action has been recorded. This is useful if you want to ensure a record has been logged before performing some other actions that may take the user off the page.
Here is a complete example of logging an action:
function clickst_ready()
{
clickst.log('video.play', { video_id: 'xyz123' })
}
</script>
REST API
The features presented above cover all the uses of the Javascript helpers. These helpers are built on top of a lower-level and more expansive API. For detailed information about API methods and using the API visit the API documentation.
