Custom Events¶

Part of the Human Scoring use case.

Mark meaningful moments in your app on the session timeline — a level starting, a form step completing, a checkout opening. Custom events annotate the session. Their names and data never count toward the score or the classification, so they cannot be used to make a session look more human.

Note: The session timeline stays on the device. The iOS SDK sends no captured input to DEA, custom events included — see Privacy and network.

When to use it¶

To mark the steps of a flow: checkout_open, payment_submit
To mark game or task boundaries: level_start, round_end

Prerequisites¶

The SDK is installed and started. See the Quick Start.
The user has consented. Events are not recorded before consent.

Usage¶

Record an event¶

import DeaSDK

_ = Dea.sdk?.captureEvent("level_start")

captureEvent returns true when the event was recorded and false when it was refused (see Limits). Assign the result to _ when you do not need it.

Record an event with data¶

import DeaBase
import DeaSDK

_ = Dea.sdk?.captureEvent("level_start", data: ["level": 3, "mode": "hard"])

data is a [String: JSONValue]. String, integer, floating-point and Boolean literals convert automatically; use .array([...]), .object([...]) and .null for the rest:

import DeaBase
import DeaSDK

let data: [String: JSONValue] = [
    "level": 3,
    "speed": 1.5,
    "assisted": false,
    "items": .array(["sword", "shield"]),
    "position": .object(["x": 10, "y": 20]),
]
_ = Dea.sdk?.captureEvent("checkpoint", data: data)

Limits¶

	Limit	If exceeded
Name	1 to 64 characters	The whole event is refused
Data	1024 bytes as JSON	The whole event is refused

A refused event returns false and nothing is recorded; names are never shortened. Events are also refused while capture is paused, before consent, and after dispose().

Do not put personal information in names or data.

Examples¶

Mark the rounds of a game¶

import DeaBase
import DeaSDK

final class GameController {
    private var round = 0

    func startRound() {
        round += 1
        _ = Dea.sdk?.captureEvent("round_start", data: ["round": .int(round)])
    }

    func endRound(won: Bool) {
        _ = Dea.sdk?.captureEvent("round_end", data: ["round": .int(round), "won": .bool(won)])
    }
}

Values held in variables are wrapped explicitly: .int(_:), .double(_:), .string(_:), .bool(_:).

API¶

Member	Returns	Description
`captureEvent(_:data:)`	`Bool`	Records an event on the session timeline; `false` when refused