Anura Docs

Anura Integration Guide

We offer two simple, but flexible native integration methods: Anura Script, which uses JavaScript and Anura Direct, which is a REST API.

Anura Script is our preferred integration method as it collects more information on the visitor, thereby finding more fraud. Anura Script is robust, enabling it to capture and identify more fraud in client campaigns. We encourage all integrators to use Anura Script, wherever possible, to provide the most insight possible to your campaigns.

When technical integrations will not allow for Anura Script, we offer Anura Direct for a fast, pre-bid analysis of traffic quality. Just as powerful as Anura Script, Anura Direct is ideal for time-sensitive traffic analysis often associated with click and programmatic campaigns. Anura Direct detects SUSPECT and NON-SUSPECT traffic, with SUSPECT traffic aligning 100% with Anura Script.

When in doubt, don't take the lazy way out! Use Anura Script wherever possible to get the best bang for your buck. Use Anura Direct when you're in a pinch and need a quick response, or when your program will not allow for the use of JavaScript.

Script Integration

Anura Script is our preferred method as it collects more information on the visitor, thereby finding more fraud. Anura Script is robust, enabling it to capture and identify more fraud in client campaigns. We encourage all integrators to use Anura Script, wherever possible, to provide the most insight possible to your campaigns.

Script Integration - Request

Placing the following JavaScript snippet at the end of your page's <head> tag will allow Anura to obtain data about, and generate a result value for each visitor to your site.

JavaScript
<script type="text/javascript">
(function(){
    var anura = document.createElement('script');
    if ('object' === typeof anura) {
        var request = {
            instance: yourAssignedInstanceId,
            // source: 'optionalSourceTrackingId',
            // campaign: 'optionalCampaignTrackingId',
            // exid: 'optionalSingleUseExternalId',
            // additional: 'optionalAdditionalData',
            // variable: 'optionalResponseObjectVariable',
            // callback: 'optionalCallbackFunction'
        };
        var params = [];
        for (var x in request) params.push(x+'='+encodeURIComponent(request[x]));
        params.push(Math.floor(1E12*Math.random()+1));
        anura.type = 'text/javascript';
        anura.async = true;
        anura.src = 'https://script.anura.io/request.js?'+params.join('&');
        var script = document.getElementsByTagName('script')[0];
        script.parentNode.insertBefore(anura, script);
    }
})();
</script>

You also have the option of using a "one line" piece of JavaScript, as some platforms and integrations do not allow the use of full scripts. Please ensure the replacement of example parameter values with their actual values when utilizing the one line script.

JavaScript
<script type="text/javascript" src="https://script.anura.io/request.js?instance={INSTANCE_ID}&source={MACRO}&campaign={MACRO}&{CACHEBUSTER}"></script>

Parameter string values should always be URL encoded when using a "one line" integration.

Parameters

Required Type Description Note
instance integer Your instance ID.
Optional Type Description Note
source string A variable, declared by you, to identify "source" traffic within Anura's dashboard interface.
campaign string A subset variable of "source," declared by you, to identify "campaign" traffic within Anura's dashboard interface.
exid string A unique single use external ID, declared by you, that is used to query a specific result from Anura's servers.
additional string An array of Additional Data declared as a JSON encoded string. Read more about using Additional Data.
variable string The variable name of the JavaScript object that response data will be assigned to. This variable contains the response ID, in addition to other data, that will allow you to make real-time decisions.
callback string The name of the JavaScript function to be executed once the response is received. Response data will be passed to the callback function as the first argument.
cachebuster * integer A random multi-digit integer added to the end of the query string to prevent caching of Anura's Script. * The cachebuster value should only be used for "one line" script implimentations.

Source, campaign, exid, variable, and callback parameters are limited to a maximum of 128 characters.

Source and campaign parameters may not equal the following values: "all sources", "all campaigns", "&", "*", "?", "%".

Variable and callback parameters are allowed to start with: "$", "_", or "a-z" characters, followed by "a-z" and "0-9" characters.

Security

