Repository navigation
docs: generate the SDK reference as Markdown with dart doc #705
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
427eac2
e222266
a032552
a0a5bf3
a152f9d
c817ab0
371f1b7
651aa11
81ee44e
8f7bd55
4f724cf
0aa0938
d8bb367
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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 }} |
| 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" | ||
| ] | ||
| } |
| 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). | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 |
||
|
|
||
| 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(); | ||
| ``` | ||
There was a problem hiding this comment.
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.