Due to language differences, the API will differ slightly between platforms, but in general, it provides the following methods:

Message Callback

The message callback is a callback function that the analytics library will invoke when there is a response action payload available from the security analytics library. It defines a single method which when invoked, will be passed the response action payload JSON string.

Response Action Processing and Application State Handling

Due to the nature of the response actions and how they arrive from the Verimatrix XTD analytics backend, some consideration is needed in the application layer.

Response actions can be divided into 2 categories: an immediate, single action or a long-term, persistent action. If the action is an immediate, single action, the application can process the response action immediately and then not store any state. Long-term, persistent actions should be persisted in the session and the action enforced until a successful pair of connection established/closed events have been received without receiving another action, of the same type, in that connection window. Below shows an example of how this would work for the degrade action.

Error Handling & Error Codes

The sendMessage API will throw exceptions if there is something wrong with the JSON payload being sent. In addition, the message callback, mostly used to deliver response actions from the analytics agent, also delivers error messages back to the protected application if they happen asynchronously within the application.

Response Action Payloads

Payload Format

The general format of the response action payloads are as follows. The JSON is passed as is to the application as a string.

{
  "c":1,
  "v":1,
  "p" : { "some" : "command specific payload data"}
}

JSON Schema

The following defines the JSON schema for the action payloads.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://verimatrix.com/xtd/response-actions-payloads/2025-01/schema.json",
  "title": "Verimatrix XTD Response Actions Payloads",
  "description": "Describes response actions payloads used when interacting with Verimatrix secure analytics library (SAIL)",
  "properties": {
    "c": {
      "description": "Defines the management action this payload carries.  ",
      "enum": [1, 2, 3, 6]
    },
    "v": {
      "description": "Indicate the version of the payload being carried",
      "enum": [1]
    },
    "p": {
      "oneOf": [
        {
          "type": "object",
          "properties" : {
            "spuid" : {
              type: "string"
            },
            "version" : {
              "type" "number"
            }
          }
          "required" : ["spuid", "version"]
          "additionalProperties": false
        },
      ]
    },
    "additionalProperties": false
  },
  "required": ["c", "v"],
  "additionalProperties": false
}

Response Action Types

The following action types are currently in use:

Further detail of each action type is described below.

Connection Established

{
"v" : 1,
"c" : 1
}

Connection Close

{
"v" : 1,
  "c" : 2
}

Degrade

{
  "v" : 1,
  "c" : 3
}

Provision VUIT

{ 
  "v" : 1,
  "c" : 6,
  "p" : {
    "version" : 1,
    "spuid" : "SP::<VUIT Data>"
  }
}