Adscore JavaScript and Links API

Adscore Links

Default endpoint: https://c.adsco.re/r

In order to simplify implementation, we offer a ready-made URL redirection service utilizing Adscore. Adscore links have to start with https://c.adsco.re/r and continue with configuration parameters as described:

Parameters to be provided in query string format, as per https://en.wikipedia.org/wiki/Query_string. They can be provided either after ? (as in a normal URL) or #. For example

https://c.adsco.re/r#param1=value&param2=value - using # as the separator between domain and query string allows more optimal caching on both CDN and browser levels and should be the preferred way.
https://c.adsco.re/r?param1=value&param2=value - using ? as the separator between domain and query string allows to maintain compatibility with 3rd party systems (ie. some advertising networks for unknown reasons do not allow # in URL).

Supported parameters for the Adscore Link are exactly the same as Adscore JavaScript Engine options listed above. Apart of that, few additional options are supported:

Name	Required	Description
type	yes	Possible values for type: 0, 1, 2, 3 This parameter specifies behaviour of the redirection page and can hold following values: 0 - Debug No action is taken after Adscore verification is completed. 1 - Iframing Target URL(stored in data parameter) is loaded inside an iframe instantly, while Adscore analyzes the visitor in the background and posts back results to our statistics system. 2 - Redirection Target URL(stored in data parameter) is prefetched instantly and the browser window will be redirected to the target URL once Adscore analysis completes. 3 - Active Filtering The data parameter stores separate URLs to redirect to for both valid and invalid traffic. After Adscore completes the analysis, it will decrypt the correct URL depending on the analysis result and instruct the browser to redirect to it.
apikey	yes	It is the same as the apikey for Adscore JavaScript Engine.
referrer	no	Possibe values: origin, no-referrer Default: origin When set to no-referrer, the redirection to the target URL will not carry referrer header (ie. blank referrer).

Passing Adscore Signature to target URL

A common usecase for Adscore Links is buying traffic from an advertising network, sending it through Adscore and then redirecting it to a tracker. This setup requires to pass some dynamic parameters (like SubID) through Adscore, into the tracker.

Passing-through tracking parameters to Iframing and Redirection type links

For example, let’s say that you are currently buying traffic to:

https://example.com/?subid={subid}&campaign={campaign}

The dynamic parameters of {subid} and {campaign} are automatically replaced by your advertising network with correct values. If you try to use that URL in Adscore Link Generator, you will get:

https://c.adsco.re/r#apikey=Qr9sAAAAAAAAmpBBUxwssIgDgG9kpKa8rSlW4rI&sub_id={subid}&type=2&data=https%3A%2F%2Fexample.com%2F%3Fsubid%3D%7Bsubid%7D%26campaign%3D%7Bcampaign%7D

As the dynamic parameters have been encoded (as our system is unable to tell which part of the URL is a dynamic parameter), they will not work and will have to be manually corrected to:

https://c.adsco.re/r#apikey=Qr9sAAAAAAAAmpBBUxwssIgDgG9kpKa8rSlW4rI&sub_id={subid}&type=2&data=https%3A%2F%2Fexample.com%2F%3Fsubid%3D{subid}%26campaign%3D{campaign}

This way, dynamic tags like {subid} or {campaign} will be correctly recognized and replaced by your advertising network. This in turn will allow you to perform correct tracking. Passing-through tracking parameters to Active Filtering links While the situation with Iframing and Redirection link types was fairly easy, as the destination URL is part of Adscore URL, the situation with Active Filtering is a bit more complex. For example, let’s say that you are currently buying traffic to:

https://example.com/?subid={subid}&campaign={campaign}

With Adscore, you may want valid traffic to be sent to the URL above, but all invalid traffic to be sent to

https://example.com/?passback=1

Adscore Link Generator with such configuration will yield a URL like this:

https://c.adsco.re/r#apikey=Qr9sAAAAAAAAmpBBUxwssIgDgG9kpKa8rSlW4rI&sub_id={subid}&type=2&data=AALlWJ55fHXs4eA8ldv-eB0cqYdcYTjW5ubqlRffMbZ4kM9Er0nO5E_SSSNCzaqeddLgxPxom7lyFeMCuz0Ck0y-MNUIYHYfmpOFbDF8CmbYuNqxcjuiD0NHOq_hoeudQciwHXjoH0yNI9LPM-uGMOpx

