Increase your website sales and conversions.
Website optimization tools that simply work.

Javascript and REST API

Developer documentation containing Javascript (callbacks) and REST API details for behavioral targeting, optimization, segments and content blocks.

Tracking Visitors

The core entity on Wingify TargetOpti is a website visitor. Each website visitor is identified by a cookie _wg_visitor_id which contains the visitor’s id (a numeral). When the visitor freshly arrives, the refferer, user agent string, local time and other information is passed to the server and a fresh new visitor id is assigned to the visitor, which is stored in the cookie. All the javascript functions used by Wingify such as tracking, segmenting, experiments, etc. are contained in one single file called wg_consolidated.js. It is important to include this file before using any of the Wingify’s functions. This file, 4 kb in size, is compressed and is also cached by the browser. Hence, the load of this file is minimal. This file should be included in the head of the website as:

<script type='text/javascript' src='http://server.wingify.com/app/js/code/wg_consolidated.js'>
</script>

Before a visitor can be targeted, segmented or subjected to an experiment, he must be assigned a visitor_id. So, calling tracking function is at the top, before calling other functions, is very important. Hence, just after including the wg_consolidated.js in the head, call the tracking function as:

<script  type='text/javascript'>_wg_track(ACCOUNT_ID);</script>

ACCOUNT_ID is id of your account, which you can see on your dashboard.  You can specify _wg_track_callback = YOUR_FUNCTION_NAME, which would call your function once the server responds. Your function then can analyze _wg_track_result (JSON object) to see what the server responded to. Obviously, you would have to define callback before you call the _wg_track function.

API

To call visitor tracking from your code, first check if the cookie _wg_visitor_id is set with the visitor’s id. If the value is not present, it means this visitor will have to be allocated a new visitor id. You must also check for a cookie called _wg_session_id, which signifies the session number of the visitor on your website. On fresh first time arrival of the visitor, both _wg_visitor_id and _wg_session_id would be missing. And on repeat visit, only _wg_session_id would be missing as this cookie’s lifetime is within one session only.

After checking for both the cookies, call the following URL:

http://server.wingify.com/app/visitor_track.php?
&account_id=ACCOUNT_ID
&visitor_id=VISITOR_ID_IF_PRESENT
&session_id=SESSION_ID_IF_PRESENT
&document_uri=ESCAPED(PAGE_URL)
&document_refferer=ESCAPED(PAGE_REFFRER)
&navigator_string=ESCAPED(USERAGENT_STRING)
&local_time=ESCAPED(VISITOR_LOCALTIME_STRING)
&wg_random=RANDOM_NUMBER_TO_PREVENT_CACHING

If you have supplied visitor id and session id, the server would respond with an empty JSON string. If new visitor id and/or session id needs to be allocated, the server would respond with the following JSON string:

{
        "new_visitor_id": NEW_VISITOR_ID,
        "create_visitor_cookie": true,
        "session_id": SESSION_ID,
        "create_session_cookie": true
}

new_visitor_id is the the value that would identify this visitor and would need to be stored in a long-term (365 days) _wg_visitor_id cookie and session_id would need to be stored in a session only cookie called _wg_session_id.

Note if account is disabled you provide with wrong account_id, visitor_id or session_id, the server would respond with _wg_error JSON string.

Example

When the visitor first time arrives on the site, call the following URL:

http://server.wingify.com/app/visitor_track.php?
&account_id=3
&document_uri=http%3A%2F%2Fparaschopra.com%2F
&document_refferer=
&navigator_string=Mozilla%2F5.0%20(Windows%3B%20U%3B%20Windows%20NT%205.1%3B%20enUS%3B%20rv%3A1.9.0.10)%20Gecko%2F2009042316%20Firefox%2F3.0.10
&local_time=Friday%2C%20June%2005%2C%202009%209%3A21%3A50%20AM
&wg_random=0.5018776110413291

The server responds with:

{
        "new_visitor_id": 1298,
        "create_visitor_cookie": true,
        "session_id": 1,
        "create_session_cookie": true
}

