chore: Expose userProperties, userPropertiesSetOnce capture method (#254)

marandaneto · web-flow · commit ea8e6ad6b071 · 2026-01-22T15:21:42.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,7 @@
 ## Next
 
+- feat: add `userProperties` and `userPropertiesSetOnce` parameters to `capture()` method ([#254](https://github.com/PostHog/posthog-flutter/pull/254))
+
 # 5.11.1
 
 - fix: RichText, SelectableText, TextField labels and hints not being masked in session replay ([#251](https://github.com/PostHog/posthog-flutter/pull/251))
diff --git a/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt b/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt
@@ -389,7 +389,14 @@ class PosthogFlutterPlugin :
         try {
             val eventName: String = call.argument("eventName")!!
             val properties: Map<String, Any>? = call.argument("properties")
-            PostHog.capture(eventName, properties = properties)
+            val userProperties: Map<String, Any>? = call.argument("userProperties")
+            val userPropertiesSetOnce: Map<String, Any>? = call.argument("userPropertiesSetOnce")
+            PostHog.capture(
+                eventName,
+                properties = properties,
+                userProperties = userProperties,
+                userPropertiesSetOnce = userPropertiesSetOnce,
+            )
             result.success(null)
         } catch (e: Throwable) {
             result.error("PosthogFlutterException", e.localizedMessage, null)
diff --git a/example/lib/main.dart b/example/lib/main.dart
@@ -8,7 +8,7 @@ Future<void> main() async {
 
   WidgetsFlutterBinding.ensureInitialized();
   final config =
-      PostHogConfig('phc_QFbR1y41s5sxnNTZoyKG2NJo2RlsCIWkUfdpawgb40D');
+      PostHogConfig('phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06');
   config.onFeatureFlags = () {
     debugPrint('[PostHog] Feature flags loaded!');
   };
@@ -127,6 +127,10 @@ class InitialScreenState extends State<InitialScreen> {
                         _posthogFlutterPlugin
                             .capture(eventName: "eventName", properties: {
                           "foo": "bar",
+                        }, userProperties: {
+                          "user_foo": "user_bar",
+                        }, userPropertiesSetOnce: {
+                          "user_foo_once": "user_bar_once",
                         });
                       },
                       child: const Text("Capture Event"),
diff --git a/example/web/index.html b/example/web/index.html
@@ -36,7 +36,7 @@
   <script async>
     !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
     posthog.init(
-      'phc_QFbR1y41s5sxnNTZoyKG2NJo2RlsCIWkUfdpawgb40D',
+      'phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06',
       {
         api_host:'https://us.i.posthog.com',
         debug: true,
diff --git a/ios/Classes/PosthogFlutterPlugin.swift b/ios/Classes/PosthogFlutterPlugin.swift
@@ -560,9 +560,13 @@ extension PosthogFlutterPlugin {
            let eventName = args["eventName"] as? String
         {
             let properties = args["properties"] as? [String: Any]
+            let userProperties = args["userProperties"] as? [String: Any]
+            let userPropertiesSetOnce = args["userPropertiesSetOnce"] as? [String: Any]
             PostHogSDK.shared.capture(
                 eventName,
-                properties: properties
+                properties: properties,
+                userProperties: userProperties,
+                userPropertiesSetOnce: userPropertiesSetOnce
             )
             result(nil)
         } else {
diff --git a/lib/posthog_flutter_web.dart b/lib/posthog_flutter_web.dart
@@ -9,6 +9,8 @@ import 'package:flutter_web_plugins/flutter_web_plugins.dart';
 import 'src/posthog_config.dart';
 import 'src/posthog_flutter_platform_interface.dart';
 import 'src/posthog_flutter_web_handler.dart';
+import 'src/utils/capture_utils.dart';
+import 'src/utils/property_normalizer.dart';
 
 /// A web implementation of the PosthogFlutterPlatform of the PosthogFlutter plugin.
 class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
@@ -89,10 +91,37 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
   Future<void> capture({
     required String eventName,
     Map<String, Object>? properties,
+    Map<String, Object>? userProperties,
+    Map<String, Object>? userPropertiesSetOnce,
   }) async {
+    final extracted = CaptureUtils.extractUserProperties(
+      properties: properties,
+      userProperties: userProperties,
+      userPropertiesSetOnce: userPropertiesSetOnce,
+    );
+
+    final extractedProperties = extracted.properties;
+    final extractedUserProperties = extracted.userProperties;
+    final extractedUserPropertiesSetOnce = extracted.userPropertiesSetOnce;
+
+    final normalizedProperties = extractedProperties != null
+        ? PropertyNormalizer.normalize(extractedProperties)
+        : null;
+    final normalizedUserProperties = extractedUserProperties != null
+        ? PropertyNormalizer.normalize(extractedUserProperties)
+        : null;
+    final normalizedUserPropertiesSetOnce =
+        extractedUserPropertiesSetOnce != null
+            ? PropertyNormalizer.normalize(extractedUserPropertiesSetOnce)
+            : null;
+
     return handleWebMethodCall(MethodCall('capture', {
       'eventName': eventName,
-      if (properties != null) 'properties': properties,
+      if (normalizedProperties != null) 'properties': normalizedProperties,
+      if (normalizedUserProperties != null)
+        'userProperties': normalizedUserProperties,
+      if (normalizedUserPropertiesSetOnce != null)
+        'userPropertiesSetOnce': normalizedUserPropertiesSetOnce,
     }));
   }
 
diff --git a/lib/src/posthog.dart b/lib/src/posthog.dart
@@ -83,6 +83,8 @@ class Posthog {
   Future<void> capture({
     required String eventName,
     Map<String, Object>? properties,
+    Map<String, Object>? userProperties,
+    Map<String, Object>? userPropertiesSetOnce,
   }) {
     final propertiesCopy = properties == null ? null : {...properties};
 
@@ -95,6 +97,8 @@ class Posthog {
     return _posthog.capture(
       eventName: eventName,
       properties: propertiesCopy,
+      userProperties: userProperties,
+      userPropertiesSetOnce: userPropertiesSetOnce,
     );
   }
 
diff --git a/lib/src/posthog_flutter_io.dart b/lib/src/posthog_flutter_io.dart
@@ -10,6 +10,7 @@ import 'package:posthog_flutter/src/util/logging.dart';
 import 'surveys/models/posthog_display_survey.dart' as models;
 import 'surveys/models/survey_callbacks.dart';
 import 'error_tracking/dart_exception_processor.dart';
+import 'utils/capture_utils.dart';
 import 'utils/property_normalizer.dart';
 
 import 'posthog_config.dart';
@@ -175,18 +176,42 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface {
   Future<void> capture({
     required String eventName,
     Map<String, Object>? properties,
+    Map<String, Object>? userProperties,
+    Map<String, Object>? userPropertiesSetOnce,
   }) async {
     if (!isSupportedPlatform()) {
       return;
     }
 
     try {
-      final normalizedProperties =
-          properties != null ? PropertyNormalizer.normalize(properties) : null;
+      final extracted = CaptureUtils.extractUserProperties(
+        properties: properties,
+        userProperties: userProperties,
+        userPropertiesSetOnce: userPropertiesSetOnce,
+      );
+
+      final extractedProperties = extracted.properties;
+      final extractedUserProperties = extracted.userProperties;
+      final extractedUserPropertiesSetOnce = extracted.userPropertiesSetOnce;
+
+      final normalizedProperties = extractedProperties != null
+          ? PropertyNormalizer.normalize(extractedProperties)
+          : null;
+      final normalizedUserProperties = extractedUserProperties != null
+          ? PropertyNormalizer.normalize(extractedUserProperties)
+          : null;
+      final normalizedUserPropertiesSetOnce =
+          extractedUserPropertiesSetOnce != null
+              ? PropertyNormalizer.normalize(extractedUserPropertiesSetOnce)
+              : null;
 
       await _methodChannel.invokeMethod('capture', {
         'eventName': eventName,
         if (normalizedProperties != null) 'properties': normalizedProperties,
+        if (normalizedUserProperties != null)
+          'userProperties': normalizedUserProperties,
+        if (normalizedUserPropertiesSetOnce != null)
+          'userPropertiesSetOnce': normalizedUserPropertiesSetOnce,
       });
     } on PlatformException catch (exception) {
       printIfDebug('Exeption on capture: $exception');
diff --git a/lib/src/posthog_flutter_platform_interface.dart b/lib/src/posthog_flutter_platform_interface.dart
@@ -44,6 +44,8 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface {
   Future<void> capture({
     required String eventName,
     Map<String, Object>? properties,
+    Map<String, Object>? userProperties,
+    Map<String, Object>? userPropertiesSetOnce,
   }) {
     throw UnimplementedError('capture() has not been implemented.');
   }
diff --git a/lib/src/posthog_flutter_web_handler.dart b/lib/src/posthog_flutter_web_handler.dart
@@ -12,7 +12,7 @@ class PostHog {}
 extension PostHogExtension on PostHog {
   external JSAny? identify(
       JSAny userId, JSAny properties, JSAny propertiesSetOnce);
-  external JSAny? capture(JSAny eventName, JSAny properties);
+  external JSAny? capture(JSAny eventName, JSAny? properties, JSAny? options);
   external JSAny? alias(JSAny alias);
   // ignore: non_constant_identifier_names
   external JSAny? get_distinct_id();
@@ -89,10 +89,24 @@ Future<dynamic> handleWebMethodCall(MethodCall call) async {
     case 'capture':
       final eventName = args['eventName'] as String;
       final properties = safeMapConversion(args['properties']);
+      final userProperties = safeMapConversion(args['userProperties']);
+      final userPropertiesSetOnce =
+          safeMapConversion(args['userPropertiesSetOnce']);
+
+      // Build options object for posthog-js capture with $set and $set_once
+      // See: https://github.com/PostHog/posthog-js/blob/main/packages/types/src/capture.ts
+      final options = <String, Object>{};
+      if (userProperties.isNotEmpty) {
+        options['\$set'] = userProperties;
+      }
+      if (userPropertiesSetOnce.isNotEmpty) {
+        options['\$set_once'] = userPropertiesSetOnce;
+      }
 
       posthog?.capture(
         stringToJSAny(eventName),
-        mapToJSAny(properties),
+        properties.isNotEmpty ? mapToJSAny(properties) : null,
+        options.isNotEmpty ? mapToJSAny(options) : null,
       );
       break;
     case 'screen':
@@ -103,6 +117,7 @@ Future<dynamic> handleWebMethodCall(MethodCall call) async {
       posthog?.capture(
         stringToJSAny('\$screen'),
         mapToJSAny(properties),
+        null,
       );
       break;
     case 'alias':
diff --git a/lib/src/surveys/survey_service.dart b/lib/src/surveys/survey_service.dart
@@ -101,9 +101,10 @@ class SurveyService {
 
   /// Hides any active survey
   void hideSurvey() {
-    if (_isShowingSurvey && _currentSurveyContext != null) {
+    final context = _currentSurveyContext;
+    if (_isShowingSurvey && context != null) {
       // Use the stored context to properly dismiss the bottom sheet
-      Navigator.of(_currentSurveyContext!).pop();
+      Navigator.of(context).pop();
       _currentSurveyContext = null;
     }
     _isShowingSurvey = false;
diff --git a/lib/src/surveys/widgets/rating_question.dart b/lib/src/surveys/widgets/rating_question.dart
@@ -204,12 +204,17 @@ class _RatingQuestionState extends State<RatingQuestion> {
             ),
           ),
         const SizedBox(height: 24),
-        SurveyButton(
-          onPressed: _canSubmit ? () => widget.onSubmit(_rating!) : null,
-          text: widget.buttonText ?? 'Submit',
-          appearance: widget.appearance,
-          enabled: _canSubmit,
-        ),
+        Builder(builder: (context) {
+          final rating = _rating;
+          return SurveyButton(
+            onPressed: _canSubmit && rating != null
+                ? () => widget.onSubmit(rating)
+                : null,
+            text: widget.buttonText ?? 'Submit',
+            appearance: widget.appearance,
+            enabled: _canSubmit,
+          );
+        }),
       ],
     );
   }
diff --git a/lib/src/utils/capture_utils.dart b/lib/src/utils/capture_utils.dart
@@ -0,0 +1,72 @@
+/// Result of extracting user properties from capture properties.
+class ExtractedCaptureProperties {
+  /// The properties map with $set and $set_once removed.
+  final Map<String, Object>? properties;
+
+  /// Merged user properties from $set in properties and userProperties parameter.
+  final Map<String, Object>? userProperties;
+
+  /// Merged user properties from $set_once in properties and userPropertiesSetOnce parameter.
+  final Map<String, Object>? userPropertiesSetOnce;
+
+  ExtractedCaptureProperties({
+    this.properties,
+    this.userProperties,
+    this.userPropertiesSetOnce,
+  });
+}
+
+/// Utility class for capture-related operations.
+class CaptureUtils {
+  /// Extracts $set and $set_once from properties for backward compatibility,
+  /// merges them with the new userProperties and userPropertiesSetOnce parameters,
+  /// and returns the cleaned properties along with the merged user properties.
+  ///
+  /// New parameters (userProperties, userPropertiesSetOnce) take precedence
+  /// over legacy $set and $set_once in properties.
+  static ExtractedCaptureProperties extractUserProperties({
+    Map<String, Object>? properties,
+    Map<String, Object>? userProperties,
+    Map<String, Object>? userPropertiesSetOnce,
+  }) {
+    // Create a mutable copy of properties to extract $set and $set_once
+    final propertiesCopy =
+        properties != null ? Map<String, Object>.from(properties) : null;
+
+    // Extract $set and $set_once from properties for backward compatibility
+    Map<String, Object>? legacyUserProperties;
+    Map<String, Object>? legacyUserPropertiesSetOnce;
+
+    if (propertiesCopy != null) {
+      if (propertiesCopy['\$set'] is Map<String, Object>) {
+        legacyUserProperties =
+            Map<String, Object>.from(propertiesCopy['\$set'] as Map);
+        propertiesCopy.remove('\$set');
+      }
+      if (propertiesCopy['\$set_once'] is Map<String, Object>) {
+        legacyUserPropertiesSetOnce =
+            Map<String, Object>.from(propertiesCopy['\$set_once'] as Map);
+        propertiesCopy.remove('\$set_once');
+      }
+    }
+
+    // Merge legacy properties with new parameters (new parameters take precedence)
+    final mergedUserProperties = <String, Object>{
+      ...?legacyUserProperties,
+      ...?userProperties,
+    };
+    final mergedUserPropertiesSetOnce = <String, Object>{
+      ...?legacyUserPropertiesSetOnce,
+      ...?userPropertiesSetOnce,
+    };
+
+    return ExtractedCaptureProperties(
+      properties: propertiesCopy,
+      userProperties:
+          mergedUserProperties.isNotEmpty ? mergedUserProperties : null,
+      userPropertiesSetOnce: mergedUserPropertiesSetOnce.isNotEmpty
+          ? mergedUserPropertiesSetOnce
+          : null,
+    );
+  }
+}
diff --git a/test/capture_utils_test.dart b/test/capture_utils_test.dart

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@`
`36`	`36`	`<script async>`
`37`	`37`	!function(t,e){var o,n,p,r;e.__SV\|\|(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people\|\|[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t\|\|(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog\|\|[]);
`38`	`38`	`posthog.init(`
`39`		`- 'phc_QFbR1y41s5sxnNTZoyKG2NJo2RlsCIWkUfdpawgb40D',`
	`39`	`+ 'phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06',`
`40`	`40`	`{`
`41`	`41`	`api_host:'https://us.i.posthog.com',`
`42`	`42`	`debug: true,`
Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,8 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface {`
`44`	`44`	`Future<void> capture({`
`45`	`45`	`required String eventName,`
`46`	`46`	`Map<String, Object>? properties,`
	`47`	`+ Map<String, Object>? userProperties,`
	`48`	`+ Map<String, Object>? userPropertiesSetOnce,`
`47`	`49`	`}) {`
`48`	`50`	`throw UnimplementedError('capture() has not been implemented.');`
`49`	`51`	`}`