API reference

Plugin Telemetry API

Record package UI activity without confusing caller-reported telemetry with customer licensing proof.

Start with getting started Explore API docs

Telemetry is not authorization

Use POST /api/plugin-connections/events for package open and UI activity. /event is a compatibility alias. These calls authenticate the generated product identity; they do not activate a device, validate customer ownership or unlock audio. A caller-provided status such as valid cannot turn a UI event into server-recorded activation or validation evidence.

Send the product identity in JSON

Supply productId and appId with either the standard pluginKey/pluginSecret or the generated hise-native/juce-native publicClient identity. This endpoint reads body fields rather than licensing headers. Snake-case identity fields and version/environment aliases are supported. Keep developer, customer and partner tokens out of this request.

Choose a safe event

Use opened, ui_click, webview_opened or webview_click. click and button_click normalize to ui_click, plugin_opened to opened, and webview_clicked to webview_click. Unknown event types become ui_click, not a licensing event. action, element and screen describe the UI; metadata should contain only minimal non-personal diagnostics. Never send customer names, emails, serials, passwords or tokens.

Understand the result and side effects

201 means an event row was returned. 202 with recorded:false means no event row was returned; neither response grants customer access. The handler verifies and refreshes product-connection history, attempts event recording and an engagement signal. It is not a zero-write health check and has no event idempotency guarantee. Avoid blind retries that duplicate engagement. Authentication and product mismatch failures use the returned code/error; storage or recording errors are not a reason to unlock the product.

SoundSync

Illustrative native UI event

Product activity, not customer authorization

curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/plugin-connections/events" \
  -H "Content-Type: application/json" \
  --data '{"productId":123,"appId":"GENERATED_APP_ID","publicClient":"juce-native","eventKind":"opened","action":"runtime_loaded","screen":"runtime","environment":"production"}'

SoundSync

Requests and responses

POST /api/plugin-connections/events

Record product UI telemetry