Even in such a case, Adscore allows to replace dynamic tags like {subid} or {campaign}, even if they are encrypted. This can be achieved by appending extra parameters to the end of Adscore URL, for example:

https://c.adsco.re/r#apikey=Qr9sAAAAAAAAmpBBUxwssIgDgG9kpKa8rSlW4rI&sub_id={subid}&type=2&data=AALlWJ55fHXs4eA8ldv-eB0cqYdcYTjW5ubqlRffMbZ4kM9Er0nO5E_SSSNCzaqeddLgxPxom7lyFeMCuz0Ck0y-MNUIYHYfmpOFbDF8CmbYuNqxcjuiD0NHOq_hoeudQciwHXjoH0yNI9LPM-uGMOpx&subid={subid}&campaign={campaign}

This way, when your traffic source sends you an impression, these dynamic tags will be replaced with actual values:

https://c.adsco.re/r#apikey=Qr9sAAAAAAAAmpBBUxwssIgDgG9kpKa8rSlW4rI&sub_id=1234&type=2&data=AALlWJ55fHXs4eA8ldv-eB0cqYdcYTjW5ubqlRffMbZ4kM9Er0nO5E_SSSNCzaqeddLgxPxom7lyFeMCuz0Ck0y-MNUIYHYfmpOFbDF8CmbYuNqxcjuiD0NHOq_hoeudQciwHXjoH0yNI9LPM-uGMOpx&subid=1234&campaign=8888

When handling such URL, Adscore will:

Decrypt correct URL (either the one for valid or invalid traffic, depending on detection result).
Go through all the Adscore Parameter URLs, for example subid or campaign.
For each such parameter it will replace {parametername} with its value. For example it will replace {subid} in the valid traffic URL to 1234.

You may have noticed that the {subid} dynamic token is used twice in the last URL. The reason is that first it is the value of the sub_id parameter ( sub_id={subid} ), which is Adscore JavaScript Engine option that allows Adscore to track traffic by SubId. Then, there is second use of {subid} as value of parameter subid ( subid={subid} ) which is only used to replace the {subid} parameter inside the valid traffic URL.

Warning: Content of dynamic URL parameters (ie. the value to which {subid} might be replaced to) should not contain any special characters or it should be URL encoded.

Basics of implementation

Adscore JavaScript API is the most flexible solution allowing most implementation customizations and configuration. The most basic implementation looks as follows:

<script src="//c.adsco.re" type="text/javascript"></script>
    <script type="text/javascript">
    AdscoreInit("API-ZONE-KEY", {});
    </script>

First of all, Adscore JavaScript Engine has to be loaded - that is done in the first line of code:

<script src="//c.adsco.re" type="text/javascript"></script>

While in this example it is executed synchronously, depending on your use case, it might be reasonable to load it asynchronously to improve your website performance, for example:

<script src="//c.adsco.re" type="text/javascript" onload='AdscoreInit("API-ZONE-KEY", {});'></script>

