feat: manual start/stop session recording

[ioannisj]

💡 Motivation and Context

Closes #262, #227

Docs PR: PostHog/posthog.com#10235

Added the following:

• startSessionRecording(resumeCurrent: Bool)
• stopSessionRecording()

Session Management

Related discussion: https://posthog.slack.com/archives/C03PB072FMJ/p1733146678787689?thread_ts=1732810962.491699&cid=C03PB072FMJ

Based on the discussion above, I refactored how we manager and rotate replay sessions. Quite a big change but the main points of the change are:

• Internal getSessionId changes form and is now responsible on running validation rules and rotates or clears the session if needed before returning
• getSessionId can be called with readOnly to skip validation and just return current session id. In both cases, a new id will be created if it doesn't exist but only when the app is foregrounded
• Validation rules are:
  • Rotates session after 30 minutes of inactivity
  • Clears session after 30 minutes of inactivity (when app is backgrounded at the time of calling this method)
  • Enforces a maximum session duration of 24 hours
  • All validations can be run against a given timestamp, otherwise .now is used. For replay, we capture the timestamp of the event as soon as possible, so we need to run session validation checks on that timestamp to account for delayed captures
• $snapshot events add their own $session_id property which is acquired as early as possible and capture() method will respect that $session_id
• $snapshot events always call capture() with a given timestamp, acquired as early as possible
• Added a reason on hedgeLog messages related to session id changes for debugging purposes

TODO:

• Skip $snapshot events if $session_id is missing from event properties

💚 How did you test it?

• Unit tests
• Added a section in PostHogExample for manual testing
• Objc project interface

📝 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.

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Next" section. Make sure the entry includes this PR's number.
Example:

## Next
- manual start/stop session recording ([#276](https://github.com/PostHog/posthog-ios/pull/276))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description.

Generated by 🚫 dangerJS against 0783154