posted this on October 19, 2012 03:36 PM
VigLink Developer Guide
If you’re a developer looking for the ideal way to integrate VigLink into your service, you’ve come to the right place. Welcome! VigLink has built a variety of integration methods that can work across websites (including blogs, forums, web apps), mobile apps, and even desktop apps. In this guide, we document the various ways we make VigLink services available and the controls we provide to developers.
This installation method works best for most text-based websites, such as blogs, forums, or review sites.
With this installation, VigLink automatically affiliates your merchant links dynamically when the link is clicked. Therefore no work is necessary on your end to create or modify these affiliated links. Also, this is the only installation method that allows Link Insertion to be implemented on your site.
Note: VigLink supports a number of content management platforms, including: phpBB, vBulletin, Blogger, Tumblr, TypePad and Wordpress.org. (Please note VigLink does not work on Wordpress.com sites). You can find these plugins which you can find on the VigLink Install page.
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().
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 these values.
Options are only read during initialization. For that reason they must be set prior to including the library, as in the recommended snippet.
Your unique VigLink API key. required; string
The base URL for REST API calls. If you’re using your own CNAME for api.viglink.com, be sure to set this option to "/ /<your CNAME>/api". optional; string; default: "//api.viglink.com/api")
Sets your user ID for this click request. For more information, see the click REST API documentation below.
optional; string; default: ""
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
By default, VigLink will not modify links which are already affiliated. To force re-affiliation for a single page, set reaffiliate to true. If you'd like to force re-affiliation for all such links, you can make that change in your account settings. (Note that only Amazon and eBay links will be re-affiliated at this time.)optional; boolean; default: false
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>
If you have Link Insertion enabled but want to prevent links from being inserted in a certain part of the page, you can add the class"nolinks" to any HTML tag that wraps that part of the page.
<div class="nolinks">VigLink will never insert any links here.</div>
The rest of this documentation is designed for people who are interested in implementing VigLink via the REST API or the redirect service. If you are unfamiliar with this technology or lingo, the above installation instructions are for you.
Using the VigLink REST API
You can find our complete REST API documentation below:
VigLink provides a simple HTTP API for URL affiliation. Requests are made via an HTTP GET in the form of:
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.
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: Ensure that all REST parameter values are properly URL-encoded!
The URL to affiliate. If the URL cannot be affiliated, the unmodified URL is echoed in the response. The response format is governed by the format parameter.required
An ID of your choosing that identifies the clicker, the page the link is on, a campaign or the click itself. The cuid should not contain personally identifiable information. Use of this parameter permits VigLink to report revenue back to you on a per-user basis.
optional; up to 32 alphanumeric characters; case sensitive
Sets the response format. Possible values are "go", "jsonp" and "txt". For details, see the response description below. optional; default: go
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 reaffiliate to true. (Note that only Amazon and eBay links will be re-affiliated at this time.)optional
The HTML title of the page containing the link to out. optional (but recommended)
The text of the HTML link to out. optional
We recommend always including optional parameters whenever possible. Any extra data you can provide will improve the quality of analytics on your VigLink dashboard.
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.
A 302 redirect to the result URL.
A text/plain document with the result URL as the body.
Using the VigLink Redirector
A redirector request is compatible with the REST API's click request format. Unlike the REST API, only key and out are required:
How do I choose between the REST API or the redirect service?
The REST API is not intended to be used directly in a browser as an end-user's browser should never see a link to api.viglink.com. The REST API is meant to be called in the background with the user being redirected to the result URL. If you are unable to make the call in the background and need to redirect users in a browser, then you should use our redirector.
Advanced Revenue Tracking
VigLink provides two means of tracking revenue individually for each of your users: Customer Unique Identifier (CUID) or SubUser/SubID.
Revenue is stored segmented by each unique CUID value that you provide. Reports of revenue distribution across those CUID values are available via this REST API call:
Provided by VigLink, available on your account page.
"day", "week", or "month"
Limits the scope of data returned to 1, 7 or 30 days, respectively
Date in the format YYYY/MM/DD
The last date for which data should be returned. This report is by revenue posting date rather than click or transaction date.
The response is a JSON object with one key per day. Each property's value is an array containing two JSON objects: the first maps CUID to revenue, the second merchant domains to revenue. The second object reports only revenue that could not be assigned to a CUID.
On January 1, 2012 the CUID XYZ earned $4.05 in revenue and ABC earned $2.20. The next day, ABC earned $13.02, and there was $3 of unattributable revenue. The response would be:
Response Status Codes
200 OK 400 Missing parameters or invalid parameter values 403 Attempt to access service over HTTP or invalid secret key 503 Service unavailable
With CUID, only reporting is affected and all revenue is still paid out to one VigLink user. A SubID integration, however, creates a full-blown VigLink user for each of your users. Initially revenue still flows to the parent account, but you can allow the user to "claim" their VigLink account, at which point their revenue flows directly to them from VigLink. Because SubID integration creates full-blown VigLink users, there are also complete analytics dashboards for each of those users on viglink.com.
SubID integration is only available to publishers with a minimum threshold of traffic and revenue. If you are interested in this type of integration, please contact firstname.lastname@example.org.
Differences between integrations
More technical integration required where account "claiming" must be integrated with SubIDs.
Revenue is tracked per CUID and available to the publisher via a REST API. Any reporting to the users is done by the publisher.
All clicks and revenue are tracked and can be accessed in the VL dashboard. Users can see their dashboard once the account is claimed.
Publisher pays individual users.
VigLink pays individual users who've "claimed" their account.
No additional VigLink accounts are created. CUID is purely for reporting.
Once an account is claimed it behaves like any other VigLink account: site login, full dashboard, self-serve account management.