Anura Docs

Script Integration

Anura Script is our preferred integration method as it 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.

The code examples displayed on this page attempt to demonstrate the "Request. Response. Result." process by which Anura Script operates.

What follows is a hypothetical process of putting Anura Script on a website, interacting with the response object, and performing a server-side query to obtain a result value using the returned response ID.

We know not everyone is a developer, therefore, we've created a wizard where you're able to create your own semi-custom integrations! You can find it under the "Integration" tab in the Anura Dashboard or by going directly to the Anura Integration Wizard.

Script Integration - Request

Placing the Anura Script at the end of your page's <head> tag will create a "request" which allows Anura to obtain "response" data and generate a "result" value for each visitor to your site.

JavaScript 
<script type="text/javascript">
// FOR DEMONSTRATION PURPOSES ONLY!
(function(){
    var anura = document.createElement('script');
    if ('object' === typeof anura) {
        var request = {
            instance: yourAssignedInstanceId,
            source: 'optionalSourceTrackingId',
            campaign: 'optionalCampaignTrackingId',
            callback: 'optionalCallbackFunction'
        };
        var params = [Math.floor(1E12*Math.random()+1)];
        for (var x in request) params.push(x+'='+encodeURIComponent(request[x]));
        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>

The JavaScript example shown above demonstrates adding Anura Script to a page with a source value of 'optionalSourceTrackingId' and campaign value of 'optionalCampaignTrackingId' that will execute a callback function called 'optionalCallbackFunction' when finished.

Anura Script may also be added to your page using a "one line" piece of JavaScript, as some platforms and integrations do not allow for the use of full scripts.

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

Please ensure the replacement of example macro values with their actual values when using a "one line" integration.

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

Parameters

Required Type Description Note
instance integer Your assigned instance ID.
Optional Type Description Note
source string A variable, declared by you, to identify "source" traffic within Anura's dashboard interface. Source strings should be limited to a reasonable number of unique values. Unique values, such as click IDs, should be passed using Additional Data.
campaign string A subset variable of "source," declared by you, to identify "campaign" traffic within Anura's dashboard interface. Campaign strings should be limited to a reasonable number of unique values. Unique values, such as click IDs, should be passed using Additional Data.
exid string A unique, one-time, single-use external ID, declared by you, that is used to query for a specific result from Anura. EXID values may not be re-used until the initital result has been queried from Anura's servers. A response status code of 540 will be returned when an EXID is unavailable for re-use.
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 object functions will be assigned to. This window variable contains the response ID, in addition to other important data, that will allow you to make real-time decisions. Anura is declared by default.
callback string The name of a declared JavaScript function to be executed once the response is received. Response object functions are passed to the callback 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 added when using "one line" script implementations.

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.

HTTP and User-Agent Client Hints

In order to more accurately identify visitors, Anura Script makes use of HTTP and user-agent client hints that are provided by some modern web browsers. Permission to receive HTTP and user-agent client hints, however, must first be allowed by the referring website. Whenever possible, it is recommended to add both of the following Accept-CH and Permissions-Policy HTTP response headers to any page where Anura Script will be executed.

Accept-CH 
Accept-CH: Device-Memory, Content-DPR, DPR, Viewport-Width, Width, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Form-Factors, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-WoW64
Permissions-Policy 
Permissions-Policy: ch-device-memory=(self "https://*.anura.io"), ch-content-dpr=(self "https://*.anura.io"), ch-dpr=(self "https://*.anura.io"), ch-viewport-width=(self "https://*.anura.io"), ch-width=(self "https://*.anura.io"), ch-ua-arch=(self "https://*.anura.io"), ch-ua-bitness=(self "https://*.anura.io"), ch-ua-form-factors=(self "https://*.anura.io"), ch-ua-full-version=(self "https://*.anura.io"), ch-ua-full-version-list=(self "https://*.anura.io"), ch-ua-mobile=(self "https://*.anura.io"), ch-ua-model=(self "https://*.anura.io"), ch-ua-platform=(self "https://*.anura.io"), ch-ua-platform-version=(self "https://*.anura.io"), ch-ua-wow64=(self "https://*.anura.io")

Read more about HTTP Client Hints and Permissions Policy.

Security

Anura Script offers an optional "domain locking" feature to protect against unauthorized use of your instance ID. Once enabled, only requests from authorized domains will be accepted. Talk to support for more information about domain locking.

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 Anura Script response object functions using an optional callback function.

Optional Callback Function

JavaScript 
<script type="text/javascript">
// FOR DEMONSTRATION PURPOSES ONLY!
function optionalCallbackFunction() {
    // if the Anura object has been declared
    if (!!Anura) {
        // declare your back-end server response handler function
        function backendServerResponseHandler() {
            // redirect the user to the returned destination url
            window.location = this.responseText;
        }
        // send the response ID to your back-end server for result-based redirection
        var http = new XMLHttpRequest();
        http.addEventListener('load', backendServerResponseHandler);
        http.open('POST', 'https://anura.io/example-redirect');
        http.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
        http.send('responseId='+Anura.getAnura().getId());
    }
}
</script>

The JavaScript example shown above demonstrates a basic callback that will send the returned response ID to a back-end server using the getId() response object function. The back-end server in this example will be querying the Anura result endpoint and returning a destination URL to which the visitor will be redirected.

Querying the result endpoint from server-side, using a response ID, or EXID, is the most secure way to actively use Anura, as there is little or no exposure of sensitive result data on the client-side.

Response Object Functions

Function Description Note
getId() Returns the Anura response ID used to query the result from Anura's servers.
getExId() Returns the self-declared external tracking ID used to query the result from Anura's servers.
hasResult() Returns true when the result value is available.
queryResult(callback) A function used to query the result value from Anura's servers within the context of your JavaScript code. The queryResult() function should be executed from your response callback and may only be used once per session. The response ID, or EXID, is automatically referenced from response data and does not need to be declared. The callback parameter is used to execute a declared callback function, which may also be passed anonymously. Response object functions are passed to the callback as the first argument.
isGood() Returns true when the result value is "good". Requires full response or prior use of the queryResult() function.
isWarning() Returns true when the result value is "warn". Requires full response or prior use of the queryResult() function.
isBad() Returns true when the result value is "bad". Requires full response or prior use of the queryResult() function.
getResult() Returns the result value string. Requires full response or prior use of the queryResult() function.
getRuleSets() Returns an array of broken rule sets. Return rule sets must be enabled. Requires full response or prior use of the queryResult() function.
getInvalidTrafficType() Returns the type of invalid traffic: "SIVT" or "GIVT". Return invalid traffic type must be enabled. Requires full response or prior use of the queryResult() function.
isMobile() Returns true when a mobile device has been detected Requires full response or prior use of the queryResult() function.
getMobile() Returns the numeric value of mobile device detection: 0 or 1. Requires full response or prior use of the queryResult() function.
hasAdBlocker() Returns true when an ad blocker has been detected. Ad blocker detection must be enabled. Requires full response or prior use of the queryResult() function.
getAdBlocker() Returns the numeric value of ad blocker detection: 0 or 1. Ad blocker detection must be enabled. Requires full response or prior use of the queryResult() function.
getError() Returns an error message if one has been declared.
getResponseObject() Returns an object of available response data.
getResultObject() Returns an object of available result data. Requires prior use of the queryResult() function.
getObject() Returns a combined object of available response and result data.

If you do not specify the variable parameter when making a script request, "Anura" will be declared by default.

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.

Refer to our callback functions documentation for more information about what data values are available and when.

Script Integration - Result

Anura 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 // FOR DEMONSTRATION PURPOSES ONLY!
// declare an array of request parameters
$params = array();
$params["instance"] = yourAssignedInstanceId;
$params["id"] = $_POST["responseId"];
// declare curl options
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://script.anura.io/result.json?".http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// execute and decode the returned json string
$response = json_decode(curl_exec($curl));
// output the redirection url based on the returned result value
echo isset($response->result) && $response->result === "good" ? "https://anura.io/protected-resource": "https://anura.io/not-found";
?>

The PHP example above completes our demonstration, using the POSTed response ID and performing a cURL request to the Result endpoint. If the returned result value is found to be GOOD the user will be redirected to a protected resource. Whereas, if the user is WARN or BAD, they will be redirected to a page that is not found.

Parameters

Required Type Description Note
instance integer Your instance ID.
id string The response ID that is used to request the result value 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 using the exid parameter.

Depending on your integration, multiple queries to the result endpoint may be required. We find this to be an acceptable practice within reason.

Response ID results will be available for 15 minutes and are removed immediately after a successful result 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 cannot 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.

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.

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