Anura Script offers an optional "domain locking" feature to protect against unauthorized use of your instance ID. Once enabled, only requests from client authorized domains will be accepted for processing. Please talk to support about enabling the script domain locking feature.

Script Integration - Response

If you want to be proactive and use response data to make decisions within the context of your page, you will need to access the "response" object. The JavaScript examples below demonstrates 2 unique methods of how to use the response object to query for a "result" using the response ID or EXID.

Preferred Response Method - optionalCallbackFunction()

JavaScript
<script type="text/javascript">
// use a defined optional callback function
function optionalCallbackFunction(response) {
    // if the response ID or EXID is available
    if (response.getId() || response.getExId()) {
        // get the result from Anura servers...
        getResult(response);
    }
}
// get the result from Anura servers using the response object
function getResult(response) {
    var method = 'POST';
    var params = ['instance=yourAssignedInstanceId'];
    if (response.getId()) params.push('id='+encodeURIComponent(response.getId()));
    if (response.getExId()) params.push('exid='+encodeURIComponent(response.getExId()));
    var url = 'https://script.anura.io/result.json'+('GET' === method ? '?'+params.join('&'): '');
    // internet explorer 8-9
    if (window.XDomainRequest) {
        var http = new XDomainRequest();
        if (http) {
            http.open(method, document.location.protocol === 'https:' ? url: url.replace('https:', 'http:'));
            http.onprogress = function(){}
            http.ontimeout = function(){}
            http.onerror = function(){}
            http.onload = function(){anuraResultHandler(this);}
            setTimeout(function(){http.send('POST' === method ? params.join('&'): '');}, 0);
        }
    // other browsers
    } else if (window.XMLHttpRequest) {
        var http = new XMLHttpRequest();
        if (http && 'withCredentials' in http) {
            http.open(method, url, true);
            if ('POST' === method) http.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
            http.onload = function(){anuraResultHandler(this);}
            http.send('POST' === method ? params.join('&'): '');
        }
    }
}
// handle the Anura result
function anuraResultHandler(http) {
    // continue with your custom result handler...
}
</script>

Alternative Response Method - setInterval()

JavaScript
<script type="text/javascript">
// use setInterval to check for the response object every 50 milliseconds
var interval = setInterval(function(){
    if ('object' === typeof optionalResponseObjectVariable) {
        // declare the response object when available
        var response = optionalResponseObjectVariable.getAnura();
        // if the response ID or EXID is available
        if (response.getId() || response.getExId()) {
            // clear defined intervals!
            clearInterval(interval);
            // get the result from Anura servers...
            getResult(response);
        }
    }
}, 50);
// get the result from Anura servers using the response object
function getResult(response) {
    var method = 'POST';
    var params = ['instance=yourAssignedInstanceId'];
    if (response.getId()) params.push('id='+encodeURIComponent(response.getId()));
    if (response.getExId()) params.push('exid='+encodeURIComponent(response.getExId()));
    var url = 'https://script.anura.io/result.json'+('GET' === method ? '?'+params.join('&'): '');
    // internet explorer 8-9
    if (window.XDomainRequest) {
        var http = new XDomainRequest();
        if (http) {
            http.open(method, document.location.protocol === 'https:' ? url: url.replace('https:', 'http:'));
            http.onprogress = function(){}
            http.ontimeout = function(){}
            http.onerror = function(){}
            http.onload = function(){anuraResultHandler(this);}
            setTimeout(function(){http.send('POST' === method ? params.join('&'): '');}, 0);
        }
    // other browsers
    } else if (window.XMLHttpRequest) {
        var http = new XMLHttpRequest();
        if (http && 'withCredentials' in http) {
            http.open(method, url, true);
            if ('POST' === method) http.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
            http.onload = function(){anuraResultHandler(this);}
            http.send('POST' === method ? params.join('&'): '');
        }
    }
}
// handle the Anura result
function anuraResultHandler(http) {
    // continue with your custom result handler...
}
</script>

Response Object Functions

