Swift SDK Feature Flag docs use "customProperties" (camelCase) but server requires "custom_properties" (snake_case) — silent failure, flag returns fallback

[marcoboerner]

Summary

The Swift Feature Flag docs instruct iOS developers to nest runtime targeting properties under a key named customProperties (camelCase). The Mixpanel /flags/ server endpoint does not recognize this key — it only unwraps custom_properties (snake_case, as documented for the JS / Java / Python / Android / Node SDKs).

The result is a silent failure: every flag that uses a runtime_evaluation_rule is omitted from the API response, the SDK returns the configured fallback value, and there is no warning or error anywhere in the SDK or server logs.

Repro

Project token below is illustrative — substitute your own when verifying.

A flag with rollout rule platform == "ios" and split 100% to treatment_b:

TOKEN="<your_token>"
AUTH=$(printf '%s:' "$TOKEN" | base64)

# ❌ following the Swift docs — flag silently omitted, SDK returns fallback
curl -G "https://api-eu.mixpanel.com/flags/" \
  --data-urlencode 'context={"distinct_id":"u1","customProperties":{"platform":"ios"}}' \
  --data-urlencode "token=$TOKEN" \
  -H "Authorization: Basic $AUTH"

# ✅ snake_case (what the JS docs say) — flag returned with treatment_b
curl -G "https://api-eu.mixpanel.com/flags/" \
  --data-urlencode 'context={"distinct_id":"u1","custom_properties":{"platform":"ios"}}' \
  --data-urlencode "token=$TOKEN" \
  -H "Authorization: Basic $AUTH"

In iOS app code, the broken pattern is:

// ❌ broken — straight from the official Swift docs
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X",
        "customProperties": ["platform": "ios"]
    ])
)

// ✅ working — what the server actually accepts
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X",
        "custom_properties": ["platform": "ios"]
    ])
)

Expected fix

Update docs/tracking-methods/sdks/swift/swift-flags.md to use custom_properties (snake_case) in both the MixpanelOptions(...) initializer example and the setContext(...) example. The page currently has at least two occurrences that need updating.

The JS docs page already shows the correct form — the Swift page is the inconsistent one.

Severity

High for anyone using Mixpanel feature flags on iOS with runtime targeting. The failure mode is silent — the SDK returns the configured fallback with no warning.

Environment

• iOS SDK: mixpanel-swift 6.4.0
• Server: https://api-eu.mixpanel.com/flags/ (EU project — likely same on US)
• Project tested: dev/staging, serving_method: client

[jerrylin3321]

Fixed in #2698