Configure SDK logging

Learn how to configure logging in the MATTR Holder SDKs, including log levels, callback handlers, and accessing log files across iOS, Android, and React Native platforms.

The MATTR Holder SDKs include a built-in logging system that records internal SDK operations. This is useful for debugging integration issues, monitoring SDK behavior, and capturing diagnostic information during development and testing.

By default, SDK logs are stored locally on the device. The SDK itself does not transmit logs to any external service, although your application can choose to export or forward log events if you register a callback handler.

What information the SDK can log

The SDK can log information about its internal operations, including errors and warnings encountered during SDK operations.

All log entries include the log level and a descriptive message. This information helps you diagnose issues and understand how the SDK operates within your application.

How SDK logs differ from activity logs

The SDK provides two types of logs: SDK logs and activity logs. While both are valuable for monitoring and diagnostics, they serve different purposes and audiences.

Feature	SDK logs	Activity logs
Purpose	Developer diagnostics and debugging	User-facing credential usage history
Audience	Developers integrating the SDK	End users of your wallet application
Content	Internal SDK operations, errors, and state changes	Credential and presentation events
Configuration	`loggerConfiguration`	`activityLogConfiguration`

To learn about activity logs, see Configure activity logs.

Log levels

The SDK supports the following log levels, ordered from most to least verbose:

Level	Description
`Verbose`	Fine-grained informational events, most detailed output.
`Debug`	Detailed information useful during development.
`Info`	General informational messages about SDK operations.
`Warning`	Potentially harmful situations or unexpected behavior (`Warn` in Android).
`Error`	Error events that might still allow the SDK to continue running.
`Assert`	Severe error events that indicate a critical failure (Android only).
`Off`	Disables logging entirely.

The SDK uses the configured log level as a threshold: only log events at the specified level and less verbose (more severe) are recorded. For example, setting the level to Info captures Info, Warning, Error, and Assert events, but not Debug or Verbose.

Configure logging at initialization

You can configure logging behavior by passing a loggerConfiguration object to the SDK's initialize method. This configuration accepts two separate log levels:

logLevel: Controls which log events are written to the log file.
callbackLogLevel: Controls which log events trigger the optional callback function.

Configure logging during initialization

try await mobileCredentialHolder.initialize(
    loggerConfiguration: LoggerConfiguration( 
        logLevel: .Info, 
        callbackLogLevel: .Warning 
    ) 
)

logLevel: Sets the minimum level for writing log entries to the log file. Defaults to .Off.
callbackLogLevel: Sets the minimum level for invoking the callback closure. Defaults to .Off.

Refer to the LoggerConfiguration reference documentation for additional details.

Handle log events with a callback

You can register a callback function during initialization to receive log events in real time. This allows your application to process log events as they occur, for example to forward them to a custom logging service, display them in a debug console, or filter specific events for monitoring.

The callback is only invoked for log events at or above the callbackLogLevel threshold.

try await mobileCredentialHolder.initialize(
    loggerConfiguration: LoggerConfiguration(
        logLevel: .Info,
        callbackLogLevel: .Warning,
        callback: { logEvent in
            print("[\(logEvent.level)] \(logEvent.message)") 
        } 
    )
)

The callback receives a LogEvent object with the following properties:

level: The LogLevel of the event.
message: A string describing the log event.

Access the log file

The SDK writes log entries to a file that you can access for debugging and diagnostics. The log file contains entries from the previous two calendar days.

Get the log file path

let logFilePath = mobileCredentialHolder.getCurrentLogFilePath()

// If using an app group (e.g. for app extensions):
let logFilePath = mobileCredentialHolder.getCurrentLogFilePath(appGroup: "group.com.yourcompany.app")

The getCurrentLogFilePath method returns the file path as a string, or nil if no log file is available.

appGroup: Optional. Specify an application group to retrieve logs generated by the SDK in an app extension. If not provided, the SDK returns the log file from the default location.

To access the log contents, read the file at the returned path into Data, then decode that data into a [String], where each element represents a single log message.