Knowledge Base/Resources/Developers

VigLink Developer Guide

brian.braunlich
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.

Using the VigLink JavaScript Library

The simplest way to install VigLink is by adding a snippet of JavaScript to your website.  You can find the code to install the VigLink JavaScript library on the VigLink site here (you must be logged in): http://www.viglink.com/install

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.

While it is not necessary to modify the JavaScript bootstrap when you install VigLink, there are a few ways to customize it if you find it necessary or useful.  

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().

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 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.

key
Your unique VigLink API key.
api_url
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".

cuid

Sets your user ID for this click request.  For more information, see the click REST API documentation below.

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.  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.)

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>
class="nolinks"
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

While the JavaScript library is the easiest way to install VigLink on your site, the REST API will give you more control of how to use VigLink on your site or app.  Some sites that find that the REST API particularly useful are coupon or deal sites which frequently change or modify links to merchants and choose which links they affiliate through VigLink.  Using the REST API also allows you to see the destination of the affiliated URL without a “click” taking place.  Or, if you are using VigLink with your web or mobile app (where JavaScript cannot be installed), the REST API may be the best way to integrate VigLink.  However, please keep in mind that using the REST API does require a certain amount of technical knowledge and should only be used by those who are familiar with it.

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: 

http://api.viglink.com/api/<method>[?<parameters>]

 

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: Ensure that all REST parameter values are 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.  An accurate loc value is required in your REST API call.
out
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.
cuid

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.

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 page, set reaffiliate to true.  (Note that only Amazon and eBay links will be re-affiliated at this time.)

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.

We recommend always including optional parameters whenever possible. Any extra data you can provide will improve the quality of analytics on your VigLink dashboard.

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('').

format=txt

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

 

Using the VigLink Redirector

If you're distributing merchant links on your Facebook page, through an email campaign, twitter or a mobile app, or anywhere else that neither the REST API nor the JavaScript library can be used, you can create VigLink redirect links. To create a link you can use the same parameters as in the REST API documentation and change the hostname from "api.viglink.com" to "redirect.viglink.com". There's also a tool on our website (VigLink Link Wrapper) that helps you with this and optionally shortens the URL for you.

Request

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.

Example

If your API key was "12345" and you wanted to link to http://www.amazon.com, the VigLink redirector URL would look like this:
http://redirect.viglink.com/?key=12345&out=http%3A%2F%2Fwww.ama...

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.

CUID

VigLink’s CUID solution is self-serve and does not require any help or additional integration from VigLink. CUID is available whether you're using VigLink’s JavaScript library, REST API or redirector service.

The CUID itself is 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.  Setting a CUID permits VigLink to report revenue back to you on a per-user basis. Simply set your vglnk.cuid if using the JavaScript library, or pass the cuid parameter in a REST or redirector API call.  See those sections of this guide for more information.

CUID Reporting

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:

Request

URL: https://www.viglink.com/service/v1/cuidRevenue
Method: GET

Parameter Value Purpose
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
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.
 
Example
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:

{

"2012/01/01": [{"XYZ":4.05,"ABC":2.20},{}],

"2012/01/02": [{"ABC":13.02},{"amazon.com":3}]

}

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

SubID

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 support@viglink.com.

Differences between integrations 

       Publisher Pays
VigLink Pays 
Implementation CUID can be implemented easily via the JavaScript bootstrap, the REST API or the redirect service. More technical integration required where account "claiming" must be integrated with SubIDs.  
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.

 

 
Topic is closed for comments