Skip to content

docs: add public API documentation and fix deprecated userId warning #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moreirawebmaster merged 2 commits into from
Jul 24, 2025
Merged

docs: add public API documentation and fix deprecated userId warning #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3677898
docs: add public API documentation for all members
moreirawebmaster Jul 24, 2025
1a85486
fix: resolve deprecated userId warning in Clarity adapter
moreirawebmaster Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions analysis_options.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ analyzer:

linter:
rules:
public_member_api_docs: true
# === SECURITY & SAFETY (2025 Critical) ===
# Modern security practices
avoid_dynamic_calls: false
Expand Down
16 changes: 13 additions & 3 deletions lib/src/analytics/adapters/engine_clarity_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,32 @@ import 'package:clarity_flutter/clarity_flutter.dart';
import 'package:engine_tracking/engine_tracking.dart';
import 'package:flutter/widgets.dart';

/// Microsoft Clarity analytics adapter for the Engine Tracking library.
///
/// Provides integration with Microsoft Clarity for session recording,
/// heatmaps, and user behavior analytics.
class EngineClarityAdapter implements IEngineAnalyticsAdapter<EngineClarityConfig> {
/// Creates a new Microsoft Clarity analytics adapter.
///
/// [config] - The Microsoft Clarity configuration.
EngineClarityAdapter(this.config);

/// The Microsoft Clarity configuration.
@override
final EngineClarityConfig config;

/// The name of this adapter.
@override
String get adapterName => 'Microsoft Clarity';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

bool get isFaroInitialized => isEnabled && _isInitialized;

bool _isInitialized = false;

@override
Expand Down Expand Up @@ -70,7 +79,8 @@ class EngineClarityAdapter implements IEngineAnalyticsAdapter<EngineClarityConfi

@override
Future<void> setUserId(final String? userId, [final String? email, final String? name]) async {
Clarity.setCustomUserId(userId ?? email ?? name ?? '');
final customUserId = userId ?? email ?? name ?? '';
Clarity.setCustomUserId(customUserId);
await Future.value(null);
}

Expand Down
11 changes: 11 additions & 0 deletions lib/src/analytics/adapters/engine_faro_analytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,34 @@ import 'package:engine_tracking/engine_tracking.dart';
import 'package:faro/faro.dart';
import 'package:flutter/widgets.dart';

/// Grafana Faro analytics adapter for the Engine Tracking library.
///
/// Provides integration with Grafana Faro for observability and analytics.
class EngineFaroAnalyticsAdapter implements IEngineAnalyticsAdapter<EngineFaroConfig> {
/// Creates a new Grafana Faro analytics adapter.
///
/// [config] - The Grafana Faro configuration.
EngineFaroAnalyticsAdapter(this.config);

/// The Grafana Faro configuration.
@override
final EngineFaroConfig config;

/// The name of this adapter.
@override
String get adapterName => 'Grafana Faro';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

bool _isInitialized = false;

/// Whether Grafana Faro is initialized and ready.
bool get isFaroInitialized => isEnabled && _isInitialized && _faro != null;

Faro? _faro;
Expand Down
11 changes: 11 additions & 0 deletions lib/src/analytics/adapters/engine_firebase_analytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,32 @@ import 'package:engine_tracking/engine_tracking.dart';
import 'package:firebase_analytics/firebase_analytics.dart';
import 'package:flutter/material.dart';

/// Firebase Analytics adapter for the Engine Tracking library.
///
/// Provides integration with Firebase Analytics for event tracking and user analytics.
class EngineFirebaseAnalyticsAdapter implements IEngineAnalyticsAdapter<EngineFirebaseAnalyticsConfig> {
/// Creates a new Firebase Analytics adapter.
///
/// [config] - The Firebase Analytics configuration.
EngineFirebaseAnalyticsAdapter(this.config);

/// The Firebase Analytics configuration.
@override
final EngineFirebaseAnalyticsConfig config;

/// The name of this adapter.
@override
String get adapterName => 'Firebase Analytics';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// Whether Firebase Analytics is initialized and ready.
bool get isFirebaseAnalyticsInitialized => isEnabled && _isInitialized && _firebaseAnalytics != null;

bool _isInitialized = false;
Expand Down
11 changes: 11 additions & 0 deletions lib/src/analytics/adapters/engine_google_logging_analytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,32 @@ import 'package:flutter/material.dart';
import 'package:googleapis/logging/v2.dart' as logging;
import 'package:googleapis_auth/auth_io.dart' as auth;

/// Google Cloud Logging analytics adapter for the Engine Tracking library.
///
/// Provides integration with Google Cloud Logging for analytics event tracking.
class EngineGoogleLoggingAnalyticsAdapter implements IEngineAnalyticsAdapter<EngineGoogleLoggingConfig> {
/// Creates a new Google Cloud Logging analytics adapter.
///
/// [config] - The Google Cloud Logging configuration.
EngineGoogleLoggingAnalyticsAdapter(this.config);

/// The Google Cloud Logging configuration.
@override
final EngineGoogleLoggingConfig config;

/// The name of this adapter.
@override
String get adapterName => 'Google Cloud Logging Analytics';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// Whether Google Cloud Logging Analytics is initialized and ready.
bool get isGoogleLoggingAnalyticsInitialized => isEnabled && _isInitialized;

bool _isInitialized = false;
Expand Down
11 changes: 11 additions & 0 deletions lib/src/analytics/adapters/engine_splunk_analytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,32 @@ import 'package:engine_tracking/src/analytics/adapters/i_engine_analytics_adapte
import 'package:engine_tracking/src/config/engine_splunk_config.dart';
import 'package:flutter/material.dart';

/// Splunk analytics adapter for the Engine Tracking library.
///
/// Provides integration with Splunk for analytics event tracking and logging.
class EngineSplunkAnalyticsAdapter implements IEngineAnalyticsAdapter<EngineSplunkConfig> {
/// Creates a new Splunk analytics adapter.
///
/// [config] - The Splunk configuration.
EngineSplunkAnalyticsAdapter(this.config);

/// The Splunk configuration.
@override
final EngineSplunkConfig config;

/// The name of this adapter.
@override
String get adapterName => 'Splunk';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// Whether Splunk is initialized and ready.
bool get isSplunkInitialized => isEnabled && _isInitialized;

bool _isInitialized = false;
Expand Down
43 changes: 43 additions & 0 deletions lib/src/analytics/adapters/i_engine_analytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,61 @@
import 'package:engine_tracking/src/config/config.dart';

/// Interface for analytics adapters in the Engine Tracking library.
///
/// Defines the contract that all analytics adapters must implement
/// to provide consistent analytics functionality across different services.
///
/// [TConfig] - The configuration type for this adapter.
abstract class IEngineAnalyticsAdapter<TConfig extends IEngineConfig> {
/// The name of this adapter.
String get adapterName;

/// Whether this adapter is enabled.
bool get isEnabled;

/// Whether this adapter has been initialized.
bool get isInitialized;

/// The configuration for this adapter.
TConfig get config;

/// Initializes this adapter.
Future<void> initialize();

/// Disposes of this adapter and cleans up resources.
Future<void> dispose();

/// Logs an analytics event.
///
/// [name] - The name of the event.
/// [parameters] - Optional parameters for the event.
Future<void> logEvent(final String name, [final Map<String, dynamic>? parameters]);

/// Sets the user ID and optional user information.
///
/// [userId] - The user ID.
/// [email] - Optional email address.
/// [name] - Optional display name.
Future<void> setUserId(final String? userId, [final String? email, final String? name]);

/// Sets a user property.
///
/// [name] - The property name.
/// [value] - The property value.
Future<void> setUserProperty(final String name, final String? value);

/// Sets the current page/screen.
///
/// [screenName] - The screen name.
/// [previousScreen] - Optional previous screen name.
/// [parameters] - Optional page parameters.
Future<void> setPage(final String screenName, [final String? previousScreen, final Map<String, dynamic>? parameters]);

/// Logs an app open event.
///
/// [parameters] - Optional parameters for the event.
Future<void> logAppOpen([final Map<String, dynamic>? parameters]);

/// Resets this adapter to its initial state.
Future<void> reset();
}
11 changes: 11 additions & 0 deletions lib/src/bug_tracking/adapters/engine_crashlytics_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,32 @@ import 'package:engine_tracking/src/config/engine_crashlytics_config.dart';
import 'package:firebase_crashlytics/firebase_crashlytics.dart';
import 'package:flutter/foundation.dart';

/// Firebase Crashlytics adapter for the Engine Tracking library.
///
/// Provides integration with Firebase Crashlytics for crash reporting and error tracking.
class EngineCrashlyticsAdapter implements IEngineBugTrackingAdapter<EngineCrashlyticsConfig> {
/// Creates a new Firebase Crashlytics adapter.
///
/// [config] - The Firebase Crashlytics configuration.
EngineCrashlyticsAdapter(this.config);

/// The name of this adapter.
@override
String get adapterName => 'Firebase Crashlytics';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// The Firebase Crashlytics configuration.
@override
final EngineCrashlyticsConfig config;

/// Whether Firebase Crashlytics is initialized and ready.
bool get isCrashlyticsInitialized => isEnabled && _isInitialized && _crashlytics != null;

bool _isInitialized = false;
Expand Down
11 changes: 11 additions & 0 deletions lib/src/bug_tracking/adapters/engine_faro_bug_tracking_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,33 @@ import 'package:engine_tracking/engine_tracking.dart';
import 'package:faro/faro.dart';
import 'package:flutter/foundation.dart';

/// Grafana Faro bug tracking adapter for the Engine Tracking library.
///
/// Provides integration with Grafana Faro for error tracking and crash reporting.
class EngineFaroBugTrackingAdapter implements IEngineBugTrackingAdapter<EngineFaroConfig> {
/// Creates a new Grafana Faro bug tracking adapter.
///
/// [config] - The Grafana Faro configuration.
EngineFaroBugTrackingAdapter(this.config);

/// The name of this adapter.
@override
String get adapterName => 'Grafana Faro Bug Tracking';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// Whether Grafana Faro is initialized and ready.
bool get isFaroInitialized => isEnabled && _isInitialized && _faro != null;

bool _isInitialized = false;

/// The Grafana Faro configuration.
@override
final EngineFaroConfig config;

Expand Down
11 changes: 11 additions & 0 deletions lib/src/bug_tracking/adapters/engine_google_logging_bug_tracking_adapter.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,34 @@ import 'package:flutter/foundation.dart';
import 'package:googleapis/logging/v2.dart' as logging;
import 'package:googleapis_auth/auth_io.dart' as auth;

/// Google Cloud Logging bug tracking adapter for the Engine Tracking library.
///
/// Provides integration with Google Cloud Logging for error tracking and logging.
class EngineGoogleLoggingBugTrackingAdapter implements IEngineBugTrackingAdapter<EngineGoogleLoggingConfig> {
/// Creates a new Google Cloud Logging bug tracking adapter.
///
/// [config] - The Google Cloud Logging configuration.
EngineGoogleLoggingBugTrackingAdapter(this.config);

bool _isInitialized = false;

/// The name of this adapter.
@override
String get adapterName => 'Google Cloud Logging Bug Tracking';

/// Whether this adapter is enabled.
@override
bool get isEnabled => config.enabled;

/// Whether this adapter has been initialized.
@override
bool get isInitialized => _isInitialized;

/// The Google Cloud Logging configuration.
@override
final EngineGoogleLoggingConfig config;

/// Whether Google Cloud Logging Bug Tracking is initialized and ready.
bool get isGoogleLoggingBugTrackingInitialized => isEnabled && _isInitialized;

late final logging.LoggingApi _loggingApi;
Expand Down
Loading