Surveys SDK Feature Audit Skill

Use this skill when auditing survey feature support across PostHog SDKs for

surveyVersionRequirements.ts

Feature to audit: $ARGUMENTS

Setup Check (Run First)

Before starting, verify the SDK paths are accessible. Run

ls

on each path:

```
$POSTHOG_JS_PATH
```
```
$POSTHOG_IOS_PATH
```
```
$POSTHOG_ANDROID_PATH
```
```
$POSTHOG_FLUTTER_PATH
```

If any path is empty or doesn't exist, ask the user: "I need the path to [SDK repo] on your machine. Where is it located?"

Once you have all paths, ask the user if they'd like to save them for future sessions by adding to

.claude/settings.local.json

json

{
  "env": {
    "POSTHOG_JS_PATH": "/path/to/posthog-js",
    "POSTHOG_IOS_PATH": "/path/to/posthog-ios",
    "POSTHOG_ANDROID_PATH": "/path/to/posthog-android",
    "POSTHOG_FLUTTER_PATH": "/path/to/posthog-flutter"
  },
  "permissions": {
    "allow": [
      "Read(/path/to/posthog-js/**)",
      "Read(/path/to/posthog-ios/**)",
      "Read(/path/to/posthog-android/**)",
      "Read(/path/to/posthog-flutter/**)",
      "Grep(/path/to/posthog-js/**)",
      "Grep(/path/to/posthog-ios/**)",
      "Grep(/path/to/posthog-android/**)",
      "Grep(/path/to/posthog-flutter/**)"
    ]
  }
}

Note: The

Read

and

Grep

permissions grant Claude access to these external SDK repositories without prompting each time.

Using SDK Paths in Commands

IMPORTANT: Environment variables like

$POSTHOG_JS_PATH

do NOT expand reliably in Bash tool commands.

Instead of bash commands, prefer:

Use the Read tool to read files (works with permissions)
Use the Grep tool to search files (works with permissions)

If you must use bash, first expand the variable:

bash

echo $POSTHOG_JS_PATH

Then use the echoed path directly in subsequent commands.

Tracking Issue

All survey SDK feature parity work is tracked in: https://github.com/PostHog/posthog/issues/45658

When creating new issues for missing features:

Create the issue in the appropriate SDK repo (see labels below)
Add the issue to the tracking issue's "Tracked Issues" section as a task list item:
markdown
```
- [ ] https://github.com/PostHog/repo/issues/123
```
Note: GitHub automatically expands issue links to show titles, so no description is needed.
Update the relevant feature table in the tracking issue if needed

To update the tracking issue body:

Step 1: Fetch the current body to a temp file:

bash

gh api repos/PostHog/posthog/issues/45658 --jq '.body' > /tmp/tracking_issue_body.md

Step 2: Use the Edit tool to modify

/tmp/tracking_issue_body.md

. This ensures the user can review the diff of your changes before proceeding.

Step 3: After the user has approved the edits, push the update:

bash

gh api repos/PostHog/posthog/issues/45658 -X PATCH -f body="$(cat /tmp/tracking_issue_body.md)"

Important: Always use the Edit tool on the temp file rather than writing directly. This gives the user visibility into exactly what changes are being made to the tracking issue.

SDK Paths and Changelogs

SDK	Code Path	Changelog
posthog-js (browser)	`$POSTHOG_JS_PATH/packages/browser`	`$POSTHOG_JS_PATH/packages/browser/CHANGELOG.md`
posthog-react-native	`$POSTHOG_JS_PATH/packages/react-native`	`$POSTHOG_JS_PATH/packages/react-native/CHANGELOG.md`
posthog-ios	`$POSTHOG_IOS_PATH`	`$POSTHOG_IOS_PATH/CHANGELOG.md`
posthog-android	`$POSTHOG_ANDROID_PATH`	`$POSTHOG_ANDROID_PATH/CHANGELOG.md`
posthog-flutter	`$POSTHOG_FLUTTER_PATH`	`$POSTHOG_FLUTTER_PATH/CHANGELOG.md`

Flutter Native Dependencies

Flutter wraps native SDKs. Check dependency versions in:

iOS:

$POSTHOG_FLUTTER_PATH/ios/posthog_flutter.podspec

(look for

s.dependency 'PostHog'

)

Android:

$POSTHOG_FLUTTER_PATH/android/build.gradle

(look for

posthog-android

dependency)

Audit Process