Auth: JSON body credential check. Headers are not used for this endpoint.
Scope: Product/app binding; standard key/secret or generated native public-client identity. No customer licensing authority.
Request fields: productId: integer
product_id: integer
appId: string
app_id: string
pluginKey: string
plugin_key: string
pluginSecret: string
plugin_secret: string
appKey: string
app_key: string
appSecret: string
app_secret: string
publicClient: hise-native | juce-native
public_client: hise-native | juce-native
pluginVersion: string
plugin_version: string
version: string
environment: string
env: string
eventKind: string
event_kind: string
type: string
action: string
element: string
screen: string
status: string
metadata: object
Returns: HTTP 201: ok, recorded, event.
Notes: Authentication is read from JSON body, not a developer/customer Bearer token. Supply standard product key/secret or the matching generated native publicClient/app/product identity. Canonical event types: opened, ui_click, webview_opened, webview_click. click/button_click normalize to ui_click; plugin_opened to opened; webview_clicked to webview_click; unknown types also become ui_click. Status and metadata are caller-reported, not customer authorization. Verifies/refreshes product connection history, records an event and attempts an engagement signal. 202 recorded:false means no event row was returned, not a licensing grant. No idempotency guarantee; retries can duplicate engagement. Never include personal data, serials or credentials in metadata. /event is a compatibility alias.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "appId": {
      "type": "string"
    },
    "app_id": {
      "type": "string"
    },
    "pluginKey": {
      "type": "string"
    },
    "plugin_key": {
      "type": "string"
    },
    "pluginSecret": {
      "type": "string"
    },
    "plugin_secret": {
      "type": "string"
    },
    "appKey": {
      "type": "string"
    },
    "app_key": {
      "type": "string"
    },
    "appSecret": {
      "type": "string"
    },
    "app_secret": {
      "type": "string"
    },
    "publicClient": {
      "enum": [
        "hise-native",
        "juce-native"
      ]
    },
    "public_client": {
      "enum": [
        "hise-native",
        "juce-native"
      ]
    },
    "pluginVersion": {
      "type": "string"
    },
    "plugin_version": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    },
    "env": {
      "type": "string"
    },
    "eventKind": {
      "type": "string"
    },
    "event_kind": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "action": {
      "type": "string"
    },
    "element": {
      "type": "string"
    },
    "screen": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "additionalProperties": true,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "productId"
          ]
        },
        {
          "required": [
            "product_id"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "appId"
          ]
        },
        {
          "required": [
            "app_id"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "publicClient"
          ]
        },
        {
          "required": [
            "public_client"
          ]
        },
        {
          "allOf": [
            {
              "anyOf": [
                {
                  "required": [
                    "pluginKey"
                  ]
                },
                {
                  "required": [
                    "plugin_key"
                  ]
                },
                {
                  "required": [
                    "appKey"
                  ]
                },
                {
                  "required": [
                    "app_key"
                  ]
                }
              ]
            },
            {
              "anyOf": [
                {
                  "required": [
                    "pluginSecret"
                  ]
                },
                {
                  "required": [
                    "plugin_secret"
                  ]
                },
                {
                  "required": [
                    "appSecret"
                  ]
                },
                {
                  "required": [
                    "app_secret"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "recorded": {
      "type": "boolean"
    },
    "event": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 500.

POST /api/plugin-connections/event

Record product UI telemetry using the compatibility alias

Auth: JSON body credential check. Headers are not used for this endpoint.
Scope: Product/app binding; standard key/secret or generated native public-client identity. No customer licensing authority.
Request fields: productId: integer
product_id: integer
appId: string
app_id: string
pluginKey: string
plugin_key: string
pluginSecret: string
plugin_secret: string
appKey: string
app_key: string
appSecret: string
app_secret: string
publicClient: hise-native | juce-native
public_client: hise-native | juce-native
pluginVersion: string
plugin_version: string
version: string
environment: string
env: string
eventKind: string
event_kind: string
type: string
action: string
element: string
screen: string
status: string
metadata: object
Returns: HTTP 201: ok, recorded, event.
Notes: Authentication is read from JSON body, not a developer/customer Bearer token. Supply standard product key/secret or the matching generated native publicClient/app/product identity. Canonical event types: opened, ui_click, webview_opened, webview_click. click/button_click normalize to ui_click; plugin_opened to opened; webview_clicked to webview_click; unknown types also become ui_click. Status and metadata are caller-reported, not customer authorization. Verifies/refreshes product connection history, records an event and attempts an engagement signal. 202 recorded:false means no event row was returned, not a licensing grant. No idempotency guarantee; retries can duplicate engagement. Never include personal data, serials or credentials in metadata. /event is a compatibility alias.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "appId": {
      "type": "string"
    },
    "app_id": {
      "type": "string"
    },
    "pluginKey": {
      "type": "string"
    },
    "plugin_key": {
      "type": "string"
    },
    "pluginSecret": {
      "type": "string"
    },
    "plugin_secret": {
      "type": "string"
    },
    "appKey": {
      "type": "string"
    },
    "app_key": {
      "type": "string"
    },
    "appSecret": {
      "type": "string"
    },
    "app_secret": {
      "type": "string"
    },
    "publicClient": {
      "enum": [
        "hise-native",
        "juce-native"
      ]
    },
    "public_client": {
      "enum": [
        "hise-native",
        "juce-native"
      ]
    },
    "pluginVersion": {
      "type": "string"
    },
    "plugin_version": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    },
    "env": {
      "type": "string"
    },
    "eventKind": {
      "type": "string"
    },
    "event_kind": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "action": {
      "type": "string"
    },
    "element": {
      "type": "string"
    },
    "screen": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "additionalProperties": true,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "productId"
          ]
        },
        {
          "required": [
            "product_id"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "appId"
          ]
        },
        {
          "required": [
            "app_id"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "publicClient"
          ]
        },
        {
          "required": [
            "public_client"
          ]
        },
        {
          "allOf": [
            {
              "anyOf": [
                {
                  "required": [
                    "pluginKey"
                  ]
                },
                {
                  "required": [
                    "plugin_key"
                  ]
                },
                {
                  "required": [
                    "appKey"
                  ]
                },
                {
                  "required": [
                    "app_key"
                  ]
                }
              ]
            },
            {
              "anyOf": [
                {
                  "required": [
                    "pluginSecret"
                  ]
                },
                {
                  "required": [
                    "plugin_secret"
                  ]
                },
                {
                  "required": [
                    "appSecret"
                  ]
                },
                {
                  "required": [
                    "app_secret"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "recorded": {
      "type": "boolean"
    },
    "event": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 500.