One important scenario to consider is that Adscore JavaScript Engine (https://c.adsco.re/ URL) might be blocked by some Adblock lists. In such a case, Adscore cannot work. In near future, we expect to provide users an option to use Adscore on a custom domain, which will resolve the problem. In the meantime, it might be beneficial for you to detect when our script is blocked by Adblock - this can be achieved using onerror event(in most cases), for example:

<script src="//c.adsco.re" type="text/javascript" onload='AdscoreInit("API-ZONE-KEY", {});' onerror='alert("Disable Adblock!");'></script>

Once the Adscore JavaScript Engine is loaded, it exposes exactly one function:

function AdscoreInit(apikey, options)

Parameters:

Name	Required	Description
apikey	yes	This parameter is the Zone API Key which you can get from Zone Encryption Details in the Adscore panel. It identifies your zone for statistics, configuration and billing purposes.
options	no	A JavaScript objects holding key-value style configuration, for example: `{"sub_id": "1234"}`

Adscore JavaScript Engine options

The options parameter of AdscoreInit has multiple options that you can use to change the behaviour of the detection process or to supplement Adscore with additional data.

Name	Required	Description
sub_id	no	This parameter allows you to pass a custom subid value to allow you to separately track different traffic sources within one zone. Passing subid also activates additional detection modules.
callback	no	function callback(result) This callback function is executed once the Adscore verification is completed and has the result as the only parameter - it is a JavaScript object containing details of the detection: `result={ signature: "...", data: "...", error: 0 }` It contains following objects: signature Adscore cryptographic signature is a detection result. Once you receive it, you can send it to your backend and decode it with one of many libraries we are providing. data In case data option was used, it will contain the decrypted string. error Error code if something goes wrong - 0 should be returned in case there is no error. The Adscore JavaScript Engine can be used without utilizing the callback. In such mode, it will operate in a similar way to Google Analytics tag - it will do the visitor verification and send the result to our backend and you will be able to review statistics in our panel.
request_signature	depending on zone settings	Request signing allows you to defend your Adscore account from malicious attempts to drain your Adscore account balance by DDOSing your Adscore URL. You will need to calculate individual request signatures for each verification basing on Zone Request Key found in Zone Encryption Details panel, visitor’s IP address and User Agent. This parameter is required in case you enable the Request Signature Required option in the Zone Crypto Details panel.
data		Adscore has a capability of doing conditional decryption of arbitrary data. This for example allows you to encrypt your email and set the data option to the encrypted payload. Then, only for valid traffic, Adscore will decrypt it and provide it in the callback so you can display it to the user. This feature is also used in our Active Filtering implementation method.
ipv6_priority	no	Possible values: 0, 1 Default: 0 By default, Adscore works on IPv4 with additional IPv6 gatherer. This means that Adscore will always know the visitor IPv4 address and in most cases, if visitor has it, IPv6 address. In case you use Adscore Signature to verify traffic in your backend and your website uses IPv6, there is a possibility that our system will see only the IPv4 address (and use it for the signature) and your system will see only the IPv6 address. In such a case, the signature verification will fail. To resolve this problem, you can set ipv6_priority to 1 which will force Adscore to work on IPv6 as the primary visitor address.
lite	no	Possible values: 0, 1 Default: 0 Some Adscore client-side modules which test visitor’s hardware, mainly GPU, tend to be time and resource consuming. On modern devices they usually take a couple hundred milliseconds, however in some cases this can take up to a few seconds (for example virtual machines). Setting the lite parameter to 1 will disable these modules, which will lower the detection quality (in certain, rare cases), but will reduce the client-side processing time by around 70% on average. Please make sure to set Allow Adscore Lite Processing in Zone Settings to Yes. Failing to do so will result in all traffic to be detected as bot.
async_callback	no	Possible values: 0, 1 Default: 0 By default, Adscore Javascript module will first gather all necessary data, then send it to our backend and then wait for the backend response to be able to provide you Adscore Signature through the callback. In some cases however, the signature is not necessary so waiting for the backend response is not needed either. In such a case, setting async_callback to 1 will make our code send data to our backend using navigator.sendBeacon, allowing us to speed up client-side processing. Your callback will be executed immediately after data is queued to be sent to our backend, but obviously will not have any values in the result object. However, doing so will also make it not possible for our system to cache verification results. This means that all subsequent hits by the same visitor will require full analysis to be repeated each time, which will not be optimal from a performance point of view. For this reason, the async_callback option should only be used on unique traffic, where one visitor is verified only once.

Example

<script src="//c.adsco.re" type="text/javascript"></script>
<script type="text/javascript">
AdscoreInit("QpUJAAAAAAAAGu98Hdz1l_lcSZ2rY60Ajjk9U1c", { sub_id: "123", lite: 1, callback: function(result)
{ alert('Adscore Verification is completed!'); } }); </script>

Adscore Signature Verification

Once you receive Adscore Signature from the callback, you need to verify it serverside. We provide libraries for popular backends to achieve that:

PHP
https://github.com/Adscore/client-libs-php

Java
https://github.com/Adscore/client-libs-java
https://github.com/Adscore/client-libs-java-samples

.NET
https://github.com/Adscore/client-libs-net

Node.JS
https://github.com/Adscore/client-libs-node

Adscore does not provide detection result in plain text, as any bot could simply overwrite the result to identify itself as a valid visitor rendering Adscore useless. Apart of that, providing you the result in form of signature ensures that only you can decode it (so your Adscore zone cannot be used by someone else).