Step 1: Understand the Feature

Look at the

check

function in

surveyVersionRequirements.ts

to understand what field/condition triggers this feature:

```
s.conditions?.deviceTypes
```
→ search for "deviceTypes"
```
s.appearance?.fontFamily
```
→ search for "fontFamily"
```
s.conditions?.urlMatchType
```
→ search for "urlMatchType"

Step 2: Search Changelogs First

bash

# Search changelog for the feature keyword
grep -n -i "KEYWORD" /path/to/CHANGELOG.md

If found, read the surrounding lines to get the version number.

Step 3: Search Code If Not in Changelog

bash

# Find commits that added the keyword (use -S for exact string match)
cd /path/to/sdk && git log --oneline --all -S "KEYWORD" -- "*.swift" "*.kt" "*.ts" "*.tsx"

# Then find the first version tag containing that commit
git tag --contains COMMIT_HASH | sort -V | head -3

Step 4: For Flutter, Find When Native Dependency Was Bumped

bash

# Find when Flutter started requiring iOS version X.Y.Z
cd $POSTHOG_FLUTTER_PATH && git log --oneline -p -- "ios/posthog_flutter.podspec" | grep -B10 "X.Y.Z"

# Get the Flutter version for that commit
git tag --contains COMMIT_HASH | sort -V | head -1

Step 5: Verify Feature Actually Works (Not Just Types)

CRITICAL: Having a field in a data model does NOT mean the feature is implemented. You must check the actual filtering/matching logic.

SDK rendering capabilities:

posthog-js (browser): Built-in survey rendering (HTML/CSS popup)
posthog-react-native: Built-in survey rendering (React Native components in
```
packages/react-native/src/surveys/
```
)

posthog-ios: Built-in survey rendering (SwiftUI views in

PostHog/Surveys/

—

SurveySheet.swift

QuestionTypes.swift

MultipleChoiceOptions.swift

)

posthog-android: No built-in UI — pure delegate pattern. Exposes display models (
```
PostHogDisplaySurvey
```
,
```
PostHogDisplayChoiceQuestion
```
, etc.) for developers to render themselves. Use
```
issue: false
```
for rendering-only features.

posthog-flutter: Built-in survey rendering (Flutter widgets in

lib/src/surveys/widgets/

—

survey_bottom_sheet.dart

choice_question.dart

)

For SDKs with built-in rendering, a feature must be actually implemented in the rendering code, not just present as a field on the data model. For Android (delegate-only), exposing the field on the display model is sufficient — mark as

issue: false

with a comment.

Key files to check for survey filtering logic:

posthog-js (browser):

$POSTHOG_JS_PATH/packages/browser/src/extensions/surveys/surveys-extension-utils.tsx

- utility functions like

canActivateRepeatedly

getSurveySeen

hasEvents

posthog-js (browser):

$POSTHOG_JS_PATH/packages/browser/src/extensions/surveys.tsx

- main survey logic

posthog-react-native:

$POSTHOG_JS_PATH/packages/react-native/src/surveys/getActiveMatchingSurveys.ts

- main filtering logic

posthog-react-native:

$POSTHOG_JS_PATH/packages/react-native/src/surveys/surveys-utils.ts

- utility functions like

canActivateRepeatedly

hasEvents

posthog-ios:

$POSTHOG_IOS_PATH/PostHog/Surveys/PostHogSurveyIntegration.swift

→

getActiveMatchingSurveys()

method,

canActivateRepeatedly

computed property

posthog-android:

$POSTHOG_ANDROID_PATH/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt

→

getActiveMatchingSurveys()

method,

canActivateRepeatedly()

function

Key utility functions to compare across SDKs:

```
canActivateRepeatedly
```
- determines if a survey can be shown again after being seen
```
hasEvents
```
- checks if survey has event-based triggers
```
getSurveySeen
```
- checks if user has already seen the survey

Example pitfall 1: Both iOS and Android have

linkedFlagKey

in their Survey model, but neither implements

linkedFlagVariant

checking. They only call

isFeatureEnabled(key)

(boolean) instead of comparing

flags[key] === variant

Example pitfall 2: The browser

canActivateRepeatedly

checks THREE conditions: (1) event repeatedActivation, (2)

schedule === 'always'

, (3) survey in progress. Mobile SDKs may only check condition (1), missing the

schedule

check entirely.

Key files to check for survey rendering logic:

posthog-js (browser):

