Skip to content

Collect Data

The test and staging packages of the SDK can send what they capture to DEA's collection service, where it trains the models that score sessions. This page shows how a test or staging app attaches the collection transporter's stream delivery: the app's input goes to DEA in pieces while it runs, and the transporter cuts it into sessions on its own, so your app makes no call per screen or per round.

Warning: Collection sends the raw input of your app — touch positions, scrolls, which class of key was pressed, device motion — to DEA. Use it only in an app DEA asked you to collect with, with your users' agreement. On Flutter the stream delivery attaches on every package, the production one included: never add the collection transporter to a build you release.

When to use it

  • A data-collection or QA app that DEA asked you to build
  • A staging build of your app whose testers' sessions should reach DEA's training data

Prerequisites

  • An appId and appKey for the app — see Accounts and keys
  • The collection service's API key, which your DEA contact gives you. It is not the appKey
  • Your users agreed to collection — see User Consent

Usage

Install the packages

A staging app vendors the staging SDK, as in the Quick Start, and the collection transporter. The transporter is published in the test channel only, so it comes from there, at the same release as the SDK. From your app's root folder:

mkdir -p vendor/dea && cd vendor/dea
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/base/dea-base-0.26.0.zip
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/automation-detection/dea-automation-detection-0.26.0.zip
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/sdk/dea-sdk-0.26.0.zip
curl -sSO https://sdk.dep-protocol.com/0.26.0/test/flutter/ai-backend-transporter/dea-ai-backend-transporter-0.26.0.zip
for zip in *.zip; do unzip -qo "$zip"; done

This creates vendor/dea/base, vendor/dea/automation_detection, vendor/dea/sdk and vendor/dea/transporters/ai_backend_transporter. A test app downloads the first three from /test/flutter/ instead of /staging/flutter/.

# pubspec.yaml
dependencies:
  dea_sdk:
    path: vendor/dea/sdk
  dea_ai_backend_transporter:
    path: vendor/dea/transporters/ai_backend_transporter

dependency_overrides:
  dea_base:
    path: vendor/dea/base
  dea_automation_detection:
    path: vendor/dea/automation_detection

