Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions .github/workflows/generate-references.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Generate references

# Regenerates references/ by hand, for when the release's best-effort reference step fails
# or the pages need a refresh. Same shape as posthog-js's generate-references.yml.
on:
workflow_dispatch:

permissions: {}

jobs:
generate-references:
name: Generate SDK reference
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Get GitHub App token
id: releaser
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
client-id: ${{ secrets.GH_APP_POSTHOG_FLUTTER_RELEASER_APP_ID }}
private-key: ${{ secrets.GH_APP_POSTHOG_FLUTTER_RELEASER_PRIVATE_KEY }}

- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: main
token: ${{ steps.releaser.outputs.token }}

- name: Check out sdk-specs
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: PostHog/sdk-specs
path: .sdk-specs
persist-credentials: false

- name: Set up Flutter
uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30
with:
channel: 'stable'

- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.13'

- name: Generate references
id: changes
run: |
python3 -m pip install --quiet -r scripts/requirements.txt
python3 scripts/generate_markdown_reference.py --sdk-specs .sdk-specs
git add references
git diff --cached --quiet || echo "changed=true" >> "$GITHUB_OUTPUT"

- name: Commit generated references
if: steps.changes.outputs.changed == 'true'
uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22
with:
commit_message: "docs: update the SDK reference [skip ci]"
repo: ${{ github.repository }}
branch: main
file_pattern: references/
env:
GITHUB_TOKEN: ${{ steps.releaser.outputs.token }}
49 changes: 49 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,55 @@ jobs:
git tag -a "$NEW_VERSION" -m "$NEW_VERSION"
git push origin "$NEW_VERSION"

# The reference headings come from the sdk-specs capabilities.
- name: Check out sdk-specs
# Best-effort: a failure never blocks the release. Run generate-references.yml to retry.
continue-on-error: true
if: steps.commit-version-bump.outputs.commit-hash != ''
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: PostHog/sdk-specs
path: .sdk-specs
persist-credentials: false

# The generator runs `flutter pub get` and `dart doc`. Same pinned action as ci.yml.
- uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30
if: steps.commit-version-bump.outputs.commit-hash != ''
with:
channel: 'stable'
Comment on lines +175 to +178

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 · Apply best-effort handling to every reference step

When Flutter setup, Python setup, or the reference commit fails, the added steps fail the release job because they lack continue-on-error. The tag has already been pushed, so the workflow emits release-preparation failure alerts while publishing proceeds independently. Extend best-effort handling to the reference setup and commit steps.


# Ubuntu's system Python refuses a plain pip install (externally managed).
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
if: steps.commit-version-bump.outputs.commit-hash != ''
with:
python-version: '3.13'

- name: Generate references
Comment thread
gewenyu99 marked this conversation as resolved.
Resolved
id: reference
# Best-effort: a failure never blocks the release. Run generate-references.yml to retry.
continue-on-error: true
if: steps.commit-version-bump.outputs.commit-hash != ''
Comment thread
gewenyu99 marked this conversation as resolved.
Resolved
run: |
python3 -m pip install --quiet -r scripts/requirements.txt
Comment thread
gewenyu99 marked this conversation as resolved.
Resolved
python3 scripts/generate_markdown_reference.py --sdk-specs .sdk-specs
# Stage the pages, so a new page shows in git status as a file, not as an untracked folder.
git add references

- name: Warn if the SDK reference didn't regenerate
if: steps.reference.outcome == 'failure'
run: echo "::warning::The SDK reference didn't regenerate. Run generate-references.yml to retry."

- name: Commit generated references
if: steps.commit-version-bump.outputs.commit-hash != ''
uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22
Comment thread
gewenyu99 marked this conversation as resolved.
Resolved
with:
commit_message: 'Update generated references'
repo: ${{ github.repository }}
branch: main
file_pattern: references/
env:
GITHUB_TOKEN: ${{ steps.releaser.outputs.token }}

