Troubleshooting

This section covers the most common questions and issues teams encounter while integrating the SDK. If your problem isn't listed here, the first diagnostic step is almost always the same: set logLevel to LogLevel.debug, reproduce the issue, and read the console output. The SDK logs every meaningful internal decision at debug level, which is usually enough to pinpoint what's going wrong.

Symptom	Resolution
Events do not appear in the platform	Initialize with logLevel: LogLevel.debug and review the console output. Verify that the API key is correct and active, that the device has network connectivity, and that you have called init() before any logEvent() call. Events can also be delayed by up to flushIntervalSeconds — wait at least that long or call flush() to force immediate delivery.
init() is called more than once	After the first call, all subsequent init() calls are ignored — no additional configuration is applied. To change configuration, call destroy() first and then init() again with the new config.
Events are not sent immediately	This is expected. The SDK delivers events in batches according to batchSize and flushIntervalSeconds to preserve battery and bandwidth. Call flush() to send immediately at critical moments such as purchase confirmation or sign-out.
Are events lost when offline?	No. Events are stored in a persistent queue (up to maxQueueSize) and sent automatically once connectivity is restored. The queue survives application restarts.
A configuration value is outside the documented range	The SDK clamps out-of-range values to the nearest valid value rather than throwing. Check the debug log to confirm which value was applied.
logEvent() is dropping some of my properties	Check that all property values are one of the supported types (String, num, bool, DateTime, null, Map, List). Unsupported types — custom classes, Futures, Streams — are dropped with a warning visible at LogLevel.warning or higher.
Session counts look too high or too low	Sessions are bounded by the sessionTimeoutMinutes config field. If counts seem high, the timeout may be too short for your usage pattern; if they seem low, it may be too long. Adjust the value at init() to match your application's typical usage.