Knowledge Base/VigLink API

API Documentation

hannah
posted this on November 09, 2011 09: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.
api_url
The base URL for REST API calls.
cuid
Sets a cuid for use in click requests.
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.)
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.

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.

Request

http://api.viglink.com/api/click?key=<your API key>&out=<URL>&loc=<URL>[&cuid=<str>][&format=go|jsonp|txt][&jsonp=<str>][&reaf=1][&ref=<URL>][&title=<str>][&txt=<str>]

Important: All parameter values must be properly URL-encoded!

key
Your API key.
loc
The URL of the page which contains the link being affiliated. For example, if a link from http://example.com to http://merchant.com is being affiliated, loc is http://example.com.

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.
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.
format
Sets the response format. Possible values are "go", "jsonp" and "txt". For details, see the response description below.
jsonp
The name of the JavaScript callback to use in a jsonp response. This parameter is ignored unless format is "jsonp".
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.
ref
Short for "referrer", ref is the URL of the referring document for the current page. Expanding on the example from loc, if the user came from http://othersite.com to get to http://example.com, ref is http://othersite.com.
title
The HTML title of the page containing the link to out.
txt
The text of the HTML link to out.

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.
 
Topic is closed for comments