failed
Finish unsuccessfully
Purpose and timing
Report a genuine loss/end without success. Conditional on your game's loss path. Do not also send completed for the same run.
Parameters and payload
No parameter is universally required for this name: the published per-game event definition is authoritative. The starter's proposal allows optional score (integer 0–1,000,000) and progress (number 0–100). It accepts no other fields. Your game's required fields or bounds can differ; inspect its current registry.
// Only valid after staff registers this event/schema for your game.
// PIExample is the provided sample helper; it waits for a real acknowledgement.
const acknowledgement = await PIExample.report('failed', {"score":50});
console.log(acknowledgement);{
"name": "failed",
"data": {
"score": 50
}
}The JSON above shows the semantic payload; the SDK adds the UUID and V2 sequence. Keep data an object, use actual numbers (not numeric strings), and omit unregistered properties. This event is terminal. Do not send more reports in the same run after acceptance.
Platform behavior
Closes the session and shows results. Registered score can update signed-in personal best/score entries. Failure does not inherently deny or award a reward; server rules decide.
Validation and errors
Registration, release scope, payload types/bounds, session state, event count and strict sequence checks apply. The current serialized data limit is 8192 characters. A defined minimumIntervalMs throttles accepted occurrences. If activeSeconds is registered, it cannot exceed server elapsed time plus three seconds. Built-in games can validate mode, seed, counters and timing beyond this common contract. Do not use their custom fields for a new game without agreeing a matching schema. See error recovery.
Best practices
Report the real gameplay transition once. Observe acceptance independently from reward receipts. After rejection or timeout, stop reporting, fix the issue and reload; there is no SDK sequence-repair method. Do not calculate platform currency or entitlements from this event locally.