Metric Event
Defined in framework ScanditCaptureCore
- enum CameraBackend
Added in version 8.7.0
The camera API a session uses.
- unknown
Added in version 8.7.0
Not known.
- camera1
Added in version 8.7.0
The legacy Android camera API.
- camera2
Added in version 8.7.0
The Android Camera2 API.
- avFoundation
Added in version 8.7.0
AVFoundation on iOS.
- enum FocusCalibration
Added in version 8.7.0
How the reported focus distance is calibrated.
- uncalibratedInfinityAtZero
Added in version 8.7.0
Uncalibrated, with infinity reported as zero.
- uncalibratedInfinityAtOne
Added in version 8.7.0
Uncalibrated, with infinity reported as one.
- approximate
Added in version 8.7.0
Approximately calibrated.
- calibrated
Added in version 8.7.0
Calibrated.
- enum CameraEvent
Added in version 8.7.0
A camera lifecycle transition.
- start
Added in version 8.7.0
The camera started.
- stop
Added in version 8.7.0
The camera stopped.
- wake
Added in version 8.7.0
The camera woke from standby.
- failure
Added in version 8.7.0
The camera failed mid-session.
- enum CameraResult
Added in version 8.7.0
The outcome of a camera transition.
- success
Added in version 8.7.0
The transition succeeded.
- failure
Added in version 8.7.0
The transition failed.
- enum LifecycleEvent
Added in version 8.7.0
An app lifecycle transition. Only transitions are reported: a session does not open with an event for the state it starts in, so its first lifecycle event can be either value.
- resume
Added in version 8.7.0
The app came back to the foreground. On iOS this is when the app becomes active again. On Android it is when one of the app’s activities starts after none was started.
- pause
Added in version 8.7.0
The app left the foreground. On iOS this is, by default, when the app resigns active, so system alerts such as permission prompts and overlays such as Control Center also pause it. On Android it is when none of the app’s activities is started, so dialogs and permission prompts do not pause it.
- enum CaptureFormat
Added in version 8.7.0
The encoding of a captured frame image.
- jxl
Added in version 8.7.0
JPEG XL.
- png
Added in version 8.7.0
PNG.
- gray8
Added in version 8.7.0
8-bit grayscale, Width * Height bytes, row-major with no padding.
- enum BatteryHealth
Added in version 8.7.0
The battery health the platform reports.
- unknown
Added in version 8.7.0
Not known.
- good
Added in version 8.7.0
Good.
- overheat
Added in version 8.7.0
Overheating.
- dead
Added in version 8.7.0
Dead.
- overVoltage
Added in version 8.7.0
Over voltage.
- unspecifiedFailure
Added in version 8.7.0
An unspecified failure.
- cold
Added in version 8.7.0
Cold.
- enum CameraConfigTrigger
Added in version 8.7.0
What prompted a camera-configuration snapshot.
- attach
Added in version 8.7.0
The camera was attached to the context.
- apply
Added in version 8.7.0
Camera settings were applied.
- frameSourceChanged
Added in version 8.7.0
The context’s frame source changed.
- MetricsConfig
open class MetricsConfig : NSObject, Sendable
Added in version 8.7.0
The configuration a session runs under, reported as the first event of a session and whenever the configuration changes. SuppressedFields names what the configuration withheld and UnavailableFields names what the platform cannot measure at all, so a suppressed field is distinguishable from an absent one.
- schemaVersion
open var schemaVersion:
Int{ get }Added in version 8.7.0
The schema version the session emits.
- enabledGroups
var enabledGroups: Set<MetricGroup> { get }
Added in version 8.7.0
The signal groups emitted in this session.
- suppressedFields
var suppressedFields: Set<SensitiveField> { get }
Added in version 8.7.0
The sensitive fields the configuration withholds.
open var unavailableFields: Set<String> { get }
Added in version 8.7.0
The environment fields this platform cannot measure, spelled as the record spells them.
var unavailableGroups: Set<MetricGroup> { get }
Added in version 8.7.0
The signal groups this platform never emits, so enabling one yields no events.
- frameMetricsSampleRate
open var frameMetricsSampleRate:
Int{ get }Added in version 8.7.0
Every Nth processed frame contributes a frame-metrics event.
- maxBufferedCaptures
open var maxBufferedCaptures:
Int{ get }Added in version 8.7.0
The most frame captures copied but not yet delivered at once. A recognition arriving while this many are in flight is dropped and counted.
- maxCaptureBytes
open var maxCaptureBytes:
Int64{ get }Added in version 8.7.0
The largest capture delivered, in bytes.
- ScanMetrics
open class ScanMetrics : NSObject, Sendable
Added in version 8.7.0
One recognition, with the timings and geometry that led to it. The fields describing the run-up, the localization counts, timings and sizes, cover the scan: the frames since the previous recognition, up to and including this one. Every barcode recognized in the same frame repeats them, so summing them across recognitions over-counts.
- frameId
open var frameId:
Int{ get }Added in version 8.7.0
Joins this recognition to the frame it came from, as the engine numbers frames. The same value as the frame id of the recognized barcode, which is not the frame signal’s own ordinal.
- symbologyIdentifier
open var symbologyIdentifier: String { get }
Added in version 8.7.0
The symbology of the recognized barcode. On iOS it is the symbology’s JSON identifier, for example
ean13, because the symbology enum is declared in ScanditBarcodeCapture, which core does not import.
- data
open var data: String? { get }
Added in version 8.7.0
The barcode content. Absent unless the ScanData sensitive field is enabled and the license includes AnalyticsScanContent.
- framesToFirstLocalization
open var framesToFirstLocalization:
Int{ get }Added in version 8.7.0
Frames from the start of the scan to the first localization, counting the scan’s first frame as 1. Zero when nothing was localized before the barcode was recognized.
- msToFirstLocalization
open var msToFirstLocalization:
Int64{ get }Added in version 8.7.0
Milliseconds from the first frame of the scan that carried a timestamp to the first localization. Zero when the first localization happened on that frame, when nothing was localized, and when the frame source reports no capture timestamp.
- msBetweenRecognitions
var msBetweenRecognitions:
Int64? { get }Added in version 8.7.0
Absent where there is no previous recognition to measure from: the first recognition of a session, the first after a discarded scan, and every frame source that reports no capture timestamp.
- localizedCount
open var localizedCount:
Int{ get }Added in version 8.7.0
Barcodes localized but not yet recognized during the scan.
- minBarcodeSizePx
open var minBarcodeSizePx:
Double{ get }Added in version 8.7.0
The smallest longer side, in pixels, of the axis-aligned bounding box of a barcode counted in LocalizedCount. Rotation moves this away from the symbol’s true side length in either direction: it shrinks for an elongated symbol and grows by up to sqrt(2) for a square one. Zero when LocalizedCount is zero.
- maxBarcodeSizePx
open var maxBarcodeSizePx:
Double{ get }Added in version 8.7.0
The largest longer side, in pixels, of the axis-aligned bounding box of a barcode counted in LocalizedCount, under the same rotation caveat as MinBarcodeSizePx. Zero when LocalizedCount is zero.
- avgBarcodeSizePx
open var avgBarcodeSizePx:
Double{ get }Added in version 8.7.0
The mean longer side, in pixels, over the barcodes counted in LocalizedCount, under the same rotation caveat as MinBarcodeSizePx. Zero when LocalizedCount is zero.
- pixelsPerElement
var pixelsPerElement:
Double? { get }Added in version 8.7.0
Pixels per smallest symbol element, absent when the symbology does not define one.
- scanIntention
open var scanIntention: ScanIntention { get }
Added in version 8.7.0
The scan intention in force when the barcode was recognized.
- torchEnabled
open var torchEnabled:
Bool{ get }Added in version 8.7.0
Whether the torch was on.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- MsarMetrics
open class MsarMetrics : NSObject, Sendable
Added in version 8.7.0
MatrixScan AR tracking counts, for a frame in which barcodes entered or left tracking and once more when the session ends. TrackedCount is the frame’s own; the other counts run from the start of the session, or from the last interruption of metrics collection within it.
- frameSeq
open var frameSeq:
Int64{ get }Added in version 8.7.0
The ordinal of the processed frame within the session.
- trackedCount
open var trackedCount:
Int{ get }Added in version 8.7.0
Barcodes tracked in this frame.
- newlyTracked
open var newlyTracked:
Int{ get }Added in version 8.7.0
Barcodes that started being tracked, counted from the start of the session.
- lostCount
open var lostCount:
Int{ get }Added in version 8.7.0
Barcodes whose tracking ended, counted from the start of the session.
- avgCodesPerFrame
open var avgCodesPerFrame:
Double{ get }Added in version 8.7.0
The running average of tracked barcodes per frame.
- processedFrames
var processedFrames:
Int? { get }Added in version 8.7.0
Frames the session processed. This and DroppedFrames are present only on the session-end event, which their presence marks.
- droppedFrames
var droppedFrames:
Int? { get }Added in version 8.7.0
Frames the session dropped, present alongside ProcessedFrames.
- processedFrameRatio
var processedFrameRatio:
Double? { get }Added in version 8.7.0
ProcessedFrames / (ProcessedFrames + DroppedFrames), on the session-end event of a session that saw any frame.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- FrameMetrics
open class FrameMetrics : NSObject, Sendable
Added in version 8.7.0
Processing cost of one sampled frame, with its resolution. Emitted every Nth processed frame, N being MetricsSettings.frameMetricsSampleRate.
- frameSeq
open var frameSeq:
Int64{ get }Added in version 8.7.0
The ordinal of the processed frame within the session.
- frameId
var frameId:
Int? { get }Added in version 8.7.0
The engine frame ordinal, present only when this frame produced a recognition.
- totalProcessingMs
open var totalProcessingMs:
Double{ get }Added in version 8.7.0
Milliseconds the frame spent in the processing pipeline.
- engineMs
open var engineMs:
Double{ get }Added in version 8.7.0
Milliseconds the engine spent on the frame.
- fpsRunningAvg
open var fpsRunningAvg:
Double{ get }Added in version 8.7.0
The running average of processed frames per second.
- droppedFrames
open var droppedFrames:
Int{ get }Added in version 8.7.0
Frames dropped since the previous frame-metrics event.
- widthPx
open var widthPx:
Int{ get }Added in version 8.7.0
The frame width in pixels.
- heightPx
open var heightPx:
Int{ get }Added in version 8.7.0
The frame height in pixels.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- EnvironmentMetrics
open class EnvironmentMetrics : NSObject, Sendable
Added in version 8.7.0
Ambient and device conditions around the scan, sampled at most once per second while frames are being processed. An absent value means it was not available for that sample, never that the configuration suppressed it: the platform cannot measure the signal, the camera backend or that frame did not report it, or the SDK does not read it yet. MetricsConfig.unavailableFields names only the first of those.
- illuminationEstimate
var illuminationEstimate:
Double? { get }Added in version 8.7.0
Smoothed 1 / (exposure x ISO). Unitless and higher when brighter; comparable only against other estimates from the same device. Present only where the SDK computes the smoothed estimate, which is narrower than where exposure and ISO themselves are reported.
- exposureMs
var exposureMs:
Double? { get }Added in version 8.7.0
The camera exposure time in milliseconds.
- iso
var iso:
Double? { get }Added in version 8.7.0
The camera ISO sensitivity.
- focusDistance
var focusDistance:
Double? { get }Added in version 8.7.0
The focus distance as the platform reports it; see the calibration for its unit.
- focusCalibration
var focusCalibration: FocusCalibration? { get }
Added in version 8.7.0
How the focus distance is calibrated.
- isFixedFocus
var isFixedFocus:
Bool? { get }Added in version 8.7.0
Whether the camera has a fixed focus.
- batteryPct
var batteryPct:
Double? { get }Added in version 8.7.0
Charge remaining, 0 to 100.
- batteryHealth
var batteryHealth: BatteryHealth? { get }
Added in version 8.7.0
The battery health the platform reports.
- powerSaveMode
var powerSaveMode:
Bool? { get }Added in version 8.7.0
Whether the device is in a power-saving mode.
- torchEnabled
open var torchEnabled:
Bool{ get }Added in version 8.7.0
The torch state the mode asked for, not the light the sensor saw: an automatic torch firing on the user’s behalf reads as false.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- CameraMetrics
open class CameraMetrics : NSObject, Sendable
Added in version 8.7.0
One camera lifecycle transition, so entering and leaving scanning is readable from the stream alone wherever the camera was stopped rather than torn down: a camera destroyed while on, or one whose metrics session closes before its stop is delivered, leaves a start with no stop against it. Start and wake carry Result and DurationMs, plus the resolution once the camera reached on. A mid-session failure carries Code, Reason and SessionUptimeMs, and stop carries SessionUptimeMs. Event identifies the transition, so the fields outside its set are absent.
- event
open var event: CameraEvent { get }
Added in version 8.7.0
The lifecycle transition this event reports.
- result
var result: CameraResult? { get }
Added in version 8.7.0
Whether the transition succeeded.
- durationMs
var durationMs:
Int64? { get }Added in version 8.7.0
Milliseconds the transition took.
- widthPx
var widthPx:
Int? { get }Added in version 8.7.0
The frame width in pixels after the transition.
- heightPx
var heightPx:
Int? { get }Added in version 8.7.0
The frame height in pixels after the transition.
- api
open var api: CameraBackend { get }
Added in version 8.7.0
The camera API in use.
- facing
open var facing: CameraPosition { get }
Added in version 8.7.0
The camera position in use.
- reason
open var reason: String? { get }
Added in version 8.7.0
The platform error description of a failure.
- sessionUptimeMs
var sessionUptimeMs:
Int64? { get }Added in version 8.7.0
Time the camera has been on since it last left the off state.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- CameraConfigMetrics
open class CameraConfigMetrics : NSObject, Sendable
Added in version 8.7.0
One snapshot of a camera’s complete configuration. DesiredSettingsJson is what was last requested and CurrentSettingsJson what the camera last put into effect; the two differ only while a request is pending. The typed properties are a projection of CurrentSettingsJson. Both are the settings as the SDK requested them, so a resolution or frame rate the platform substituted is not reflected; the delivered resolution is on the camera start event.
- revision
open var revision:
Int64{ get }Added in version 8.7.0
Counts this session’s camera-config events from 1, in the order they were emitted.
- trigger
open var trigger: CameraConfigTrigger { get }
Added in version 8.7.0
What prompted this snapshot.
- facing
open var facing: CameraPosition { get }
Added in version 8.7.0
The camera position.
- api
open var api: CameraBackend { get }
Added in version 8.7.0
The camera API.
- preferredResolution
open var preferredResolution: VideoResolution { get }
Added in version 8.7.0
The preferred resolution in the settings.
- maxFrameRate
open var maxFrameRate:
Double{ get }Added in version 8.7.0
The maximum frame rate in the settings.
- zoomFactor
open var zoomFactor:
Double{ get }Added in version 8.7.0
The zoom factor in the settings.
- torchLevel
open var torchLevel:
Double{ get }Added in version 8.7.0
The torch brightness in the settings. Whether the torch is on is not part of the settings.
- focusStrategy
open var focusStrategy: String { get }
Added in version 8.7.0
The focus strategy as its JSON identifier, for example
onlyOnRequest. On Android, an unknown identifier passed to the constructor reads asauto.
- desiredSettingsJson
open var desiredSettingsJson: Dictionary<String,
Any> { get }Added in version 8.7.0
The settings last requested, as a JSON object: an
org.json.JSONObjecton Android and a dictionary on iOS.
- currentSettingsJson
open var currentSettingsJson: Dictionary<String,
Any> { get }Added in version 8.7.0
The settings the camera last put into effect, as a JSON object: an
org.json.JSONObjecton Android and a dictionary on iOS.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- FrameCaptureMetrics
open class FrameCaptureMetrics : NSObject, Sendable
Added in version 8.7.0
The tabular row for one captured frame. The pixels travel separately, so a sink that only writes rows never has to carry an image.
- frameSeq
open var frameSeq:
Int64{ get }Added in version 8.7.0
The ordinal of the processed frame within the session.
- frameId
var frameId:
Int? { get }Added in version 8.7.0
The engine frame ordinal, present only when this frame produced a recognition.
- captureId
open var captureId: String { get }
Added in version 8.7.0
Ties this row to the encoded image delivered alongside it.
- format
open var format: CaptureFormat { get }
Added in version 8.7.0
The encoding of the captured image.
- widthPx
open var widthPx:
Int{ get }Added in version 8.7.0
The captured image width in pixels.
- heightPx
open var heightPx:
Int{ get }Added in version 8.7.0
The captured image height in pixels.
- bytes
open var bytes:
Int64{ get }Added in version 8.7.0
The encoded image size in bytes.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- FrameCapture
open class FrameCapture : NSObject, Sendable
Added in version 8.7.0
One captured frame image, raw or encoded as Format says, delivered to a sink alongside the frame-capture row it belongs to.
- captureId
open var captureId: String { get }
Added in version 8.7.0
Ties the image to the frame-capture row describing it.
- format
open var format: CaptureFormat { get }
Added in version 8.7.0
The encoding of the image.
- width
open var width:
Int{ get }Added in version 8.7.0
Pixel width of the image in Data.
- height
open var height:
Int{ get }Added in version 8.7.0
Pixel height of the image in Data.
- LifecycleMetrics
open class LifecycleMetrics : NSObject, Sendable
Added in version 8.7.0
One app lifecycle transition.
- event
open var event: LifecycleEvent { get }
Added in version 8.7.0
The lifecycle transition this event reports.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- ContextMetrics
open class ContextMetrics : NSObject, Sendable
Added in version 8.7.0
One data capture context status, as reported to the context listeners: the state in force rather than a change. A StatusCode of zero means the context has reached no verdict, either none yet or one since withdrawn. IsValid is true only for an outright success, so it reads false for a withdrawn verdict as well as for a failure; count failures by StatusCode, not by IsValid.
- statusCode
open var statusCode:
Int{ get }Added in version 8.7.0
The context status code. Zero when no verdict is in force.
- isValid
open var isValid:
Bool{ get }Added in version 8.7.0
Whether the context is valid in this status. False both for a failure and for a verdict that was withdrawn, so counting failures by this alone over-counts.
- extras
open var extras: Dictionary<String, String> { get }
Added in version 8.7.0
Fields not yet stable enough for their own column.
- CustomEvent
open class CustomEvent : NSObject, Sendable
Added in version 8.7.0
One event the app injected into the metric stream.
- attributes
open var attributes: Dictionary<String, String> { get }
Added in version 8.7.0
The app-defined attributes of the event.
- DroppedEventsMetrics
open class DroppedEventsMetrics : NSObject, Sendable
Added in version 8.7.0
What the pipeline threw away, so a gap in the data is visible instead of silent.
- droppedEventsCumulative
open var droppedEventsCumulative:
Int64{ get }Added in version 8.7.0
Events dropped since the session started.
- frameCapturesDropped
open var frameCapturesDropped:
Int64{ get }Added in version 8.7.0
Frame captures dropped since the session started.
- sinkWriteErrors
open var sinkWriteErrors:
Int64{ get }Added in version 8.7.0
Write errors the bundled sink reported since the session started.
- MetricEvent
open class MetricEvent : NSObject, Sendable
Added in version 8.7.0
One production-metrics event: a schema-versioned envelope plus exactly one populated payload, which is what identifies the event’s kind.
- schemaVersion
open var schemaVersion:
Int{ get }Added in version 8.7.0
The schema version this event follows.
- tsUtc
open var tsUtc:
Int64{ get }Added in version 8.7.0
Wall-clock epoch milliseconds. Subject to clock changes, so it orders events across sessions but not reliably within one.
- monotonicMs
open var monotonicMs:
Int64{ get }Added in version 8.7.0
Steady-clock milliseconds, comparable only against other events from the same process run.
- sessionId
open var sessionId: String { get }
Added in version 8.7.0
Identifies the session; every event of a session repeats it.
- config
open var config: MetricsConfig? { get }
Added in version 8.7.0
The configuration in force. Set on the first event of a session, when the instance is enabled, whenever the configuration changes, and on the first event a newly registered sink receives.
- scan
open var scan: ScanMetrics? { get }
Added in version 8.7.0
One recognition.
- msar
open var msar: MsarMetrics? { get }
Added in version 8.7.0
One frame of MatrixScan AR tracking.
- frame
open var frame: FrameMetrics? { get }
Added in version 8.7.0
One sampled processed frame.
- environment
open var environment: EnvironmentMetrics? { get }
Added in version 8.7.0
Ambient and device conditions.
- camera
open var camera: CameraMetrics? { get }
Added in version 8.7.0
One camera lifecycle transition.
- frameCapture
open var frameCapture: FrameCaptureMetrics? { get }
Added in version 8.7.0
One captured frame; its pixels arrive through the sink separately.
- lifecycle
open var lifecycle: LifecycleMetrics? { get }
Added in version 8.7.0
One app lifecycle transition.
- context
open var context: ContextMetrics? { get }
Added in version 8.7.0
The data capture context status in force.
- custom
open var custom: CustomEvent? { get }
Added in version 8.7.0
One app-injected event.
- dropped
open var dropped: DroppedEventsMetrics? { get }
Added in version 8.7.0
What the pipeline threw away.
- cameraConfig
open var cameraConfig: CameraConfigMetrics? { get }
Added in version 8.7.0
One snapshot of a camera’s complete configuration.