The two cookies are set and on further browsing in the same session, following URL is called:

http://server.wingify.com/app/visitor_track.php?
&account_id=3
&visitor_id=1298
&session_id=1
&document_uri=http%3A%2F%2Fparaschopra.com%2Fprojects%2F
&document_refferer=http%3A%2F%2Fparaschopra.com%2F
&navigator_string=Mozilla%2F5.0%20(Windows%3B%20U%3B%20Windows%20NT%205.1%3B%20enUS%3B%20rv%3A1.9.0.10)%20Gecko%2F2009042316%20Firefox%2F3.0.10
&local_time=Friday%2C%20June%2005%2C%202009%209%3A29%3A45%20AM
&wg_random=0.5497223269250283

The server responds with an empty JSON string.

The same visitor does a repeat visit on the website, following URL is called:

http://server.wingify.com/app/visitor_track.php?
&account_id=3
&visitor_id=1298
&document_uri=http%3A%2F%2Fparaschopra.com%2Fprojects%2F&document_refferer=
&navigator_string=Mozilla%2F5.0%20(Windows%3B%20U%3B%20Windows%20NT%205.1%3B%20en-US%3B%20rv%3A1.9.0.10)%20Gecko%2F2009042316%20Firefox%2F3.0.10
&local_time=Friday%2C%20June%2005%2C%202009%209%3A41%3A26%20AM
&wg_random=0.9100067109278733

Note that the session_id parameter is not passed. Calling this URL, the server responds with a JSON string signaling setting up of _wg_session_id cookie with 2 as value.

{
        "session_id": 2,
        "create_session_cookie": true
}
↑ Back to Top

Real time information on Visitors

If you need to obtain real-time information about your visitors, you can do a REST call to following URL

http://server.wingify.com/app/get_report.php?
&account_id=ACCOUNT_ID
&visitor_id=VISITOR_ID
&authtoken=YOUR_SECRET_AUTHENTICATION_TOKEN
&function=METRIC_NAME
&parameter=PARAMETER_FOR_METRIC_IF_ANY

The response of this would be in JSON format:

{
        "RESPONSE"
        
}

As mentioned earlier, visitor_id can be read from visitor's cookie named _wg_visitor_id

An example of this API is:

http://server.wingify.com/app/get_report.php?
&account_id=2
&visitor_id=590
&authtoken=xyz
&function=getVisitedPage
&parameter=http://www.wingify.com/contact-us/

Following list contains all the metrics available, their names, if the accept parameters and what kind of response they return

General

  • getBrowser: returns browser name
  • getOS: returns OS name
  • getMobile: returns mobile name
  • getIP: returns IP Address
  • getOrganization: returns organization name
  • getCountry: returns country name
  • getCity: returns city name
  • getLocalTimeHourLatestLanding: returns hour of the day (0-23) when visitor landed in his latest session
  • getLocalDayWeekLatestLanding: returns day of the week (Sunday, Monday, etc.) when visitor landed in his latest session

Refferal

  • getRefferal: returns refferal URL for the visitor's first visit
  • getKeywords: returns search keywords for the visitor's first visit
  • getRefferalLatestVisit: returns refferal URL for the visitor's latest visit
  • getLatestKeywords: returns search keywords for the visitor's latest visit

Time Behavior

  • getTimeSpentInLatestSession: returns time spent (in seconds) by visitor in his latest visit
  • getAverageTimeSpentPerSession: returns average time spent (in seconds) across sessions by a visitor
  • getTimeSpentURL: returns time spent (in seconds) by visitor on a URL or category specified by parameter (click here to format of URL/category)
  • getTotalTimeSpent: returns total time spent (in seconds) across sessions by a visitor
  • getAverageTimeSpentPerPage: returns average time spent per page viewed (in seconds) across sessions by a visitor