$POSTHOG_JS_PATH/packages/browser/src/extensions/surveys/surveys-extension-utils.tsx

getDisplayOrderQuestions()

getDisplayOrderChoices()

posthog-react-native:

$POSTHOG_JS_PATH/packages/react-native/src/surveys/surveys-utils.ts

getDisplayOrderQuestions()

getDisplayOrderChoices()

posthog-ios:

$POSTHOG_IOS_PATH/PostHog/Surveys/QuestionTypes.swift

SingleChoiceQuestionView

MultipleChoiceQuestionView

;

$POSTHOG_IOS_PATH/PostHog/Surveys/SurveySheet.swift

- question ordering

posthog-android: No built-in UI — only check display model exposure in

$POSTHOG_ANDROID_PATH/posthog/src/main/java/com/posthog/surveys/PostHogDisplaySurveyQuestion.kt

and

PostHogDisplaySurveyAppearance.kt

posthog-flutter:

$POSTHOG_FLUTTER_PATH/lib/src/surveys/widgets/survey_bottom_sheet.dart

- question ordering;

$POSTHOG_FLUTTER_PATH/lib/src/surveys/widgets/choice_question.dart

- choice rendering

What to look for:

Is the field parsed from JSON into the model? (necessary but not sufficient)
Is the field used in filtering logic like
```
getActiveMatchingSurveys()
```
?
For rendering features: Is the field actually used by the built-in UI? (check rendering code, not just data models)
Does the logic match the reference implementation behavior?
Test files don't count as implementation

Reference Implementation

posthog-js browser is the canonical implementation - it has every feature and is the source of truth for how things are supposed to work.

When auditing a feature:

First check

$POSTHOG_JS_PATH/packages/browser/src/extensions/surveys.ts

to understand the complete, correct behavior

Then compare mobile SDKs against posthog-react-native (
```
$POSTHOG_JS_PATH/packages/react-native/src/surveys/getActiveMatchingSurveys.ts
```
) which is the reference for mobile-specific implementations

Web-Only vs Cross-Platform Features

Some features only make sense on web:

URL targeting: No concept of "current URL" in native apps →
```
issue: false
```
for all mobile
CSS selector targeting: No DOM in native apps →
```
issue: false
```
for all mobile
Custom fonts via CSS: May need native implementation or may not be applicable

Output Format

For each feature, produce:

typescript

{
    feature: 'Feature Name',
    sdkVersions: {
        'posthog-js': 'X.Y.Z',
        'posthog-react-native': 'X.Y.Z',  // or omit if unsupported
        'posthog-ios': 'X.Y.Z',
        'posthog-android': 'X.Y.Z',
        'posthog_flutter': 'X.Y.Z',  // add comment: first version to require native SDK >= X.Y
    },
    unsupportedSdks: [
        { sdk: 'sdk-name', issue: 'https://github.com/PostHog/repo/issues/123' },  // needs implementation
        { sdk: 'sdk-name', issue: false },  // not applicable (e.g., web-only feature)
    ],
    check: (s) => ...,
}

Creating GitHub Issues

IMPORTANT: Always search for existing issues BEFORE creating new ones.

bash

# Search in the SDK-specific repo
gh issue list --repo PostHog/posthog-ios --search "FEATURE_KEYWORD" --state all --limit 20
gh issue list --repo PostHog/posthog-android --search "FEATURE_KEYWORD" --state all --limit 20
gh issue list --repo PostHog/posthog-flutter --search "FEATURE_KEYWORD" --state all --limit 20

# Also search with broader terms
gh issue list --repo PostHog/posthog-ios --search "survey feature flag" --state all --limit 20

Always search issues in the main repo

PostHog/posthog

AND the SDK-specific repo(s) to ensure an issue does not already exist anywhere.

Labels by Repository

Repository	Labels for Survey Features
PostHog/posthog-js	`feature/surveys`
PostHog/posthog-ios	`Survey` , `enhancement`
PostHog/posthog-android	`Survey` , `enhancement`
PostHog/posthog-flutter	`Survey` , `enhancement`

Issue Creation Command

bash

# posthog-js (covers browser and react-native)
gh issue create --repo PostHog/posthog-js --label "feature/surveys" --title "..." --body "..."

# posthog-ios
gh issue create --repo PostHog/posthog-ios --label "Survey" --label "enhancement" --title "..." --body "..."

# posthog-android
gh issue create --repo PostHog/posthog-android --label "Survey" --label "enhancement" --title "..." --body "..."

