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 }):projectIdis required, and comes fromlistProjectsNo project list listProjects(sdk, { publisherUserId })resolves the projects open to the userno_task: no active project has a task for the userno_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
appIdandappKey. See the Quick Start and Accounts and keys. attest()answeredpassed. Without a registered key,listProjectsanswersNOT_ATTESTEDandstartanswersnot_attested, and nothing is sent.- An app user id for each user, passed as
publisherUserIdtolistProjectsandstart. 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.
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).