vybekiit 0.7.25 → 0.7.27

package/dist/global-skills/instrument-product-analytics/references/flutter.md

@@ -1,10 +1,6 @@
 > AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
 
-# Flutter - Docs
-
-Copy page
-
-# Flutter - Docs
+# Flutter
 
 This is an optional library you can install if you're working with Flutter. It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your mobile app.
 
@@ -24,14 +20,14 @@ To start, add `posthog_flutter` to your `pubspec.yaml`:
 
 pubspec.yaml
 
-PostHog AI
-
 ```yaml
 # rest of your code
+
 dependencies:
   flutter:
     sdk: flutter
   posthog_flutter: ^5.26.0
+
 # rest of your code
 ```
 
@@ -49,8 +45,6 @@ Add your PostHog configuration to your `AndroidManifest.xml` file located in the
 
 android/app/src/main/AndroidManifest.xml
 
-PostHog AI
-
 ```xml
 <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
     <application>
@@ -69,8 +63,6 @@ Add your PostHog configuration to your `AndroidManifest.xml` file located in the
 
 android/app/src/main/AndroidManifest.xml
 
-PostHog AI
-
 ```xml
 <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
     <application>
@@ -84,14 +76,14 @@ In both cases, you'll also need to update the minimum Android SDK version to `23
 
 android/app/build.gradle
 
-PostHog AI
-
 ```kotlin
 // rest of your config
+
     defaultConfig {
         minSdkVersion 23
         // rest of your config
     }
+
 // rest of your config
 ```
 
@@ -99,7 +91,7 @@ PostHog AI
 
 There are 2 ways of initializing the SDK, automatically and manually.
 
-You'll need to have [Cocoapods](https://guides.cocoapods.org/using/getting-started.html) installed.
+The SDK supports both [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) and [Swift Package Manager (SPM)](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers). Flutter 3.44 and later enable SPM by default. On earlier versions, or if you disabled SPM, enable it with `flutter config --enable-swift-package-manager`.
 
 Automatically:
 
@@ -107,8 +99,6 @@ Add your PostHog configuration to the `Info.plist` file located in the `ios/Runn
 
 ios/Runner/Info.plist
 
-PostHog AI
-
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -132,8 +122,6 @@ Add your PostHog configuration to the `Info.plist` file located in the `ios/Runn
 
 ios/Runner/Info.plist
 
-PostHog AI
-
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -146,17 +134,25 @@ PostHog AI
 </plist>
 ```
 
-In both cases, you'll need to set the minimum platform version to iOS 13.0 in your Podfile:
+In both cases, you'll need to set the minimum platform version to iOS 13.0.
 
-ios/Podfile
+For CocoaPods projects, set it in your `Podfile`:
 
-PostHog AI
+ios/Podfile
 
 ```yaml
 platform :ios, '13.0'
 # rest of your config
 ```
 
+For Swift Package Manager projects without a `Podfile`, set the **Minimum Deployments** version to iOS 13.0 for the `Runner` target in Xcode (**Runner > General > Minimum Deployments**). After you change **Minimum Deployments**, regenerate the iOS project's configuration files:
+
+Terminal
+
+```bash
+flutter build ios --config-only
+```
+
 #### Dart setup (For manual step only)
 
 If you followed the automatic SDK setup, then there's no more configuration needed in Dart.
@@ -165,11 +161,11 @@ If you followed the manual SDK setup:
 
 Dart
 
-PostHog AI
-
 ```dart
 import 'package:flutter/material.dart';
+
 import 'package:posthog_flutter/posthog_flutter.dart';