# posthog-flutter
gh issue create --repo PostHog/posthog-flutter --label "Survey" --label "enhancement" --title "..." --body "..."

Issue Template

markdown

## 🚨 IMPORTANT

This issue is likely user-facing in the main PostHog app, see [`surveyVersionRequirements.ts`](https://github.com/PostHog/posthog/blob/master/frontend/src/scenes/surveys/surveyVersionRequirements.ts). If you delete or close this issue, be sure to update the version requirements list here.

## Summary

The [SDK] SDK does not support [feature] for surveys.

## Current State

- [What exists, if anything - types, partial implementation, etc.]

## Expected Behavior

[What should happen when this feature is configured]

## Reference Implementation

See posthog-js browser: `packages/browser/src/extensions/surveys.ts`
For mobile-specific patterns, see posthog-react-native: `packages/react-native/src/surveys/getActiveMatchingSurveys.ts`

## Tracking

This is tracked in the survey SDK feature parity issue: https://github.com/PostHog/posthog/issues/45658

_This issue was generated by Claude using the `/survey-sdk-audit` skill._

Completion Checklist

Before finishing the audit, verify all steps are complete:

Understand the feature - Read the check function in
```
surveyVersionRequirements.ts
```
Check browser SDK - Find version in changelog (this is the reference implementation)
Check react-native SDK - Find version in changelog
Check iOS SDK - Verify if feature is actually implemented (not just types)
Check Android SDK - Verify if feature is actually implemented (not just types)
Check Flutter SDK - Check native dependency versions
Search for existing issues - Before creating new ones
Create GitHub issues - For any unsupported SDKs (with proper labels)
Update surveyVersionRequirements.ts - Fix versions and add issue links to unsupportedSdks

Regenerate SDK parity docs - Run

pnpm --filter=@posthog/frontend build:survey-sdk-docs

to update

docs/published/docs/surveys/sdk-feature-support.mdx

Update tracking issue - Add new issues to https://github.com/PostHog/posthog/issues/45658

Common Pitfalls

Don't guess versions - always verify with changelog or git history
Types ≠ Implementation - having a field in a data class doesn't mean filtering logic exists
Model field ≠ Feature support - the field may be parsed but never used in decision-making (e.g.,
```
linkedFlagKey
```
exists but
```
linkedFlagVariant
```
check is missing)
Test code ≠ Production code - functions only in test files aren't shipped
Flutter inherits from native - its "support" depends on iOS/Android SDK versions it requires
Always search for existing issues first - before creating new GitHub issues
Compare utility function implementations - functions like
```
canActivateRepeatedly
```
may have different logic across SDKs; browser is the source of truth
Built-in UI ≠ delegate - iOS, React Native, and Flutter have built-in survey rendering; Android is delegate-only (no built-in UI). A field on the display model is sufficient for Android (
```
issue: false
```
) but for SDKs with built-in rendering, the rendering code must actually use the field
Check rendering code, not just models - e.g., iOS exposes
```
shuffleOptions
```
on
```
PostHogDisplayChoiceQuestion
```
but the SwiftUI
```
QuestionTypes.swift
```
completely ignores it when rendering choices

Post-Audit: Skill Improvement

After completing an audit, consider whether any learnings should be added to this skill file:

New pitfalls discovered - Add to Common Pitfalls section
New key files identified - Add to the file paths in Step 5
New utility functions to compare - Add to the "Key utility functions" list
Pattern changes - If SDK implementations have changed structure, update paths

If you find improvements, propose them to the user:

plaintext

I found some learnings during this audit that could improve the skill:
- [describe the improvement]

Would you like me to update the skill file?

survey-sdk-audit

NPX Install

Tags

SKILL.md Content

Surveys SDK Feature Audit Skill

Setup Check (Run First)

Using SDK Paths in Commands

Tracking Issue

SDK Paths and Changelogs

Flutter Native Dependencies

Audit Process

Step 1: Understand the Feature

Step 2: Search Changelogs First

Step 3: Search Code If Not in Changelog

Step 4: For Flutter, Find When Native Dependency Was Bumped

Step 5: Verify Feature Actually Works (Not Just Types)

Reference Implementation

Web-Only vs Cross-Platform Features

Output Format

Creating GitHub Issues

Labels by Repository

Issue Creation Command

Issue Template

Completion Checklist

Common Pitfalls

Post-Audit: Skill Improvement