Pageview Behavior

  • getTotalPageViews: returns total number of pages viewed across sessions by a visitor
  • getPageViewsInLatestSession: returns total number of pages viewed in latest session by a visitor
  • getPageViewsPerSession: returns average number of pages viewed per session by a visitor
  • getTotalPageViews: returns total number of pages viewed across sessions by a visitor
  • getVisitedPage: returns 1 if a visitor has visited a certain URL or category specified by parameter (click here to format of URL/category)
  • getTotalPageViews: returns total number of pages viewed across sessions by a visitor
  • getLatestLandingPage: returns landing page of a visitor for the latest session
  • getLastExitPage: returns exit page of a visitor for the last session
  • getLastPageViewed: returns the last page viewed by a visitor
  • getCurrentPageViewed: returns the current page viewed by a visitor

Recency and Frequency

  • getDaysSinceLastSessionExcludingLatest: returns the number of days a visitor's previous visit occured
  • getNumberOfSessions: returns the number of sessions by a visitor on your site
  • getDaysPerSession: returns the average number of gap (in days) between visitor's visit

Custom Variables

  • getCustomVariableValue: returns value of custom variable for a visitor. Custom variable name needs to be specified in the parameter

Goals

  • getGoalTriggered: returns 1 if a visitor triggered a goal, 0 otherwise. Goal name needs to be specified in the parameter
  • getGoalTotalValue: returns total value of a goal for the visitor. Goal name needs to be specified in the parameter
  • getGoalAverageValue: returns average value of a goal for the visitor. Goal name needs to be specified in the parameter

Tests, Experiments

  • getVariationForExpFactor: returns variation name which is assigned to the visitor for a particular experiment and factor. Experiment and factor name needs to be specified in this format: "experiment_name|||factor_name", e.g. "contact_us|||button".

Segments

  • getIfUserInSegment: returns 1 if a visitor belongs to the segment, 0 otherwise. Segment name needs to be specified in the parameter


↑ Back to Top

Experiments

To initialize an experiment, include the following code in head of your website

<script type='text/javascript'>
          _wg_experiment(ACCOUNT_ID,  ['EXPERIMENT_NAME']);
</script>

Example

<script type='text/javascript'>
          _wg_experiment(12,  ['sidebar_banner']); 
</script>

You can also check for multiple experiments at a time by passing an array of experiment names instead of single experiment name.

After you have included the code for requesting variations from the server, for each factor place following snippets at appropriate places:

  • URL: this code goes into the head 
    <script type='text/javascript'>
_wg_getURL('EXPERIMENT_NAME', 'FACTOR_NAME', 'DEFAULT_URL');
</script>
  • Stylesheet: this code goes into the head
    <script type='text/javascript'>
_wg_getStyleSheet('EXPERIMENT_NAME', 'FACTOR_NAME', 'DEFAULT_CSS_PATH');
</script>
  • Content: this code replaces the existing content
    <script type='text/javascript'> 
_wg_getContent('EXPERIMENT_NAME', 'FACTOR_NAME', 'DEFAULT_URL')</script>
Existing content or control</span>

Note: for implementing callbacks in Javascript code or for getting access to internal Wingify’s Javascript variables (used for tracking experiment status, factor initialization status, variation content, etc.) set 

 _wg_experiment_callback  = YOUR_FUNCTION_NAME

Once server has responded, the variation content is set into this universal variable 

_wg_factors['EXPERIMENT_NAME']['FACTOR_NAME']
and your function would be called with experiment name as parameter. For example, your function would be called (for each experiment on the page) in following manner:

YOUR_FUNCTION_NAME('EXPERIMENT_NAME');

Your callback function may analyze this variable (containing JSON object) to get which variations are assigned to the factors. If the variable 

_wg_factors['EXPERIMENT_NAME']['FACTOR_NAME']
is not assigned, it means there is an error in the experiment.

API

If you wish to get variations of a factor through API, call the following URL

http://server.wingify.com/app/get_variation.php
&account_id=ACCOUNT_ID
&experiment_name=EXPERIMENT_NAME
&visitor_id=VISITOR_ID

You can get access to visitor id by reading the cookie _wg_visitor_id. The response of this URL would be a JSON string of the following structure:

