From 61faf2c3bd7caa5707acb70517cbe9e9823cab15 Mon Sep 17 00:00:00 2001 From: Matias de Andrea Date: Tue, 10 Feb 2026 19:01:25 +0100 Subject: [PATCH] feat: Enhance Posthog SDK documentation methods --- lib/src/posthog.dart | 98 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 6 deletions(-) diff --git a/lib/src/posthog.dart b/lib/src/posthog.dart index bdb05de..04d0c58 100644 --- a/lib/src/posthog.dart +++ b/lib/src/posthog.dart @@ -72,6 +72,20 @@ class Posthog { @internal String? get currentScreen => _currentScreen; + /// Can associate events with specific users + /// + /// - [userId] A unique identifier for your user. Typically either their email or database ID. + /// - [userProperties] the user properties, set as a "$set" property, + /// - [userPropertiesSetOnce] the user properties to set only once, set as a "$set_once" property. + /// + /// **Example:** + /// ```dart + /// await Posthog().identify( + /// userId: emailController.text, + /// userProperties: {"name": "Peter Griffin", "email": "peter@familyguy.com"}, + /// userPropertiesSetOnce: {"date_of_first_log_in": "2024-03-01"} + /// ); + /// ``` Future identify({ required String userId, Map? userProperties, @@ -82,6 +96,29 @@ class Posthog { userProperties: userProperties, userPropertiesSetOnce: userPropertiesSetOnce); + /// Captures events. + /// Docs https://posthog.com/docs/product-analytics/user-properties + /// + /// We recommend using a [object] [verb] format for your event names, + /// where [object] is the entity that the behavior relates to, + /// and [verb] is the behavior itself. + /// For example, project created, user signed up, or invite sent. + /// + /// - [eventName] name of event + /// - [properties] the custom properties + /// - [userProperties] the user properties, set as a "$set" property, + /// - [userPropertiesSetOnce] the user properties to set only once, set as a "$set_once" property. + /// + /// **Example** + /// ```dart + /// await Posthog().capture( + /// eventName: 'user_signed_up', + /// properties: { + /// 'login_type': 'email', + /// 'is_free_trial': true + /// } + /// ); + /// ``` Future capture({ required String eventName, Map? properties, @@ -104,6 +141,10 @@ class Posthog { ); } + /// Captures a screen view event + /// + /// - [screenName] the screen title + /// - [properties] the custom properties Future screen({ required String screenName, Map? properties, @@ -115,6 +156,10 @@ class Posthog { ); } + /// Creates an alias for the user. + /// Docs https://posthog.com/docs/product-analytics/identify#alias-assigning-multiple-distinct-ids-to-the-same-user + /// + /// - [alias] the alias Future alias({ required String alias, }) => @@ -122,10 +167,15 @@ class Posthog { alias: alias, ); + /// Returns the registered `distinctId` property Future getDistinctId() => _posthog.getDistinctId(); + /// Resets all the cached properties including the `distinctId`. + /// + /// The SDK will behave as its been [setup] for the first time Future reset() => _posthog.reset(); + /// Disable data collection for a user Future disable() { // Uninstall Flutter-specific integrations when disabling _uninstallFlutterIntegrations(); @@ -133,21 +183,56 @@ class Posthog { return _posthog.disable(); } + /// Enable data collection for a user Future enable() => _posthog.enable(); + /// Check if the user has opted out of data collection Future isOptOut() => _posthog.isOptOut(); + /// Enable or disable verbose logs about the inner workings of the SDK. + /// + /// - [enabled] whether to enable or disable debug logs Future debug(bool enabled) => _posthog.debug(enabled); + /// Register a property to always be sent with all the following events until you call + /// [unregister] with the same key. + /// + /// - [key] the Key + /// - [value] the Value Future register(String key, Object value) => _posthog.register(key, value); + /// Unregisters the previously set property to be sent with all the following events + /// + /// [key] the Key Future unregister(String key) => _posthog.unregister(key); + /// Returns if a feature flag is enabled, the feature flag must be a Boolean + /// + /// Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments + /// + /// - [key] the Key of the feature Future isFeatureEnabled(String key) => _posthog.isFeatureEnabled(key); + /// Reloads the feature flags Future reloadFeatureFlags() => _posthog.reloadFeatureFlags(); + /// Creates a group. + /// Docs https://posthog.com/docs/product-analytics/group-analytics + /// + /// - [groupType] the Group type + /// - [groupKey] the Group key + /// - [groupProperties] the Group properties, set as a "$group_set" property. + /// + /// **Example:** + /// ```dart + /// await Posthog().group( + /// groupType: "company", + /// groupKey: "company_id_in_your_db", + /// groupProperties: { + /// "name": "ACME Corp" + /// }); + /// ``` Future group({ required String groupType, required String groupKey, @@ -197,9 +282,9 @@ class Posthog { /// Captures exceptions with optional custom properties /// - /// [error] - The error/exception to capture - /// [stackTrace] - Optional stack trace (if not provided, current stack trace will be used) - /// [properties] - Optional custom properties to attach to the exception event + /// - [error] - The error/exception to capture + /// - [stackTrace] - Optional stack trace (if not provided, current stack trace will be used) + /// - [properties] - Optional custom properties to attach to the exception event Future captureException( {required Object error, StackTrace? stackTrace, @@ -210,9 +295,9 @@ class Posthog { /// Captures runZonedGuarded exceptions with optional custom properties /// https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html /// - /// [error] - The error/exception to capture - /// [stackTrace] - Optional stack trace (if not provided, current stack trace will be used) - /// [properties] - Optional custom properties to attach to the exception event + /// - [error] - The error/exception to capture + /// - [stackTrace] - Optional stack trace (if not provided, current stack trace will be used) + /// - [properties] - Optional custom properties to attach to the exception event Future captureRunZonedGuardedError( {required Object error, StackTrace? stackTrace, @@ -237,6 +322,7 @@ class Posthog { return _posthog.close(); } + /// Returns the session Id if a session is active Future getSessionId() => _posthog.getSessionId(); Posthog._internal();