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. |
Release History
The complete release history for the SDK, including every version, its release date, and the full changelog, is maintained on pub.dev. Each release entry lists the bug fixes, new features, and breaking changes introduced in that version, so you can decide when to upgrade and what to test.
- All versions — pub.dev/packages/b2metric_sdk/versions
- Package page — pub.dev/packages/b2metric_sdk
- API documentation — pub.dev/documentation/b2metric_sdk/latest
Before upgrading in production, we recommend reviewing the changelog for any version between your current one and the target, paying particular attention to entries marked as breaking changes. Patch releases (the third number — for example 1.0.0 → 1.0.1) are always backward-compatible bug fixes.
Support and Contact
If you run into issues during integration that aren't covered by the Troubleshooting section, or if you have feature requests or feedback about the SDK, the B2Metric team is available through the channels below. When reporting a bug, please include the SDK version, the Flutter version, the target platform (iOS or Android), and any relevant debug log output — these details speed up diagnosis considerably.
- Website — b2metric.com
- pub.dev — pub.dev/packages/b2metric_sdk
- API ref — pub.dev/documentation/b2metric_sdk/latest