{
      "_wg_experiment":  "EXPERIMENT_NAME",
      "_wg_factors": 
      [
          {
              "_wg_factor_name":  "FACTOR_NAME_1",
              "_wg_factor_content":  "FACTOR_CONTENT_1",
              "_wg_factor_type":  "FACTOR_TYPE_1"
          },
          {
              "_wg_factor_name":  "FACTOR_NAME_2",
              "_wg_factor_content":  "FACTOR_CONTENT_2",
              "_wg_factor_type":  "FACTOR_TYPE_2"
          }
      ]
}

Factor type (content or url or stylesheet) would be irrelevant here as you would be interpreting factor name and factor content according to your own way.

This JSON string can be converted to an object easily in your favorite programming languages. Almost all languages have libraries supporting JSON.  If the visitor_id, account_id or experiment_name is invalid. Or, in case experiment is disabled, a JSON string with _wg_error set is received. For example,

{"_wg_experiment":"WRONG_EXPERIMENT_NAME",
"_wg_error":"Experiment  name not correct"}
Example

If you call this URL:

http://server.wingify.com/app/get_variation.php?
&account_id=3
&experiment_name=sidebar_exp_refined
&visitor_id=178
&wg_random=0.8382816705852747

You would get the following response:

{
      "_wg_experiment":  "sidebar_exp_refined",
      "_wg_factors": 
      [
        {
           "_wg_factor_name": "sidebar",
           "_wg_factor_content": "<div class=\"sidelist\">Banner 1<\/div>",
           "_wg_factor_type": "content"
        }
      ]
}
↑ Back to Top

Segments

After making sure that the visitor information is being tracked properly, you may check if the visitor belongs to a segment by using the following JS code.

<script type='text/javascript'>
  _wg_segment(ACCOUNT_ID, ['SEGMENT_NAME_1', 'SEGMENT_NAME_2']);
  </script>

If you want to check for all the segments created by you, simply call the following JS code:

<script type='text/javascript'>
  _wg_segment(ACCOUNT_ID);
</script>

The code above calls the server and asks it to which segments does the current visitor belong to. The server responds with a list of all segments containing values as the (JavaScript) date when the visitor was allocated to the segment. These dates can be seen to deduce which is the most latest segment, visitor is belonging to. If the visitor does not belong to a segment, a value of -1 (in case of wrong segment name) or 0 (in case of visitor not belonging to segment) is assigned to it. Moreover, once .  This list is represented as a key-value JavaScript array _wg_segments

For example, 

_wg_segments['check_firefox']
may be containing value of 30 May 2009. Or
 _wg_segments['repeat_visitor']
may containing value of -1.

You may specify a callback function 

_wg_segment_callback = YOUR_FUNCTION_NAME;
which would call your function, once the server responds. For each segment, your function would be called in following manner:

YOUR_FUNCTION_NAME('SEGMENT_NAME');

You can then check the value of variable _wg_segments to know which segments does this visitor belong to.

API

To test for all segments call this URL:

http://server.wingify.com/app/test_segment.php?
&account_id=ACCOUNT_ID
&visitor_id=VISITOR_ID
&wg_random=RANDOM_NUMBER
&test_all=1

Or to test for selected segments, call this URL:

http://server.wingify.com/app/test_segment.php?
&account_id=ACCOUNT_ID
&test_segments['SEGMENT_1_NAME']=1
&test_segments['SEGMENT_2_NAME']=1
&visitor_id=VISITOR_ID
&wg_random=0.934

The server responds with a JSON string:

{
  "SEGMENT_NAME_1": "DATETIME  OR -1 OR 0"
  " SEGMENT_NAME_2": " DATETIME  OR -1 OR 0",    
  ....
}
Example

Upon calling this URL:

http://server.wingify.com/app/test_segment.php?
&account_id=2
&test_all=1
&visitor_id=86
&wg_random=0.9776652125225078

The server responds with:

