Skip to content

Telemetry

Telemetry is what the SDK reports while it runs: its log, one entry per step it takes, and the input it captures. On the staging and test packages your app receives both: the log through onLog, and the captured input through an integration of your own. Your code decides where they go; the SDK sends neither to DEA.

Staging and test packages only. The production package writes no log and does not set up your integrations, so nothing on this page reaches an app you release. DEA's collection transporter is the one exception: its stream delivery attaches on every package. See Collect Data.

When to use it

  • Watch what the SDK does while you integrate, in your own log screen or logging service
  • Record the raw input of test sessions for your own QA or analysis

Prerequisites

  • The staging packages are installed: see Install the staging packages. The test packages work the same way and also log DEBUG
  • Where requireConsent is true, the default, your testers agreed: see User Consent. Nothing is captured before they do

Usage

Install the staging packages

The staging SDK is three Swift packages, published as archives. From the folder that keeps your vendored packages:

mkdir -p Vendor/DEA && cd Vendor/DEA
for slot in base automation-detection sdk; do
  curl -sS "https://sdk.dep-protocol.com/0.26.0/staging/ios/$slot/dea-$slot-0.26.0.tar.gz" | tar -xz
done

This creates dea-base-0.26.0, dea-automation-detection-0.26.0 and dea-sdk-0.26.0 side by side. Each one names the others by those relative paths, so keep them together. A test app takes them from /test/ios/ instead of /staging/ios/.

Add dea-sdk-0.26.0 and dea-base-0.26.0 as local packages, and link the DeaSDK and DeaBase products to your app target. In a Package.swift:

dependencies: [
    .package(path: "Vendor/DEA/dea-sdk-0.26.0"),
    .package(path: "Vendor/DEA/dea-base-0.26.0"),
],
targets: [
    .target(name: "App", dependencies: [
        .product(name: "DeaSDK", package: "dea-sdk-0.26.0"),
        .product(name: "DeaBase", package: "dea-base-0.26.0"),
    ]),
]

Receive the log

Pass onLog to DeaSdkOptions. The SDK calls it with every entry, and still writes each entry to the unified log, subsystem ai.dea, category dea, which Xcode's console and Console.app show.

import DeaSDK

let dea = DeaSdk.initialize(options: DeaSdkOptions(
    appId: "YOUR_APP_ID",
    appKey: "YOUR_APP_KEY",
    onLog: { entry in myLogger.log(entry.levelText, entry.spec.name, entry.json) }))
dea.start()

myLogger stands for your own code. onLog runs on the thread that wrote the entry, which is often not the main thread. Return quickly, and use DispatchQueue.main.async before you touch your UI.

Each entry is a LogEntry:

Member Description
timestamp When the step happened, a Date
levelText DEBUG, INFO, WARN or ERROR
severityNumber The OpenTelemetry number of that level: 5, 9, 13 or 17
spec.name The step, for example sdk.ready or proof.not_signed
outcome ok, refused or failed
session The session id when the step happened
body One sentence that describes the step
attributes The step's values, as key and value pairs in a fixed order. attribute(_:) reads one by key
resource The SDK release (serviceVersion), osType ios, and the package (flavor: staging or test)

entry.line renders the entry as its unified log line. entry.json renders it as JSON with the OpenTelemetry field names: timestamp, severityText, severityNumber, eventName, body, attributes and resource. The iOS SDK has no option for the log level: the package sets it. Staging writes INFO and up, test writes every level.

Receive the captured input

An integration is a value that conforms to Integration, from DeaBase: a name and a setup(attach:session:) method. The SDK calls setup on the main thread, at the first start(). Each transporter you pass to attach receives every object the SDK captures, through its transport(_:) method. A transporter is a class that conforms to Transporter.

import DeaBase
import DeaSDK

final class CapturedInput: Transporter {
    private(set) var objects: [SchemaObject] = []

    func transport(_ object: SchemaObject) {
        objects.append(object)
    }
}

struct CaptureIntegration: Integration {
    let name = "my-capture"
    let sink: CapturedInput

    func setup(attach: @escaping (Transporter) -> Detach, session: SessionInfoProvider) {
        _ = attach(sink)
    }
}

let captured = CapturedInput()
let dea = DeaSdk.initialize(options: DeaSdkOptions(
    appId: "YOUR_APP_ID",
    integrations: [CaptureIntegration(sink: captured)],
    appKey: "YOUR_APP_KEY"))
