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. They never change the score, so they cannot be used to make a session look more human.

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

Note: Custom events are not a way to report input. To report typing, or touches inside a web view, see Report input the SDK cannot see.

Note: Custom events stay on the device, in the session the SDK scores. The SDK does not send them to DEA.

Prerequisites

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

Usage

Record an event

import 'package:dea_sdk/dea_sdk.dart';

DeaSdk.instance?.captureEvent('level_start');

Record an event with data

DeaSdk.instance?.captureEvent('level_start', {'level': 3, 'mode': 'hard'});

Limits

	Limit	If exceeded
Name	64 characters	The name is shortened to its first 64 characters
Data	1024 bytes as JSON	The whole event is dropped

Data that cannot be converted to JSON is also dropped. A dropped event is dropped silently: captureEvent does not throw and reports nothing. Events are also ignored 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 'package:dea_sdk/dea_sdk.dart';

class GameController {
  int _round = 0;

  void startRound() {
    _round++;
    DeaSdk.instance?.captureEvent('round_start', {'round': _round});
  }

  void endRound({required bool won}) {
    DeaSdk.instance?.captureEvent('round_end', {'round': _round, 'won': won});
  }
}

API

Member	Returns	Description
captureEvent(name, [data])	void	Records an event on the session timeline

Related

• Sessions
• API Reference