The transporter requires dea_base at exactly its own version, like dea_sdk, so all four zips must come from the same release; the one dea_base override serves both. The zips contain their own test/ folders: exclude vendor/** from analyzer in your analysis_options.yaml if flutter analyze walks into them.

Attach the stream delivery

import 'package:dea_ai_backend_transporter/dea_ai_backend_transporter.dart';
import 'package:dea_sdk/dea_sdk.dart';

void startCollecting() {
  final collect = aiBackendTransport(
    delivery: Delivery.stream,
    label: const CollectLabel(kind: 'human', subjectId: 'tester-0142', task: 'staging-ai-data'),
    baseUrl: 'https://poh-api.dep-protocol.com', // the host only; the transporter adds the path
    apiKey: 'YOUR_COLLECT_API_KEY',
  );

  DeaSdk.init(
    DeaOptions(
      appId: 'YOUR_APP_ID',
      // Keep motion at full rate while nobody touches the screen: motion is what tells the
      // transporter the app is still running, and thinned motion ends the session.
      idleMotionMs: 0,
      integrations: [collect],
    ),
    appKey: 'YOUR_APP_KEY',
  );
}

Then ask for consent, as in User Consent: nothing is captured or sent until the user agrees.

final agreed = await showDeaConsentDialog(context);

Warning: With no baseUrl or no apiKey, the transporter still attaches and reports every piece as sent, but nothing leaves the device. Pass both. baseUrl is the host without a path or a trailing slash.

Label the sessions

Every streamed session is filed under the CollectLabel given to aiBackendTransport.

Field Required Description
kind Yes 'human' for a person, 'bot' for an automated client
subjectId No Who produced the input: a pseudonymous id of the person or the bot, never personal data
task No What the sessions are for. Pass 'staging-ai-data': there is no default, and a label without it is sent with task null
botFamily When kind is 'bot' Which bot produced the input
botInjection No How a bot's input reached the app: 'framework', 'os-level' or 'human-relay'
difficulty No 'easy', 'normal' or 'hard'
taskId, seed No Your own task number and seed

An invalid label — a bot without botFamily, an unknown difficulty or botInjection — does not throw. The transporter refuses to attach, and nothing streams: check that (collect as StreamTransportIntegration).transporter is not null after init.

aiBackendTransport also takes facts, a CollectDevice with the OS version, the hardware model, the screen density and whether the app runs in a simulator, which the transporter writes into each session's header.

The label is read once, when the SDK starts. To file what follows under another person, dispose of the SDK and start it again with a new transporter:

DeaSdk.instance?.dispose();
startCollecting(); // with the new person's subjectId

The running streamed session then ends when its motion stops, within a second. Without motion — a simulator, or motion switched off — it is not ended, and DEA closes it after a while.

Keep the event flow going

The transporter ends a streamed session where the app's event flow is interrupted — see Where a streamed session ends. Your app does not need to do anything for a session to end, and it should avoid ending one by accident:

  • Set idleMotionMs: 0. By default the SDK keeps one motion sample every 3 seconds while nobody touches the screen, and a second of silence ends the session.
  • Do not call reset() or pause() for a screen, a game or a round. reset() starts a new session, and a pause longer than a second stops the event flow. Call reset() only where a session really ends, such as a logout — see Sessions.
  • Do not call setMotion(false). It ends the session, and the sessions after it can end only at the background, a reset or the 5-minute limit.

Examples

A staging build that shows what it sent

import 'package:dea_ai_backend_transporter/dea_ai_backend_transporter.dart';
import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/foundation.dart';

final sent = ValueNotifier<List<StreamReport>>([]);

void startCollecting(String subjectId) {
  DeaSdk.instance?.dispose();
  DeaSdk.init(
    DeaOptions(
      appId: 'YOUR_APP_ID',
      idleMotionMs: 0,
      integrations: [
        aiBackendTransport(
          delivery: Delivery.stream,
          label: CollectLabel(kind: 'human', subjectId: subjectId, task: 'staging-ai-data'),
          baseUrl: 'https://poh-api.dep-protocol.com',
          apiKey: 'YOUR_COLLECT_API_KEY',
          // Called after each answer, and for each piece the queue dropped.
          onSend: (report) => sent.value = [report, ...sent.value],
        ),
      ],
    ),
    appKey: 'YOUR_APP_KEY',
  );
}

// Mark where each game starts and ends: the marks travel with the stream, and do not cut it.
void gameStarted(String game) => DeaSdk.instance?.captureEvent('session_start', {'task': game});
void gameEnded(String game, bool completed) =>
    DeaSdk.instance?.captureEvent('session_end', {'task': game, 'completed': completed});

Check that it works

  1. Use the app for 30 seconds after agreeing to consent.
  2. onSend reports a session_stream_ingest with ok true every 30 seconds while the app is in front, and a session_stream_end when the session ends, for example when the app goes to the background. sessionId names the streamed session, not the SDK's session id.
  3. On a staging or test package, DeaOptions(onLog:) receives an http.response entry for every request, whose url.path is /api/collect-data/data-training-streaming. No http.response with ok reports means the host or key is missing.

If nothing is sent:

Check Why
baseUrl and apiKey are both set Without them nothing leaves the device, although every piece reports ok
transporter is not null after init null means the label was refused
Consent was given Nothing reaches the transporter before it
The session lasted 3 seconds or more, with a touch or key press A session that ends before its first piece is sent, shorter than that or without input, is not sent
The four packages come from the same release A mismatched SDK starts paused, and captures nothing

API

Member Returns Description
aiBackendTransport({delivery, label, facts, baseUrl, apiKey, onSend}) Integration The collection transporter, for DeaOptions(integrations:). With Delivery.stream, the stream delivery; it is a StreamTransportIntegration
StreamTransportIntegration.transporter StreamTransporter? The running transporter, null before init or when the label was refused
StreamTransporter.stats StreamStats session (the open streamed session, or null), buffered, sent, failed, dropped, lastError
StreamReport — What one request came to: at, sessionId, eventType, objects, bytes (gzipped), elapsed, ok, error