dea.start()

attach returns a Detach closure that removes the transporter; call it on the main thread. session.sessionInfo answers the same as sessionInfo on the DeaSdk.

How the objects reach your transporter:

Rule Description
Order In capture order, a moment after capture, on the main thread. A slow transport holds up your UI and the other transporters
Queue limit 8192 objects for each transporter. Past that, new objects are dropped until the queue drains
Errors transport may throw. A transporter that throws 5 times in a row is detached. The test package logs each throw as pipeline.transporter_failed
Consent When the user withdraws consent, the objects still queued are discarded. The transporter stays attached and receives again once the user agrees
pause() Touch, motion and custom event objects stop until resume(). Lifecycle objects still arrive
Background When the app goes to the background, everything queued is handed over at once. flushQueues() does the same when you call it
reset() A new session starts. Queued objects keep the session they were captured in: read object.session
Automation stop With automationDetection on, a stop detaches every transporter and drops its queue. The reset() that lifts the stop calls setup again
dispose() Nothing more arrives. Objects still queued are dropped

Keep transport short: copy the object into your own buffer, and send from your own timer.

What an object holds

Every object is a SchemaObject. It carries schema, the version of its shape: 1, or 2 when you capture key events. It carries session, the session id, and device: the runtime, the operating system, the surface size in points, the pixelRatio, the rotation in degrees, maxTouchPoints and the motion sensorRate in Hz. Its record holds exactly one of these cases, which object.pointer, object.motion, object.lifecycle and object.custom also read:

Case When Fields
.pointer A touch, pencil, pointer, scroll or hover event, or a key your app reports with captureKey ts, kind (Kind), tool (PointerTool), buttons, position (x, y, in points on device.surface), primary, coalesced, and when they apply pointerId, scroll, force, contact, stylus, target, key (the KeyClass and modifiers, never the character)
.motion One motion sensor sample ts, acceleration (m/s², three axes, gravity removed), rotationRate (rad/s, three axes)
.lifecycle The app goes to the background or returns ts, state (LifecycleState)
.custom Your app records a custom event, or the SDK writes a marker: motion when the sensors are switched off or on, and names that start with dea. ts, name, data

ts is in microseconds since the session began; object.ts reads it for every case. Motion arrives at full rate near a touch, and one sample every idleMotionMs (3 seconds by default) otherwise. object.wire gives the object as JSON-ready values, and object.wireJSON as a JSON string. Kind, PointerTool, KeyClass, LifecycleState and the other types of the object are public in DeaBase.

Examples

Send test sessions to your own service

import DeaBase
import DeaSDK
import Foundation

final class QAForwarder: Transporter {
    private let endpoint = URL(string: "https://qa.example.com/dea-sessions")!
    private var buffer: [[String: Any]] = []
    private var timer: Timer?

    /// Create it on the main thread: the timer runs on the main run loop.
    init() {
        timer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { [weak self] _ in
            self?.send()
        }
    }

    func transport(_ object: SchemaObject) {
        buffer.append(object.wire)
    }

    private func send() {
        guard !buffer.isEmpty, JSONSerialization.isValidJSONObject(buffer),
            let body = try? JSONSerialization.data(withJSONObject: buffer)
        else { return }
        buffer.removeAll()
        var request = URLRequest(url: endpoint)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = body
        URLSession.shared.dataTask(with: request).resume()
    }
}

struct QAIntegration: Integration {
    let name = "qa-forwarder"
    let forwarder: QAForwarder

    func setup(attach: @escaping (Transporter) -> Detach, session: SessionInfoProvider) {
        _ = attach(forwarder)
    }
}

enum Dea {
    private(set) static var sdk: DeaSdk?

    static func start() {
        guard sdk == nil else { return }
        let dea = DeaSdk.initialize(options: DeaSdkOptions(
            appId: "YOUR_APP_ID",
            integrations: [QAIntegration(forwarder: QAForwarder())],
            requireConsent: true,
            appKey: "YOUR_APP_KEY",
            onLog: { entry in print("[dea]", entry.spec.name, entry.attributes) }))
        dea.start()
        sdk = dea
    }
}

// When the tester agrees:
Dea.sdk?.setConsent(true)

https://qa.example.com stands for your own service. What you send there is yours to protect: it holds your testers' raw input.