ConversionRuler.com allows you to submit action information outside of the regular JavaScript snippet notification from a web page. This API is useful for commerce applications which perform transaction processing off site, or wish to record actions outside of the user's web session.
The Action API allows you to determine a user's identification with ConversionRuler and then to notify our servers outside of the user's web session that a particular action took place. The API consists of two parts:
Your web pages need to record and pass the visitor identification for a particular site visitor prior to accessing the Action API. To do this, you will leverage aspects of our Cross-Channel functionality which enables access to server-side values such as the user cookie and the user landing code. You can record the user cookie information on your site in one of the following ways:
The typical installation of the API is to pass the cookie value in a form to your servers, and is covered in this document.
To access the user cookie on our servers, you will use the identical JavaScript file as used in the Cross-Channel Tracking document, found at "/bin/xjs.php" on the www.conversionruler.com server. This is called the cross tracking snippet. The standard snippet is located at "/bin/js.php".
The following is of the utmost importance when using the cross tracking snippet:
To retrieve the user cookie from our server, simply invoke the following JavaScript on your web page:
<script language="javascript" src="http://www.conversionruler.com/bin/xjs.php?siteid=XXX"></script>
<script language="javascript" language="JavaScript">
if (typeof cr_track != 'undefined') { cr_track(); }
</script>
Once this code has been invoked on your page, you can now access the JavaScript global variable called CRCookie to output the cookie in any way you see fit.
The xjs.php contains some handy functions for embedding the cookie in your web page, or in a hidden form field. This section outlines the two Action API JavaScript functions for visitor identification, their parameters, and how they are invoked on the page.
CRCookieOutput writes the 32-character user cookie to the page directly, and has three optional parameters which can be used to customize the output of the cookie value. It requires that cr_track has been called previously on the same page as well as the siteid global variable to be defined.
Both parameters are optional. To specify an empty parameter (if you want to specify a suffix but not a prefix), enter the empty string in your JavaScript (e.g. two quotes, "", or '')
The prefix and suffix indicate a pair of strings which are output when a cookie exists for this visitor and are output before and after the visitor's cookie.
The function cr_track must be invoked previously on a page, and the siteid variable must defined prior to invokation of this function. If proto is not defined prior to invokation of this function, it defaults to the string 'http'.
Here are some examples of how this function can be invoked:
<p>Welcome to our site.
... Call cr_track ...
<script language="javascript">
CRCookieOutput(
Your tracking number is <strong>',
'</strong>. Please use this number in any correspondence with us.');
</script>
</p>
This will output:
Welcome to our site. Your tracking number is dc93f7e3de1d6afb879dc89c04711088. Please use this number in any correspondence with us.
CRCookieFormInput outputs a hidden form variable used for submission to your site's forms. It requires that a variable named siteid be defined previously on the page.
The name variable is a string which is required and identifies the input name which will be submitted when the user submits the form.
<form action="myform.html" method="post">
<script language="javascript">
CRCookieFormInput('CRCookie');
</script>
<input type="submit" name="OK" value="Submit Form" />
</form>
Beware of the following issues when implementing the Action API on your site:
<!-- This will lead to unpredictable results! DO NOT DO THIS -->
<script language="javascript" src="http://www.conversionruler.com/bin/xjs.php?siteid=XXX"></script>
<!-- bunch of other HTML -->
<!-- THIS NEXT LINE IS THE ERROR -->
<script language="javascript" src="http://www.conversionruler.com/bin/js.php?siteid=XXX"></script>
<script language="javascript">
var siteid = XXX; var proto = 'http';
if (typeof(valid) + '' != 'undefined') {cr_track()};
</script>
... more stuff ...
<script language="javascript">
CRCookieOutput();
</script>
The cr_track function when called with the cross tracking snippet defines a variable called CRCookie. You may access this in scripts on your page.
You may perform any custom functionality with the CRCookie by detecting whether it's set or not, e.g.
<script language="javascript">
if (typeof CRCookie == 'undefined') {
// Site visitor doesn't have a cookie, or problem with cr_track invokation
} else {
// Site visitor has cookie
}
</script>
Once you have determined the user cookie value, you can notify our servers in your back-end processes by accessing the Action Notification URL on our server.
The Action Notification URL is:
http://www.conversionruler.com/bin/tracker.php
You will pass parameters to this URL using a standard HTTP GET request to our server. You must format and pass variables using standard HTTP query string syntax, including escaping of special characters, if any.
Variable names as described below are case-sensitive. All variable names are lower-case.
You may pass the following variables to our server:
| Variable Name | Description | Example |
|---|---|---|
| siteid | Required. The Site ID of the site to record this action for. | siteid=935 |
| crcookie | Required. The user cookie to record an action for. | crcookie=dc93f7e3de1d6afb879dc89c04711088 |
| actn | Required. Action ID of the action to record for this visitor. Depending on the configuration of this Action ID on the ConversionRuler web site, the following values may or may not be relevant to this request. | actn=3 |
| eval | Optional. Numeric value representing an order amount or similar numeric value. | eval=24.33 |
| etext | Optional. String value representing an order number or similar associated value with eval. | etext=41259783 |
| eval2 | Optional. Numeric value representing a second order amount, a subtotal, or value to be summed in reports. | eval2=24.33 |
| etext2 | Optional. String value representing a customizable value to be displayed in reporting details. | etext2=john@example.com |
In the simplest case, you can send just siteid, crcookie and actn. In most common cases, you will send siteid, crcookie, actn, eval, and etext. The following example uses PHP and the URL fopen syntax which must be configured when building PHP:
<?php
/*
... Process order and define $OrderAmount and $OrderNumber
*/
/* Build CR Query String */
$qs = array();
$qs[] = "siteid=935";
$qs[] = "crcookie=" . urlencode($CRCookie);
$qs[] = "actn=3";
$qs[] = "eval=" . urlencode($OrderAmount);
$qs[] = "etext=" . urlencode($OrderNumber);
/* Notify CR Server */
$f = fopen("http://www.conversionruler.com/bin/tracker.php?" . implode("&", $qs), "r");
if (!$f) {
// Handle error
}
fclose($f);
/* We have recorded the transaction with ConversionRuler */
This records the complete URL:
http://www.conversionruler.com/bin/tracker.php?siteid=935&crcookie=dc93f7e3de1d6afb879dc89c04711088&actn=3&eval=34.55&etext=4234323
Currently, there is no way to determine a status of the action recording. The server will return a blank document. We will add a status result in the future to increase reliability of server transactions.
Note that actions which occur within a 15 minute time frame which appear identical to the server will only be recorded once.