+
 Future<void> main() async {
   // init WidgetsFlutterBinding if not yet
   WidgetsFlutterBinding.ensureInitialized();
@@ -184,17 +180,18 @@ Future<void> main() async {
 
 #### Web setup
 
-For Web, add your `Web snippet` (which you can find in [your project settings](https://us.posthog.com/settings/project#snippet)) in the `<header>` of your `web/index.html` file:
+If your project has a `web/` directory, this step is required. `Posthog().setup()` is a no-op on web, so a web build without the snippet below captures nothing.
 
-web/index.html
+Add your `Web snippet` (which you can find in [your project settings](https://us.posthog.com/settings/project#snippet)) in the `<header>` of your `web/index.html` file. Write your project token into the snippet as a literal string. It's public, the same token ships to every visitor, and it needs no build-time or deploy-time injection:
 
-PostHog AI
+web/index.html
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
     <!-- ... other head elements ... -->
+
     <script async>
       !(function (t, e) {
         var o, n, p, r;
@@ -218,13 +215,23 @@ PostHog AI
             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)";
-                },
+                Object.defineProperty(u, "toString", {
+                  configurable: !0,
+                  enumerable: !0,
+                  writable: !0,
+                  value: function (t) {
+                    var e = "posthog";
+                    return ("posthog" !== a && (e += "." + a), t || (e += " (stub)"), e);
+                  },
+                }),
+                Object.defineProperty(u.people, "toString", {
+                  configurable: !0,
+                  enumerable: !0,
+                  writable: !0,
+                  value: 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 getFeatureFlagResult reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(
                     " ",
@@ -244,6 +251,7 @@ PostHog AI
       });
     </script>
   </head>
+
   <!-- other elements -->
 </html>
 ```
@@ -256,8 +264,6 @@ You can send custom events using `capture`:
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().capture(
   eventName: 'user_signed_up',
@@ -272,8 +278,6 @@ Optionally, you can include additional information with the event by including a
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().capture(
   eventName: 'user_signed_up',
@@ -292,12 +296,16 @@ PostHog autocapture automatically tracks the following events for you:
 -   **Application Backgrounded** - when the app is sent to the background by the user
 -   **Application Installed** - when the app is installed.
 -   **Application Updated** - when the app is updated.
--   **$screen** - when the user navigates (if using [navigatorObservers](https://docs.flutter.dev/ui/navigation) or [go\_router](https://pub.dev/packages/go_router). You'd need to set up the `PosthogObserver` manually.)
+-   **$screen** - when the user navigates, once you add the `PosthogObserver`
 -   **$exception** - when the app throws exceptions.
 
 ### Capturing screen views
 
-> Note: Your routes should be named. Otherwise, they won't be recorded.
+Screen views aren't captured automatically. Add the `PosthogObserver` to your app yourself. Without it, your app sends no `$screen` events at all.
+
+This works with any routing package, not just the plain `Navigator` API. Add the observer wherever your router takes navigator observers, as shown below for `MaterialApp` and `go_router`.
+
+> Note: Screen names come from each route's `RouteSettings.name`. Most routing packages set this for you. If yours doesn't, name your routes so `$screen` events are readable.
 
 #### Using `navigatorObservers`
 
@@ -305,12 +313,12 @@ Add the `PosthogObserver` to record screen views automatically:
 
 Dart
 
-PostHog AI
-
 ```dart
 import 'package:flutter/material.dart';
 import 'package:posthog_flutter/posthog_flutter.dart';
+
 void main() => runApp(MyApp());
+
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
@@ -330,8 +338,6 @@ Name your routes:
 
 Dart
 
-PostHog AI
-
 ```dart
 ...
 MaterialPageRoute(builder: (context) => const HomeScreenRoute(),
@@ -346,12 +352,11 @@ Add the `PosthogObserver` to record screen views automatically:
 
 Dart
 
-PostHog AI
-
 ```dart
 import 'package:flutter/material.dart';
 import 'package:posthog_flutter/posthog_flutter.dart';
 import 'package:go_router/go_router.dart';
+
 // GoRouter configuration
 final _router = GoRouter(
   routes: [
@@ -360,6 +365,7 @@ final _router = GoRouter(
   // The PosthogObserver records screen views automatically
   observers: [PosthogObserver()],
 );
+
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
@@ -375,8 +381,6 @@ Name your routes:
 
 Dart
 
-PostHog AI
-
 ```dart
 ...
 GoRoute(
@@ -400,8 +404,6 @@ An `identify` call has the following arguments:
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().identify(
   userId: emailController.text,
@@ -428,15 +430,13 @@ In this case, you can use `alias` to assign another distinct ID to the same user
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().alias(
   alias: 'distinct_id',
 );
 ```
 
-We strongly recommend reading our docs on [alias](/docs/data/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method.
+We strongly recommend reading our docs on [alias](/docs/product-analytics/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method.
 
 ## Anonymous vs identified events
 
@@ -476,8 +476,6 @@ For example:
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.host = 'https://us.i.posthog.com';
@@ -506,10 +504,9 @@ For example, take a look at the following call:
 
 Dart
 
-PostHog AI
-
 ```dart
 import 'package:posthog_flutter/posthog_flutter.dart';
+
 await Posthog().register("team_id", 22);
 ```
 
@@ -523,10 +520,9 @@ Super properties are persisted across sessions so you have to explicitly remove
 
 Dart
 
-PostHog AI
-
 ```dart
 import 'package:posthog_flutter/posthog_flutter.dart';
+
 await Posthog().unregister("team_id");
 ```
 
@@ -548,12 +544,11 @@ PostHog's [feature flags](/docs/feature-flags.md) enable you to safely deploy an
 
 Dart
 
-PostHog AI
-
 ```dart
 final result = await Posthog().getFeatureFlagResult('flag-key');
 if (result != null && result.enabled) {
   // Do something differently for this user
+
   // Optional: fetch the payload from the same evaluation result
   final matchedFlagPayload = result.payload;
 }
@@ -563,12 +558,11 @@ if (result != null && result.enabled) {
 
 Dart
 
-PostHog AI
-
 ```dart
 final result = await Posthog().getFeatureFlagResult('flag-key');
 if (result != null && result.variant == 'variant-key') { // replace 'variant-key' with the key of your variant
   // Do something differently for this user
+
   // Optional: fetch the payload from the same evaluation result
   final matchedFlagPayload = result.payload;
 }
@@ -586,8 +580,6 @@ To handle this, you can use the `onFeatureFlags` callback in your config to be n
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.host = 'https://us.i.posthog.com';
@@ -605,8 +597,6 @@ Feature flag values are cached. If something has changed with your user and you'
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().reloadFeatureFlags();
 ```
@@ -621,8 +611,6 @@ Set `config.bootstrap` before calling `setup()` to seed identity and flag values
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.host = 'https://us.i.posthog.com';
@@ -654,14 +642,13 @@ If a flag targets person or group properties, you can send those properties inli
 
 Dart
 
-PostHog AI
-
 ```dart
 // Person properties — included in the next flag evaluation request
 await Posthog().setPersonPropertiesForFlags({
   'storefront_country': 'US',
   'is_beta_user': true,
 });
+
 // Group properties
 await Posthog().setGroupPropertiesForFlags('company', {'plan': 'enterprise'});
 ```
@@ -710,8 +697,6 @@ You can also configure the flush interval with `flushInterval` (default 30 secon
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.flushAt = 20;
@@ -722,8 +707,6 @@ You can also manually flush the queue to start sending events immediately instea
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().flush();
 ```
@@ -744,8 +727,6 @@ You can disable data collection for a user at any time using the `disable()` met
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().disable();
 ```
@@ -754,8 +735,6 @@ This prevents any future events from being sent. It doesn't remove events alread
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().enable();
 ```
@@ -764,8 +743,6 @@ To check if a user is opted out:
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().isOptOut();
 ```
@@ -780,11 +757,10 @@ Since version 5.13.0, you can provide `beforeSend` callbacks when initializing t
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.host = 'https://us.i.posthog.com';
+
 config.beforeSend = [
   (event) {
     // Redact email from properties
@@ -794,6 +770,7 @@ config.beforeSend = [
     return event;
   },
 ];
+
 await Posthog().setup(config);
 ```
 
@@ -803,8 +780,6 @@ Return `null` from the callback to drop the event:
 
 Dart
 
-PostHog AI
-
 ```dart
 config.beforeSend = [
   (event) {
@@ -825,10 +800,9 @@ Because it's just a function, you can filter however you like – an **ignorelis
 
 Dart
 
-PostHog AI
-
 ```dart
 const ignoredScreens = {'Splash', 'Debug'};
+
 config.beforeSend = [
   (event) {
     final screenName = event.properties?['$screen_name'];
@@ -863,8 +837,6 @@ You can enable debug mode during initialization by setting the `debug` option to
 
 Dart
 
-PostHog AI
-
 ```dart
 final config = PostHogConfig('<ph_project_token>');
 config.host = 'https://us.i.posthog.com';
@@ -878,8 +850,6 @@ You can also enable debug by calling the `Posthog().debug()` method in your code
 
 Dart
 
-PostHog AI
-
 ```dart
 await Posthog().debug(true);
 await Posthog().debug(false);