Usage and diagnostics

One keeps product usage, handled errors, and native crashes separate so each answer is useful to an operator without turning normal app activity into a stream of logs.

Usage measurements

An App owner defines measurements in Configure → Settings → Apps → Usage measurements. A definition says what the app will measure: its key, display label, unit, precision, allowed source, optional categories, and optional entitlement.

New measurements begin at revision 1. Their meaning is retained for historical reports. You can change the label or which revision is active; changing the unit, precision, dimensions, source, or entitlement requires a new revision, which starts inactive. Activate it only after the app has been changed to declare and record that revision.

Creating a measurement does not collect data, backfill history, or add a charge. The SDK records completed work cumulatively and uploads only on its normal schedule. A missing upload is shown as incomplete or unavailable evidence, never as zero use.

Where the information appears

Customer Usage shows the selected customer’s recorded usage and session evidence. Customer Activity shows important events. The dashboard uses the same bounded data for reports. These views are not a customer-facing page in a tenant app; they are operator tools in One Admin.

Handled errors and native crashes

Use a handled error when the app catches a failure and can continue or show recovery UI. The SDK records one app_error_reported occurrence with its phase (startup or runtime), operation, bounded error details, and an optional migration stage. Reuse the same report when retrying the same failure; create a new report for a new occurrence.

A native crash is different: the process terminated. One’s crash reporter preserves the complete crash report and records app_crash_reported for the timeline. A handled error does not replace crash reporting, and a crash is not inferred from a caught error. In Customer Activity, handled errors have expandable, short-retention details; native crashes remain available through Crash Reports.

Refund previews

Apple consumption requests can be reviewed with the exact transaction context and available usage evidence. The preview makes evidence gaps clear and never assumes unrecorded usage was zero.

Consumption-response sending is disabled. A preview cannot send a response to Apple, and enabling measurements does not change that. Incoming requests remain recorded for review until customer consent and a separately approved sending rollout exist.

SDK setup

These additions are present in the local SDK source. Check your resolved SDK version before adopting them; publishing the SDK remains separate from deploying One Admin. First register a transfers count measurement at revision 1 with client source and a direction category allowing send and receive.

For iOS, use the process-wide One instance:

try await one.configureUsage(
    instrumentationRevision: "transfer_usage_1",
    supportedMetrics: [.init(key: "transfers", definitionRevision: 1)]
)

// After this transfer has completed; transferID is the app's durable operation ID.
try one.recordUsage(.init(
    operationId: transferID,
    key: "transfers",
    scaledValue: "1",
    dimensions: ["direction": "send"]
))

React, Svelte, and headless browser/desktop clients share the same core methods:

await one.configureUsage({
  instrumentationRevision: 'transfer_usage_1',
  supportedMetrics: [{ key: 'transfers', definitionRevision: 1 }],
});

// After completion; keep this ID stable if the app retries the same record.
await one.recordUsage({
  operationId: completedTransfer.id,
  key: 'transfers',
  scaledValue: '1',
  dimensions: { direction: 'send' },
});

Declare only measurements the app actually records. Quantities are integer strings in the registered scale; count and byte measurements use scale 0. Use completed work, not progress updates. The SDK owns persistence, deduplication, and its normal upload schedule; do not add another timer or queue. Registration and these calls do not enable Apple consumption-response sending.