Function Description Note
getId() Returns the response ID used to query the result from Anura's servers.
getExId() Returns the self declared unique external tracking ID used to query the result from Anura's servers.
getResult() Returns the result value. Requires full response.
getMobile() Returns whether a mobile device was detected. Requires full response.
getAdBlocker() Returns whether an ad blocker was detected. Requires full response and ad blocker detection.
getRuleSets() Returns an array of detected broken rule sets. Requires full response and return rule sets.
getInvalidTrafficType() Returns the type of invalid traffic: "SIVT" or "GIVT". Requires full response and return invalid traffic type.
getError() Returns an error message if one has been declared.
getObject() Returns an object of all data listed above.

If you do not specify a response variable when making a script request, "optionalResponseObjectVariable" will default to "Anura".

A "full response" is available, which provides result data immediately and without the need to connect to the result endpoint. Talk to support about enabling or disabling the full response feature.

Ad blocker detection may be enabled or disabled per instance. Talk to support about whether having the ad blocker detection feature turned on/off is right for you.

Script Integration - Result

Script result values may be obtained by calling the endpoint directly.

Method URL Note
GET, POST https://script.anura.io/result.json HTTPS recommended

Example Request

PHP
<?php
// define parameters
$params = array();
$params["instance"] = yourAssignedInstanceId;
$params["id"] = "yourResponseId";
// setup and initialize curl
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://script.anura.io/result.json?".http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// perform the request
$response = curl_exec($curl);
// close the curl connection
curl_close($curl);
// continue with your custom result handler...
?>

Parameters

Required Type Description Note
instance integer Your instance ID.
id string The response ID that is used to request the result from Anura's servers.
Optional Type Description Note
exid string The unique external tracking ID, declared by you, that is used to query the result from Anura's servers. Send "exid" instead of "id" when utilizing the exid parameter.

While we strive to have results available within milliseconds, in worst case scenarios, some results may take longer. Therefore, it is okay to perform multiple queries for a response ID that is not found.

Response ID results will be available for 15 minutes and are removed immediately after a successfully query.

Example Response

{
    "result": "bad",
    "mobile": 1,
    "adblocker": 0,
    "rule_sets": [
        "UE",
        "SP"
    ],
    "invalid_traffic_type": "SIVT"
}

Result Values

Result Description
good The visitor has passed our tests and appears to be trustworthy.
warn There are aspects about the visitor that raise concerns. However, we can not say for certain they are bad. It is your decision how to interpret this value.
bad The visitor has failed our testing and should be considered untrustworthy.

Please refer to our script result definitions documentation for more information on these values.

Rule Set Values

Result Description
DI Data Integrity
UE User Environment
DC Data Center
TO Traffic Origin
IP IP Integrity
SP Spoofing
WC Web Crawler

The "rule_sets" array requires "return rule sets" to be enabled. Talk to support about enabling or disabling the return rule sets feature.

The "invalid_traffic_type" string requires "return invalid traffic type" to be enabled. Talk to support about enabling or disabling the return invalid traffic type feature.

Please refer to our rule set definitions documentation for more information on these values.

Direct Integration

Anura Direct is ideal for a fast, pre-bid analysis of time-sensitive traffic often associated with click and programmatic campaigns, detecting SUSPECT and NON-SUSPECT traffic.

Direct Integration - Endpoint

Direct result values may be obtained by calling the endpoint directly.

Method URL Note
GET, POST https://direct.anura.io/direct.json HTTPS recommended

Example Request

PHP
<?php
// define parameters
$params = array();
$params["instance"] = yourAssignedInstanceId;
// $params["source"] = "optionalSourceTrackingId";
// $params["campaign"] = "optionalCampaignTrackingId";
$params["ip"] = "visitorIPAddress";
// $params["ua"] = "optionalVisitorUserAgentString";
// $params["app"] = "optionalVisitorAppIDString";
// $params["device"] = "optionalVisitorDeviceIDString";
// $params["additional"] = "optionalAdditionalData";
// setup and initialize curl
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://direct.anura.io/direct.json?".http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// perform the request
$response = curl_exec($curl);
// close the curl connection
curl_close($curl);
// continue with your custom result handler...
?>

