Skip to main content
Sign in Homepage

OpticksJS full specification

Support
  • Updated

In this guide you will find the most detailed documentation for OpticksJS integration.

Introduction

The OpticksJS visits integration is performed by inserting a small piece of code to the header of your website. This piece of code will then connect to the Opticks servers, analyze each visitor, and decide if they should be allowed to continue, based on the rules you've set up for your campaign on the Opticks website

Similarly, the OpticksJS conversions integration is performed by inserting a small piece of code to the conversion event at your webpage. This piece of code will inform Opticks that a conversion has been made

The insertion of these pieces of code can be made either directly to the webpage itself or by using a Tag manager (Google Tag Manager, Adobe Tag Manager, etc.).

Instructions to Integrate 

The following instructions are applicable if you integrate directly on your webpage.

If you use a Tag Manager, you can find more detailed instructions here. 

Integrate Visits 

This integration option requires the OpticksJS script to be included in your website’s head as follows:

<head>
 <script 
  src="https://opticksprotection.com/o/{CAMPAIGN_HASH}">
 </script>
 ...
</head>

Get the CAMPAIGN_HASH from the Sensor JS snippet that the Opticks platform generates. 

(Optional) Adding extra information to the visit 

You can add extra information as URL params in the Sensor JS script and and Opticks will replace any text in brackets (macro) with the value of that URL parameter storing it in the analysis.

For example, you can fill the subpublisher_id parameter in the URL with your own values. This mapping will allow you to view subpublisher statistics via the Opticks Analytics as follows.

 <script
  src="https://opticksprotection.com/o/YOURCAMPAIGNHASH?subpublisher_id={source}">
 </script>
...
</head>

Additionally, you can use var1 var2 var3 and var4 parameters to store custom information.

via the Sensor JS script as follows.

 <script
  src="https://opticksprotection.com/o/YOURCAMPAIGNHASH?subpublisher_id={source}&var1={affiliate_id}">
 </script>
...
</head>

(Optional)Retrieving the response event

It is optional to listen to this event. If you want to track conversions or use the v2 or v3 encrypted response then it is necessary.

OpticksJS will emit an opticksEvent event when it has finished processing the visit. You can listen for the event with the following code:

<script>
 window.addEventListener('opticksEvent', function (event) {
  opticksId = event.detail.opticksClickId;
 }, true);
</script>

Response format

The response allow you to receive detailed information about the detections Opticks has uncovered. The data is provided in an encrypted format. Note that if a visit contains detections that the Campaign's security settings indicate should be blocked, the visitor will be redirected and no detections will be delivered.

{
 "opticksClickId": "track_20180528004215_a4bdb381_fe23_40ab_8202_ec3029bf8bd2",
 "data": "Base64 encoded, AES-128-CBC encrypted JSON string using 16 character Initialization Vector (IV). The IV will be the last 16 characters of the opticksClickId.",
 "hmac": "Base64 encoded keyed-hash message authentication code"
}

Ask our team for the documentation to decode the payload in the "data" and "hmac" parameters if you need to do so.

Integrate Conversions

Even when using the OpticksJS integration option, conversions can be reported to Opticks servers.

This is really recommended as it is a valuable information that our machine learning Algorithms can use to harden consequent analysis in the Protected Page. Additional development by the customer is necessary and can vary from one scenario to another. Here is some information and examples for sending Opticks conversion information when using the JS integration.


Getting the click_id

In order for Opticks to integrate conversions, your platform would need to send one conversion postback to Opticks with the Opticks click_id. In order to get the Opticks click_id, you need to capture the response from the OpticksJS script. Then you must fire the Opticks postback when your click_id converts.

Here is an example of one of the multiple ways you can use to capture the response from the OpticksJS and send it to your servers:

<script>
  window.addEventListener('opticksEvent', function (event) {
    var opticksCheck = document.createElement('input');
    opticksCheck.type = 'hidden';
    opticksCheck.name = 'opticks';
    opticksCheck.value = event.detail.opticksClickId;
    document.querySelector('form').appendChild(opticksCheck);
  }, true);
</script>

In the above example, we have added the Opticks click id to a hidden form field, which your server will receive when a form is submitted. If you are not sending forms then your implementation will be a bit different.

Firing the postback

The Opticks postback should be sent to: 
https://opticksstatic.com/conversion?click_id={opticks_click_id} as a GET request. You can check your custom_domain in any of the Offers you set up on your Opticks Back Office, it will be the same domain where you load your Opticks script from. 

It's also possible, to fire postbacks on the client side. This is useful when firing conversion pixels in a "thank you page" when the user finished the flow and has converted. 

<img src=https://opticksstatic.com/conversion?click_id={opticks_click_id}      height="1" width="1" style="display:none" />

OpticksJS flow overview

Flows__13_.png

1. OpticksJS loads and performs analysis

2.a. Analysis arrives to Opticks servers and optional blocking or redirecting logic is applied by OpticksJS.

2.b. Analysis is returned from Opticks servers to client side and some optional blocking logic is applied on client side.

3. Further user events are harvested and feed to the algorithm. (This Events module must be activated separately).

4. User initiates the action to convert.

5. The conversion is accepted.

6. The conversion is reported to Opticks. This feedback is used as an input for the algorithms.

 

warning-icon.png  Due to the asynchronous nature of the Javascript language, in some extreme cases, the OpticksJS integration might fail in preventing some advanced fraud schemes. In the section limitations you can find a list of limitations for this type of integration and actions you can take to offset its associated risks  

 

Limitations of OpticksJS integration

Possible failure to block fraudulent visits

A fast-acting fraudulent bot could potentially act before OptickJS finishes executing. This is due to the asynchronous nature of Javascript. Since the webpage continues to be rendered while OptickJS executes, there is potential for someone to click on the subscribe button during the few milliseconds before OpticksJS acts.

Malicious code could also completely block access to Opticks servers, thereby disabling OptickJS.

One possible way to mitigate these risks is by hiding the web content until OpticksJS responds. A callback function could unhide the web content upon a successful response from Opticks. Or, the OpticksJS response could be sent to the server upon a conversion attempt and verified before allowing the conversion.

Automatic Front end reporting

The Opticks Back Office is able to display traffic statistics by Traffic Source but this feature will lose effectiveness since with OpticksJS all traffic is coming from the same Protected Page where the snippet is inserted. 

It's very common to still need to store some data about the sources who are sending traffic to the Protected Page, e.g. all the utm_ variables, affiliate ids, etc... You can use the var1 var2var3 or var4 custom variables to store this kind of data. Keep in mind that this data can't be visit identifiers or identifiers that are meant to be unique.

<head>
  <script
    src="https://opticksprotection.com/o/{campaign_hash}?subpublisher_id={source}&var1={affiliate_id}&var2={utm_content}">
  </script>
  ...
</head>

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.