survey-sdk-audit（survey SDK 审核）

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:

{
  "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:

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:

1. Create the issue in the appropriate SDK repo (see labels below)
2. Add the issue to the tracking issue's "Tracked Issues" section as a task list item: - [] https://github.com/PostHog/repo/issues/123 Note: GitHub automatically expands issue links to show titles, so no description is needed.
3. 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:

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:

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

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

# 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

# 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

# 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:

1. First check $POSTHOG_JS_PATH/packages/browser/src/extensions/surveys.ts to understand the complete, correct behavior
2. 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:

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

# 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

Issue Creation Command

# 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

## 🚨 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

1. Don't guess versions - always verify with changelog or git history
2. Types ≠ Implementation - having a field in a data class doesn't mean filtering logic exists
3. Model field ≠ Feature support - the field may be parsed but never used in decision-making (e.g., linkedFlagKey exists but linkedFlagVariant check is missing)
4. Test code ≠ Production code - functions only in test files aren't shipped
5. Flutter inherits from native - its "support" depends on iOS/Android SDK versions it requires
6. Always search for existing issues first - before creating new GitHub issues
7. Compare utility function implementations - functions like canActivateRepeatedly may have different logic across SDKs; browser is the source of truth
8. 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
9. 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:

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

If you find improvements, propose them to the user:

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

Would you like me to update the skill file?