edmand46
76 lines
2.2 KiB
Markdown
76 lines
2.2 KiB
Markdown
# Quests — `client.quests`
|
|
|
|
`QuestsService` (source: `src/quests/QuestsService.ts`). The player's **global**
|
|
quests — list, claim, report metric progress. Plain call-and-response service,
|
|
NOT observable (no sync revision key): re-list after a claim or report.
|
|
|
|
Distinct from scenario quest nodes, which advance through
|
|
`client.effects.onQuest` (see `reference/scenarios.md`).
|
|
|
|
## Methods
|
|
|
|
```ts
|
|
list(): Promise<Quest[]>
|
|
claim(questSlug: string): Promise<ClaimQuestResponse>
|
|
reportProgress(metric: string, amount: number): Promise<string[]> // slugs of quests completed by this report
|
|
```
|
|
|
|
## Types
|
|
|
|
```ts
|
|
interface Quest {
|
|
slug?: string; // stable across environments — what claim() takes
|
|
name?: string;
|
|
objectives?: QuestObjectiveProgress[];
|
|
rewards?: Reward[];
|
|
status?: 'active' | 'claimed' | 'completed';
|
|
}
|
|
|
|
interface QuestObjectiveProgress {
|
|
completed?: boolean;
|
|
current?: number;
|
|
metric?: string;
|
|
objectiveId?: string;
|
|
target?: number;
|
|
}
|
|
|
|
interface ClaimQuestResponse {
|
|
alreadyClaimed?: boolean;
|
|
error?: string;
|
|
granted?: Reward[]; // { amount?, currency?, itemId? }
|
|
success?: boolean;
|
|
}
|
|
```
|
|
|
|
## Usage notes
|
|
|
|
```ts
|
|
const quests = await client.quests.list();
|
|
for (const quest of quests) {
|
|
if (quest.status === 'completed' && quest.slug) {
|
|
const res = await client.quests.claim(quest.slug);
|
|
// res.success / res.alreadyClaimed / res.granted
|
|
}
|
|
}
|
|
const completedSlugs = await client.quests.reportProgress('kills', 1);
|
|
```
|
|
|
|
- `claim` is idempotent server-side; check `success` / `alreadyClaimed` /
|
|
`error` in the response rather than relying on exceptions.
|
|
- Objective completion is judged server-side from metric reports.
|
|
|
|
## `QuestMetrics` helpers
|
|
|
|
Exported as a namespace: `import { QuestMetrics } from '@rudder/js-sdk'`
|
|
(source: `src/quests/QuestMetrics.ts`).
|
|
|
|
```ts
|
|
QuestMetrics.purchaseOffer('starter-pack'); // "purchase.offer:starter-pack"
|
|
QuestMetrics.purchaseItem('moonberry'); // "purchase.item:moonberry"
|
|
```
|
|
|
|
Purchase metrics are reported automatically server-side by the store purchase
|
|
fan-out — these helpers exist so quest configs and client code name the format
|
|
consistently. Catalog counter slugs are reported via `reportProgress`. Custom
|
|
free-text metrics no longer progress quests — they no-op at runtime.
|