API Documentation

hannah
posted this on November 9, 2011, 9:40 AM

The VigLink affiliation service can be accessed directly through a REST API or managed for you with our JavaScript Library.

JavaScript

The recommended VigLink installation snippet includes our JavaScript library on your page. Once included, the library handles affiliation of external links automatically. Want a little more control? Tweak the options or use its JavaScript API.

Functions

vglnk.click(URL[, target])

Redirect to URL, affiliating it if appropriate. Calls to vglnk.click() are counted as "clicks" in your VigLink analytics. target is optional (it defaults to _self) and can be any target supported by the standard window.open().

vglnk.link(link)

Enable click tracking and affiliation for a link. This is done automatically for all external links in the DOM when the library loads, but not for links added later. If you're adding links dynamically and want them to pass through VigLink, pass each one to vglnk.link().

Options

Options are set as properties of a global vglnk object. The recommended installation snippet sets api_url and key for you. Most users will not need to modify those values.

Options are only read during initialization. For that reason they must be set prior to including the library, as in the recommended snippet.

key

Your VigLink API key. required; string

api_url

The base URL for REST API calls. optional; string; default: the URL from which the library was loaded (probably "//api.viglink.com/api")

cuid

Sets a cuid for use in click requests. optional; string; default: ""

enabled

Enable the library. false means that the library will return immediately during initialization. No communication with the VigLink REST API server will occur. When disabled, functions like vglnk.click() will continue to work, but in a failsafe mode. (In the case of vglnk.click() it will still redirect but will not affiliate.) optional; boolean; default: true

reaffiliate

By default, VigLink will not modify links which are already affiliated. If you'd like to force re-affiliation for all such links, you can make that change in your account settings. To force re-affiliation for a single page, set vglnk.reaffiliate to true. optional; boolean; default: false

Markup

rel="norewrite"

When a link's rel attribute includes "norewrite", that link will not be affected in any way by VigLink. Clicks will not be counted, and the link will not be affiliated. <a href="http://example.com" rel="norewrite">VigLink ignores this link</a>

REST

VigLink provides a basic HTTP API for URL affiliation. Requests are made via an HTTP GET in the form of http://api.viglink.com/api/<method>[?<parameters>].

The REST API is not available without authorization. If you would like to use the REST API, please send us an email. Include your API key (found on the account page) and a brief description of how you will use the API. We'll respond within 48 hours.

Click Method

In addition to affiliating an unaffiliated URL, the click method records the click event for use in analytics. For this reason, an application should call click every time a user is about to follow an outbound link, even if the application has cached the response from a prior request.

If you have legitimate reason not to pass loc please contact us so we can make special arrangements.

out

The URL to affiliate. If the URL cannot be affiliated, the original URL is echoed in the response. The response format is governed by the format parameter. required

cuid

An ID of your choosing that identifies the clicker. The cuid should not contain personally identifiable information. Use of this parameter permits VigLink to report click traffic back to you on a per-user basis.optional; up to 32 alphanumeric characters; case sensitive

The name of the JavaScript callback to use in a jsonp response. This parameter is ignored unless format is "jsonp". optional; default: vl_cB

reaf

By default, VigLink will not modify links which are already affiliated. If you'd like to force re-affiliation for all such links, you can make that change in your account settings. To force re-affiliation for a single click request, set reaf to 1. optional

The HTML title of the page containing the link to out. optional (but recommended)

txt

The text of the HTML link to out. optional (but recommended)

Response

The response format is governed by the request's format parameter. In all cases the resulting URL is either an affiliated equivalent of the original URL, or the original URL itself if affiliation is not possible.

format=go

A 302 redirect to the result URL.

format=jsonp

A JavaScript document containing a single function call. That function is passed the result URL as its only parameter. The name of the function is determined by the request's jsonp parameter (or "vl_cB" by default). For example, a request which includes format=jsonp&jsonp=foo will return: foo('<result URL>');

format=txt

A text/plain document with the result URL as the body.

required

VigLink uses these parameters to create valuable context in your dashboard analytics and also to detect spam. Including them is highly recommended.