survey-sdk-audit

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.

Issue Visibility

Survey SDK feature parity has no central tracking issue. Visibility lives at repo level: surveyVersionRequirements.ts links unsupported SDKs to their issues, and each new issue cross-links its siblings via a ## Related section (see the issue template below).

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
        'po

---

*Content truncated.*