{
  "ncr_visitors": "2009-06-05  04:39:28",
  "indian_visitors":  "2009-06-05 04:39:28",
  "repeat_visitor": 0,
  "first_visitor": "2009-06-05  04:40:47"
}

Or call this URL:

http://server.wingify.com/app/test_segment.php?
&account_id=2
&test_segments['ncr_visitors']=1
&test_segments['repeat_visitors']=1
&visitor_id=86
&wg_random=0.934

The server responds with:

{
  "ncr_visitors": "2009-06-05  04:39:28",
  "repeat_visitors": -1
}
↑ Back to Top

Zones

To get content for zones, you would have to call the following JS code in the head of your website.

<script type='text/javascript'>
         _wg_zone(ACCOUNT_ID,  ['ZONE_NAME']);
</script>

For example:

<script type='text/javascript'>
         _wg_zone(2,  ['header_target']);
</script>

Please ensure that _wg_track has been called before you call this function.
Now, after including this code, place the following code at the location where you want the zone to be located:

<script type='text/javascript'>
         _wg_getZone('ZONE_NAME');
</script></span>

For example:

<script type='text/javascript'>
         _wg_getZone('header_target');
</script></span>

You may specify a callback function

 _wg_zone_callback =  YOUR_FUNCTION_NAME;
which would call your function, once the server responds.  Your function would be called with ZONE_NAME as parameter.  For example, your function would be called (for each zone on the page) in following manner:

YOUR_FUNCTION_NAME('ZONE_NAME');

You can then check the value of variable 

_wg_content_blocks['ZONE_NAME']
to know what content has the server responded with.

API

Upon calling the following URL: 

http://server.wingify.com/app/get_zone.php?
&account_id=ACCOUNT_ID
&zone_name=ZONE_NAME
&visitor_id=VISITOR_ID
&wg_random=RANDOM_NUMBER

The server responds with:

{
         "_wg_zone_name": "ZONE_NAME",
         "_wg_zone": "ZONE_VALUE"
}

In case you error (wrong account id, visitor id or content block name), the server responds with a _wg_error key.

Example
http://server.wingify.com/app/get_zone.php?
&account_id=2
&zone_name=header_target
&visitor_id=86
&wg_random=0.9776652125225078

The server responds with:

{
         "_wg_zone_name": "header_target",
         "_wg_zone": "Hey, visitor from Delhi NCR!"
}
↑ Back to Top

Goals

To trigger goal for a visitor, call the following code:

<script type='text/javascript'>
         _wg_goal(ACCOUNT_ID, 'GOAL_NAME', GOAL_VALUE);
</script>

For Example:

<script type='text/javascript'>
         _wg_goal(3, 'downloaded' , 1);
</script>
API

Call the following URL for triggering a goal:

http://server.wingify.com/app/goal.php?
&account_id=ACCOUNT_ID
&visitor_id=VISITOR_ID
&session_id=SESSION_ID
&goal_name=GOAL_NAME
&goal_value=GOAL_VALUE
&wg_random=RANDOM_NUMBER

To server would send an empty responce to this URL as goals are passive.

Example
http://server.wingify.com/app/goal.php?
&account_id=3
&visitor_id=1231
&session_id=2
&goal_name=sidebar_click
&goal_value=1
&wg_random=0.9795883420495882
↑ Back to Top

Custom Variables

Custom variables are used for storing values related to visitors which are defined by you. For example, a custom variable could be ‘gender’ with possible values ‘male’ or ‘female’. You would want to set this variable whenever you capture the information, for example during signups.
To track values for custom variables, call the following code:

<script type='text/javascript'>
         _wg_custom(ACCOUNT_ID, 'CUSTOM_VARIABLE_NAME',  'CUSTOM_VARIABLE_VALUE');
</script>

For example,

<script type='text/javascript'>
		_wg_custom(3,  'shipping_prefrence',  'fedex');
</script>
API

Call the following URL for tracking custom variable values:

