Skip to main content
Sign in Homepage

Server lookup full specification

Support
  • Updated

The detections endpoint allows a customer to retrieve Opticks visit detections given a unique lookup id. The unique lookup id is defined by the customer when inserting the OpticksJS snippet into a landing page.

Please contact your account manager if this feature is of interest.

Use case

This endpoint is expected to be used in the following manner:

  1. User visits a page containing OpticksJS.
  2. User moves on to a second stage, perhaps a form submission or purchase event.
  3. Customer calls the Opticks detections endpoint before allowing step 2 to occur. If Opticks detections are clean, allow step 2 to complete. If Opticks detections are unacceptable OR NOT FOUND, interrupt step 2 as required.

OpticksJS setup

In order to use the detections endpoint, you must first configure the OpticksJS snippet properly. The key piece to this setup is sending Opticks your unique lookup id in the opticks_lookup_id key. The unique lookup id will later be used to retrieve the detections from the detections endpoint.

N.B. Only the first opticks_lookup_id will be stored. Any subsequent requests with the same id will be discarded.

Snippet format

<script 
src="https://opticksprotection.com/o/{CAMPAIGN_HASH}?subpublisher_id={URLPARAM1}&var1={URLPARAM2}&version=v3&opticks_lookup_id={UNIQUELOOKUPID}">
</script>

N.B. Remember that the snippet must be placed in the HTML <head>.

Example snippet

<script 
src="https://opticksprotection.com/o/4734632235345?subpublisher_id={URLPARAM1}&var1={URLPARAM2}&version=v3&opticks_lookup_id=9278cfa4-7ac7-4691-a867-98518ef666df">
</script>

Authorization

You should whitelist domains which are allowed to host the javascript snippet. Additionally, your account must be configured to use this detections endpoint. Please speak to your account manager about this.

Endpoint

  • Endpoint URL: https://api.optickssecurity.com/analysis/find
  • HTTP method: GET
  • Query parameters: lookupId
  • Authentication: See https://developers.optickssecurity.com/#section/Authentication
  • Data TTL: 30 minutes.
    • This endpoint is designed to make it easier for you to get real time detection information, therefore the data is stored for only 30 minutes. Please see our HITS endpoint where you can retrieve visit information for up to 15 days using the Opticks clickid as the lookup value.
  • Responses:
    • 200: Success
    • 204: No content - token ok, lookupid not found
    • 401: Unauthorized
    • 500: Internal server error

Request sample

curl -X GET \
'https://api.optickssecurity.com/analysis/find?lookupId=9278cfa4-7ac7-4691-a867-98518ef666df' \
-H 'Authorization: {your_token}'

Response sample

{
    "invalidClickReasons": [],
    "analysis": {
        "level": "high",
        "detections": [{
            "group": {"id": 2,"group": "Header Injections"},
            "triggers": [{
                "id": 11,"trigger": "MSISDN Injection"
            }]
        }, {
            "group": {"id": 6,"group": "Iframe"},
            "triggers": [{
                "id": 30, "trigger": "Tiny Iframe"
            }]
        }, {
            "group": {"id": 3,"group": "Harmful applications"},
            "triggers": [{
                "id": 14,"trigger": "Offer not rendered"
            }, {
                "id": 15,"trigger": "Malicious code found"
            }]
        }]
    },
    "opticksClickId": "track_20180831102904_4209d1c2_63c2_4fb2_af40_ae2eae08fd10",
    "delivered": true,
    "fallbackUrl": null,
    "ts": 1535711344986,
    "version": 3
}

🔴  Do not accept repeat Opticks clickids or your opticks_lookup_ids. Clickids are unique and should never repeat.
🔴  Ensure that the the invalidClickReasons array is empty.
🔴  Be sure that the encrypted timestamp is reasonable. For example, less than 5 minutes old.

Related articles

Comments

0 comments

Please sign in to leave a comment.