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
requireConsentistrue, 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.
Related¶
- Collect Data: DEA's own integration, which sends the captured input to DEA
onLogoption- Privacy and network