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
appIdandappKeyfor 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.
Warning: With no
baseUrlor noapiKey, the transporter still attaches and reports every piece as sent, but nothing leaves the device. Pass both.baseUrlis 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:
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()orpause()for a screen, a game or a round.reset()starts a new session, and a pause longer than a second stops the event flow. Callreset()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¶
- Use the app for 30 seconds after agreeing to consent.
onSendreports asession_stream_ingestwithoktrueevery 30 seconds while the app is in front, and asession_stream_endwhen the session ends, for example when the app goes to the background.sessionIdnames the streamed session, not the SDK's session id.- On a staging or test package,
DeaOptions(onLog:)receives anhttp.responseentry for every request, whoseurl.pathis/api/collect-data/data-training-streaming. Nohttp.responsewithokreports 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 |
Related¶
- Collecting data — what is sent, when, and where a session ends
- User Consent
- Sessions
- Accounts and keys