Skip to content

AI Data Tasks

Show your users short AI data tasks inside your page, such as picking the better of two answers. The @dea/contribution package lists the projects open to the user, fetches a task from the project the user picks, shows the consent screen and the task, and sends the answer with a proof that the SDK signs. Your page never sees the task, the answer, the score or the proof.

Migrating to this release: a round now runs on one project that the user picks.

Before This release
start({ publisherUserId }) start({ publisherUserId, projectId }): projectId is required, and comes from listProjects
No project list listProjects(sdk, { publisherUserId }) resolves the projects open to the user
no_task: no active project has a task for the user no_task: the picked project has nothing left for the user. Show the list again

When to use it

  • Your page rewards its users for completing tasks, for example from an "Earn rewards" button
  • DEA has projects open for your app

Prerequisites

  • The SDK is installed and initialized with your appId and appKey. See the Quick Start and Accounts and keys.
  • attest() answered passed. Without a registered key, listProjects answers NOT_ATTESTED and start answers not_attested, and nothing is sent.
  • An app user id for each user, passed as publisherUserId to listProjects and start. It is required. See App user ids.
  • If your page sends a Content Security Policy, it allows the following, in addition to what the Quick Start lists:
Directive Allow Why
connect-src https://poh-api.dep-protocol.com The project list, the task, the consent and the answer
connect-src https://sdk.dep-protocol.com The task's widget file. The package checks its origin and hash before it runs it
img-src https://sdk.dep-protocol.com Images that a task draws on your page

Install

Install @dea/contribution from the same release as @dea/sdk. It takes your own @dea/sdk instance and requires the same version.

npm install https://sdk.dep-protocol.com/0.26.0/web/contribution/dea-contribution-0.26.0.tgz

Usage

List the projects

import { DeaSdk } from '@dea/sdk';
import { listProjects } from '@dea/contribution';

const sdk = DeaSdk.current!;
const { projects, errorCode } = await listProjects(sdk, { publisherUserId: user.id });

listProjects never throws. It resolves the projects in the order DEA sends them. An empty list with no errorCode means that no project is open to this user. An empty list with an errorCode means that the list could not load.

Run a task on the picked project

import { DeaSdk } from '@dea/sdk';
import { createContribution, Outcome } from '@dea/contribution';

const contribution = createContribution(DeaSdk.current!, {
  container: document.getElementById('task')!,
  onEvent: (event) => console.log(event),
});

const { outcome, errorCode } = await contribution.start({
  publisherUserId: user.id,
  projectId: picked.projectId,
});

The package draws its screens and the task in container. start resolves once, with one outcome. When the round ends on one of the package's own screens (thank you, not sent, task unavailable), start resolves after the user taps "Back to the app".

Use the same projectId for every start of the session, "Another task" included. When the user leaves your task screen, call close(). The next session starts from the project list.

Examples

An Earn rewards screen

import { DeaSdk } from '@dea/sdk';
import { createContribution, listProjects, Outcome } from '@dea/contribution';

async function earnRewards(userId: string) {
  const sdk = DeaSdk.current!;
  const { projects, errorCode } = await listProjects(sdk, { publisherUserId: userId });
  if (errorCode) return showError(errorCode);
  if (projects.length === 0) return showNothingOpen();

  const picked = await showProjectPicker(projects);
  const contribution = createContribution(sdk, { container: taskElement });

  let outcome: Outcome = Outcome.Submitted;
  while (outcome === Outcome.Submitted && (await userWantsAnotherTask())) {
    ({ outcome } = await contribution.start({ publisherUserId: userId, projectId: picked.projectId }));
  }
  contribution.close();
  if (outcome === Outcome.NoTask) return earnRewards(userId);
}

showError, showNothingOpen, showProjectPicker, userWantsAnotherTask and taskElement stand for your own code.

Outcomes

outcome What happened
submitted DEA stored the answer
consent_declined The user tapped "Not now" on the consent screen. Nothing was recorded or sent
no_task The picked project has nothing left for this user. Show the project list again
widget_unavailable The task's widget failed its origin or hash check. Nothing was sent
not_sent The answer could not be sent: retries ran out, DEA refused it, or the SDK had too little input from the user on three tries
not_attested The SDK has no registered key. The round did not start
closed Your page called close(), or started another round, before the round ended
error DEA refused the task or the consent, or did not answer before the task showed. errorCode names the reason, or is NETWORK

API

Member Returns Description
listProjects(sdk, { publisherUserId }) Promise<ProjectList> The projects open to this user. Never throws
createContribution(sdk, options) Contribution The task runner. options takes container and an optional onEvent
contribution.start({ publisherUserId, projectId }) Promise<RoundResult> Runs one round on the picked project. Resolves { outcome, errorCode? }
contribution.consent(version) Promise<ConsentResult> Records consent from your own screen. A round waiting on the consent screen goes on to its task
contribution.close() void Ends the running round with closed, unless it has already ended

Project:

Field Type Description
projectId string Pass it to start
name string The project's name, to show in your list
patternId string The task type, such as pairwise-preference
patternName string The task type's display name, such as Pairwise preference

onEvent receives, in order: consent_required, task_shown, not_enough_signal (the same task shows again), sending and waiting_to_send (no answer from DEA yet, retrying while the page stays open).