Skip to main content

Opticks Sensor SDK

Overview​

The Opticks Sensor SDK provides an advanced way to integrate an Opticks sensor into your site and analyze your traffic. Using this method, you have more control over what happens and when it happens. It is an alternative to the basic integration via the Sensor Tag, which just runs an scan when the script is loaded.

The SDK works similarly to tracking pixels and SDKs for other services: it is loaded asynchronously through a lightweight bootstrap snippet, and once loaded, the SDK exposes a global queue‑based API (opticks(...)) that allows you to:

  • Initialize the SDK with your sensor
  • Trigger scans
  • Send conversions (optional)

Installation​

Add the following snippet to your site’s <head> or end of <body>:

<script>
(function(o,p,t,i,c,k,s){
  o[i]=o[i]||function(){(o[i].q=o[i].q||[]).push(arguments);};
  k=p.createElement(t);k.async=1;k.src=c;
  s=p.getElementsByTagName(t)[0];s.parentNode.insertBefore(k, s);
})(window,document,'script','opticks','https://opticksprotection.com/sdk.js');

opticks('init', "__YOUR_SENSOR_HASH__");
</script>

Replace:

  • __YOUR_SENSOR_HASH__ → Your Opticks sensor hash. See Initialization for more details.

API Reference​

The SDK exposes a single global function, which you can use to execute commands even before the SDK script has finished loading (in which case they will be queued):

opticks(command, parameters?)

Supported Commands​

CommandDescription
"init"Initializes the SDK with your sensor hash.
"scan"Runs an opticks scan (analysis) for the current visitor, asynchronously.
"conversion"Sends a conversion event.
"parameters"Manually add extra parameters/macros to scans and conversions.

Initialization​

opticks('init', '__YOUR_SENSOR_HASH__');

This initializes the sensor using the given Opticks Sensor hash. You can get the sensor hash from the Setup Center inside the Opticks app, by clicking on the gear icon of a sensor to see the sensor tag.

The init must be called before any other command. If called multiple times, only the first sensor will be configured, and any further calls will be ignored.

Running a Scan​

opticks('scan');

This triggers an opticks scan (also known as analysis). The scan is an asynchronous operation, so if you want to access the result you will need to pass a callback.

Example with a callback, which also adds macros manually:

opticks('scan', {
    parameters: { var1: 'my_custom_value' },
    callback: function(result) {
        console.log('Scan result:', result);
    },
});

Scan options​

interface ScanOptions {
    once?: boolean;
    parameters?: Record<string, string>;
    callback?: (result: ScanResult) => void;
}
OptionTypeDefaultDescription
oncebooleanfalseIf true, the SDK will ensure only one scan runs for the current page-view. Can be used to protect against race conditions if you only want one scan.
parametersRecord<string,string>—Extra macros (e.g., utm_source, var1). Note that scans automatically include any query parameter from the current page URL as macros.
callback(result) => void—Called asynchronously when the scan completes. Use this to access the scan result, or the Opticks id for the visit.

Scan result object​

interface ScanResult {
    opticksClickId: string;
    s: string | null;
    p: boolean;
}
FieldDescription
opticksClickIdThe Opticks page-view ID.
sThe Opticks session ID.
pWill be true if the visit is determined to be invalid, according to the Opticks risk score plus the sensor settings.

Sending a Conversion​

opticks('conversion');

You can use this to mark this visit as converted, so it will display as a conversion inside the Opticks app.

By default only one conversion will be allowed per each session per each pageview. You can force multiple via the parameters documented below.

Example to support multiple conversions per visit:

opticks('conversion', { txid: 'signup' });

opticks('conversion', { txid: 'checkout' });

Conversion options​

interface ConversionOptions {
    force?: boolean;
    txid?: string;
}
OptionTypeDescription
forcebooleanIf true, allows sending multiple conversions for a single page-view. Otherwise a "dedup" will be applied so only the first conversion will be kept (the default behavior).
txidstringCan be used to specify a type of conversion (e.g. "signup", "checkout"). Only the first conversion of each type will be registered for a given page-view (unless force is also used).

Adding additional macros / parameters​

opticks('parameters', {});

You can use the parameters command to manually add extra custom parameters (also known as macros, inside Opticks app). These will be included in any scan or conversion triggered from that point onwards.

Note that Opticks will automatically include all query parameters in the current page URL as macros.

This command can be used for convenience to add dynamic information, such as form fields values; and from any place in your code, while still not triggering yet the scan/conversion.

Example:

opticks('parameters', {
    var1: 'my_custom_value',
    utm_campaign: 'spring_sale',
});

Full integration example​

  1. Initialize the SDK:
(function(o,p,t,i,c,k,s){
  o[i]=o[i]||function(){(o[i].q=o[i].q||[]).push(arguments);};
  k=p.createElement(t);k.async=1;k.src=c;
  s=p.getElementsByTagName(t)[0];s.parentNode.insertBefore(k, s);
})(window,document,'script','opticks','https://opticksprotection.com/sdk.js');


opticks('init', "__YOUR_SENSOR_HASH__");
  1. Run a scan (on page load, or wherever else you want to):
opticks('scan');

// Alternatively, if you want to read the result:
opticks('scan', {
    callback: function(result) {
        // read the opticks id:
        // result.opticksClickId;

        // do something if the visit is invalid:
        // if (result.p) { ... }; 
    }
});

  1. (optional) Trigger a conversion (e.g. on signup, or checkout success):
opticks('conversion');