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.
- 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().
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.
- 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".
Sets your user ID for this click request. For more information, see the click REST API documentation below.
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.)
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.)
- 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!
- Your API key.
- 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. An accurate loc value is required in your REST API call.
- 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.
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.
Sets the response format. Possible values are "go", "jsonp" and "txt". For details, see the response description below.
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.)
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.
The HTML title of the page containing the link to out.
The text of the HTML link to out.
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:
See the REST API documentation for more information about key and out.
If your API key was "12345" and you wanted to link to http://www.amazon.com, the VigLink redirector URL would look like this:
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:
|secret||Provided by VigLink, available on your account page.||Authentication|
|period||"day", "week", or "month"||Limits the scope of data returned to 1, 7 or 30 days, respectively|
|lastDate||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.|
Response Status Codes
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 email@example.com.
Differences between integrations
|Reporting||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.|
|Payment||Publisher pays individual users.||VigLink pays individual users who've "claimed" their account.|
|Account Ownership||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.|