- name: Send failure event to PostHog
if: ${{ failure() }}
continue-on-error: true
Expand Down
53 changes: 53 additions & 0 deletions docs/capabilities.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
{
"Posthog.addExceptionStep": "exception-steps",
"Posthog.alias": "alias",
"Posthog.capture": "capture",
"Posthog.captureException": "capture-exception",
"Posthog.captureLog": "logs",
"Posthog.captureRunZonedGuardedError": "capture-exception",
"Posthog.close": "shutdown",
"Posthog.debug": "debug",
"Posthog.flush": "flush",
"Posthog.getAllFeatureFlags": "get-feature-flags",
"Posthog.getDistinctId": "get-distinct-id",
"Posthog.getFeatureFlag": "get-feature-flag",
"Posthog.getFeatureFlagPayload": "get-feature-flag-payload",
"Posthog.getFeatureFlagResult": "get-feature-flag-result",
"Posthog.getSessionId": "get-session-id",
"Posthog.group": "group",
"Posthog.identify": "identify",
"Posthog.isFeatureEnabled": "is-feature-enabled",
"Posthog.isOptOut": "is-opt-out",
"Posthog.isSessionReplayActive": "is-session-replay-active",
"Posthog.logger": "logs",
"Posthog.optIn": "opt-in",
"Posthog.register": "register",
"Posthog.reloadFeatureFlags": "reload-feature-flags",
"Posthog.reset": "reset",
"Posthog.resetGroupPropertiesForFlags": "reset-group-properties-for-flags",
"Posthog.resetPersonPropertiesForFlags": "reset-person-properties-for-flags",
"Posthog.screen": "screen",
"Posthog.setGroupPropertiesForFlags": "set-group-properties-for-flags",
"Posthog.setPersonProperties": "set-person-properties",
"Posthog.setPersonPropertiesForFlags": "set-person-properties-for-flags",
"Posthog.setup": "setup",
"Posthog.startSessionRecording": "start-session-recording",
"Posthog.stopSessionRecording": "stop-session-recording",
"Posthog.unregister": "unregister",
"next": {
"Posthog.captureAi": "capture-ai",
"Posthog.onFeatureFlags": "on-feature-flags"
},
"utils": [
"Posthog.Posthog.new",
"Posthog.captureFeatureInteraction",
"Posthog.captureFeatureView",
"Posthog.capturePushNotificationOpened",
"Posthog.disable",
"Posthog.enable",
"Posthog.optOut",
"Posthog.registerPushNotificationToken",
"Posthog.setAppLanguage",
"Posthog.unregisterPushNotificationToken"
]
}
44 changes: 44 additions & 0 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Getting started

The Flutter SDK runs in iOS, Android, macOS, and web apps.

To send your first event, add `posthog_flutter`, then call `setup` once before `runApp` with your project token and host from your [project settings](https://app.posthog.com/project/settings).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 · Include the required JavaScript initialization for web

For a fresh Flutter web app, these instructions leave window.posthog undefined: PosthogFlutterWeb.setup only binds to an existing JavaScript SDK and never initializes it. Subsequent capture and identify calls therefore send no events despite following the guide. Add the required posthog-js loading and initialization steps for web.


Use `capture` for your own events, and call `flush` and `close` before the app exits.

Install the package:

```bash
flutter pub add posthog_flutter
```

Initialize the SDK once, before `runApp`, with your project token and host:

```dart
import 'package:flutter/widgets.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();

final config = PostHogConfig('<ph_project_token>');
config.host = 'https://us.i.posthog.com';
await Posthog().setup(config);

runApp(const MyApp());
}
```

Capture an event and identify the user:

```dart
await Posthog().capture(eventName: 'user_signed_up', properties: {'plan': 'free'});
await Posthog().identify(userId: 'user_123', userProperties: {'email': 'a@example.com'});
```

Flush queued events and shut the SDK down before the app exits:

```dart
await Posthog().flush();
await Posthog().close();
```
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,15 @@ enum PostHogPlatformViewPrivacy {
/// This widget has no runtime state — it is a pure marker. The compositor reads
/// [privacy] from the element tree during each capture frame.
class PostHogPlatformView extends StatelessWidget {
/// The platform view subtree this policy applies to.
final Widget child;

/// How the platform views in [child] are handled in session replay.
///
/// Defaults to [PostHogPlatformViewPrivacy.mask].
final PostHogPlatformViewPrivacy privacy;

/// Creates a session replay policy marker around [child].
const PostHogPlatformView({
super.key,
required this.child,
Expand Down
Loading
Loading