Parameters

Required Type Description Note
instance integer Your instance ID.
ip string The IP address of your visitor. IPV6 addresses are also supported.
Optional Type Description Note
source string A variable, declared by you, to identify "source" traffic within Anura's dashboard interface.
campaign string A subset variable of "source," declared by you, to identify "campaign" traffic within Anura's dashboard interface.
ua string The user agent string of your visitor. Do not modify the user agent string of your visitor. Modifications to the user agent string may cause adverse results.
app string The application package identifier of your visitor (when available.) Also referred to as: app ID, bundle ID, package name, etc.
device string The device identifier of your visitor (when available.)
additional string An array of Additional Data declared as a JSON encoded string. Read more about using Additional Data.

Source and campaign parameters are limited to a maximum of 128 characters.

Source and campaign parameters may not equal the following values: "all sources", "all campaigns", "&", "*", "?", "%".

Security

Anura Direct offers an optional "IP address locking" feature to protect against unauthorized use of your instance ID. Once enabled, requests will only be accepted from client authorized IP addresses. Please talk to support about enabling the direct IP address locking feature.

Example Response

{
    "result": "suspect",
    "mobile": null,
    "rule_sets": [
        "IP"
    ],
    "invalid_traffic_type": "GIVT"
}

Result Values

Result Description
suspect Based on available data, we have determined the visitor to be suspect.
non-suspect Based on available data, we have determined the visitor to be non-suspect.

Please refer to our direct result definitions documentation for more information on these values.

Rule Set Values

Result Description
UE User Environment
DC Data Center
IP IP Integrity
WC Web Crawler

The "rule_sets" array requires "return rule sets" to be enabled. Talk to support about enabling or disabling the return rule sets feature.

The "invalid_traffic_type" string requires "return invalid traffic type" to be enabled. Talk to support about enabling or disabling the return invalid traffic type feature.

Please refer to our rule set definitions documentation for more information on these values.

Additional Data Integration

Additional Data gives Anura users the ability to pass-in select points of data with their Script or Direct requests, essentially, turning Anura into "your database for transactional data".

Data Structure

Additional Data is passed to Anura using JSON encoded array strings. The following example illustrates how to build a simple JSON encoded array string using PHP.

Data Array

PHP
<?php
// create an array of data
$data = array(
    1 => "9868061c",
    2 => "a4ab95",
    5 => "d021ed96d184"
);
// output the json encoded array string
echo json_encode($data);
?>

The following string, from the output of the PHP code above, is an example of the JSON encoded array string that should be submitted to Anura using the additional parameter.

JSON Encoded Array String

{"1":"9868061c","2":"a4ab95","5":"d021ed96d184"}

Array Values

Data array values may only be strings or numbers of less than or equal to 128 characters. Values greater than 128 characters will be ignored and will not be stored.

Array Keys

It is important to declare the keys in your data array as numbers, starting with 1 going until your instance's Additional Data limit, so that your data points can be mapped to an Additional Data Definition, or self-mapped label, from within the Anura Dashboard. Once created, Additional Data Definition are inserted into the column headers of Raw Data Reports containing Additional Data. It is also important to pass points of Additional Data using the same key position across requests for Raw Data report consistency.

Additional Data Definitions

The Anura Dashboard provides a method of declaring self-mapped labels for your Additional Data array keys, allowing you to have descriptive column headers when viewing your data in a Raw Data Report. The following string illustrates a mapping of Additional Data array keys from our examples used above.

{"Offer ID":"9868061c","Transaction ID":"a4ab95","Click ID":"d021ed96d184"}

When using our "one line" Script implimentation, or Direct GET requests, be sure to URL encode your JSON encoded array string so it is passed to Anura correctly.

Additional Data Definitions are not required when viewing Additional Data. A default value of Additional Data XX will be returned when no key definition has been defined.

Every Anura instance comes with 10 available points of additional data. However, if you require more than 10 points of additional data, the default limit can be raised. Contact your Anura Account Executive for more information.

We recommend you do not send personally identifiable information when using Additional Data.