http://server.wingify.com/app/goal.php?
&account_id=ACCOUNT_ID
&visitor_id=VISITOR_ID
&custom_name=ESPACED(CUSTOM_VARIABLE_NAME)
&custom_value=ESCAPED(CUSTOM_VARIABLE_VALUE)

To server would send an empty responce to this URL as custom variables tracking is passive.

Example
http://server.wingify.com/app/custom_track.php?
&account_id=1
&visitor_id=101
&custom_name=emailid
&custom_value=myemail%40domain.com
&wg_random=0.642333360034879
↑ Back to Top

ContextSense

ContextSense is a simple API to return tags, concepts, categories, sentiment and related links for a given URL or piece of text. Calling API is very simple. You call the following URL

http://api.wingify.com:9312/context/

and pass three parameters (either through GET or POST) to it

content = URL or piece of text
authkey = your secret API key
callback = Optional parameter. A callback for the JSON returns

An example is

http://api.wingify.com:9312/context/?content=http://www.wingify.com/&authkey=cvi1wke4r92m6x

Best way to learn the API is to play with above URL and observe the response. (Response in indented, though it will not apprear so in browsers)

The API returns response in JSON in format:

{ 
 "concepts": [
  [
   "Concept 1", 
   Score_for_concept_1
  ], 
  [
   "Concept 2", 
   Score_for_concept_2
  ], 
  [
   "Concept 3", 
   Score_for_concept_3
  ],
	......
 ], 
 "categories": [
  [
   "Category 1", 
   Score_for_category_1
  ], 
  [
   "Category 2", 
   Score_for_category_2
  ],
	.......
 ], 
 "sentiment": {
  "text": "Sentiment Text", 
  "value": Sentiment_Value
 }, 
 "tags": [
  "TAG_1", 
  "TAG_2", 
  "TAG_3",

	.......
 ]
}
Example
{ 
 "concepts": [
  [
   "Content Management", 
   4.7196959249999999
  ], 
  [
   "Advertising", 
   2.2553873677579999
  ], 
  [
   "Site Management", 
   1.9410400896083999
  ], 
  [
   "Hosted Services", 
   1.25289575
  ], 
 
	......
 ], 
 "categories": [
  [
   "Computers > Software > Internet > Site Management > Content Management", 
   4.7196959249999999
  ], 
  [
   "Computers > Software > Internet > Servers > Advertising", 
   2.0067153372499997
  ], 
  [
   "Computers > Software > Internet > Site Management", 
   1.9410400896083999
  ], 
  [
   "Computers > Software > Internet > Site Management > Log Analysis > Commercial > Hosted Services", 
   1.25289575
  ], 
  [
   "Computers > Internet > Web Design and Development > Promotion > Advertising, Banners, and Exchanges", 
   1.1496458000000001
  ], 
	....
 ], 
 "sentiment": {
  "text": "Slightly Positive", 
  "value": 0.63825063223980927
 }, 
 "tags": [
  "targeting", 
  "behavioral", 
  "website", 
  "customers", 
  "personalization", 
  "automatic", 
  "target", 
  "email", 
  "predict", 
	....
 ]
}
Details

The API would return a lot of concepts and categories. The score represent relevance to the input URL/text provided. Higher the score, more relevant would concept or categories are. Further, in results, concepts and categories are sorted according to score. We recommend you to use a threshold score to select most relevant categories and concepts. Though the threshold would depend on the domain of application, generally a threshold of 0.5-0.8 should be good enough.

For sentiment analysis, the value ranges from 0-1 (negativeness to positiveness). Along with a value, text is also provided which shows interpretation of the value in sentiment scale. In some cases, API does not have enough confidence to give a sentiment value, hence returns -1 as value.

Error

In some cases the API returns error because a wrong URL was specified or too less content was provided to determine context. In that case in JSON error field would contain error description and JSON error_code field would contain code of the error, which may take one of the following values.

SERVER_ERROR: when unspecified error occurs
CONTEXT_ERROR: when context of the contents cannot be determined
API_ERROR: when wrong API key is specified
FETCH_ERROR: when there is error fetching contents from the supplied URL


← Back to Documentation