feat: add manual start and stop recording

[ioannisj]

💡 Motivation and Context

Closes #124
Docs PR: PostHog/posthog.com#14487

• Add manual session recording control APIs (iOS, Android, Web)
• Expose isSessionReplayActive to match iOS and Android implementation

💚 How did you test it?

Manual testing:

• iOS
• Android
• Web

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

[marandaneto]

left 2 comments otherwise LGTM

[ForTheYin]

Hi PostHog team,

Thanks for adding this feature for Flutter. I've tried out this feature branch on an app and followed the instructions here.

I have the PostHogConfig.sessionReplay boolean set to false and then I attempted to manually record a session.

This is my config:

    final posthogConfig = PostHogConfig(_config.posthogApiKey);
    posthogConfig.host = _config.posthogHost;
    posthogConfig.debug = kDebugMode;
    posthogConfig.captureApplicationLifecycleEvents = true;
    posthogConfig.sessionReplay = false;
    posthogConfig.sessionReplayConfig.maskAllTexts = false;
    posthogConfig.sessionReplayConfig.maskAllImages = false;

   // Some time later...
   Posthog().startSessionRecording(resumeCurrent: false)

   // Also tried it with
   Posthog().startSessionRecording(resumeCurrent: true)

Both startSessionRecording usages create recordings that have timestamps, but no content in the session replay preview (no images fetched).

---

The recording work normally when I set sessionReplay to true, but then this creates a unwanted session replay.

I also tried to manually remove the config.sessionReplay check in PostHogWidget, but that didn't work either.

    // posthog_widget.dart - PostHogWidgetState, L34
    if (config == null || !config.sessionReplay) {
      return;
    }

---

iOS 26.0 Simulator & a real Device, Flutter 3.35.7

[ioannisj]

Hey @ForTheYin thanx for testing this out! 🙏 I also noticed the same thing happen to me yesterday during a final test before releasing and held off the merge. This used to work fine before so it must be either some late changes made here or in the ingestion side of things. I'll try to sort this asap

[ioannisj]

Actually let me correct myself, this used to work with the config enabled, so the happy path you describe here. I bumped into the same issue when config was disabled

[ioannisj]

Okay turns out that PostHogWidget was disabled because of config, and we had no way of dynamically re-enabling it.

@marandaneto pushed a fix for this in c385b62. Used an internal ValueNotifier cause I didn't wanat to couple PostHog with PostHogWidget. Could not think of a better alternative. Worth a second look