┌─────────────────────────────────────────────────────────────┐
│                    Mobile App                               │
├─────────────────────────────────────────────────────────────┤
│  LaunchDarkly SDK                                           │
│       │                                                     │
│       ├── useFeatureFlagEnabled() - Boolean flags           │
│       ├── useFeatureFlagValue() - String/multivariate       │
│       ├── checkFeatureFlag() - Outside React components     │
│       ├── trackEvent() - Custom event tracking              │
│       └── FeatureGate - Declarative feature gating          │
├─────────────────────────────────────────────────────────────┤
│  AI Agent (Cursor)                                          │
│       │                                                     │
│       └── MCP Server - Create/manage flags programmatically │
└─────────────────────────────────────────────────────────────┘

{
  "mcpServers": {
    "launchdarkly": {
      "command": "npx",
      "args": [
        "-y",
        "--package", "@launchdarkly/mcp-server",
        "--", "mcp", "start",
        "--api-key", "api-YOUR-TOKEN-HERE"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/etc/ssl/cert.pem"
      }
    }
  }
}

// Use mcp_launchdarkly_list-feature-flags
{
  "projectKey": "default"
}

# LaunchDarkly Mobile SDK Key (safe for client-side use)
EXPO_PUBLIC_LAUNCHDARKLY_MOBILE_KEY=mob-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

import { FeatureGate } from "@/components/FeatureGate";
import { FEATURE_FLAGS } from "@/hooks/useFeatureFlags";

// In a tab file (e.g., app/(tabs)/habits.tsx)
export default function HabitsTab() {
  return (
    <FeatureGate
      flag={FEATURE_FLAGS.HABITS_ENABLED}
      featureName="Habits"
      icon="checkbox-outline"
    >
      <HabitsScreen />
    </FeatureGate>
  );
}

import { useFeatureFlagEnabled, FEATURE_FLAGS } from "@/hooks/useFeatureFlags";

function VoiceButton() {
  const isVoiceEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.VOICE_JOURNALING_ENABLED);
  
  if (!isVoiceEnabled) {
    return null;
  }
  
  return <Button>Voice Entry</Button>;
}

import { useFeatureFlagValue, FEATURE_FLAGS, JOURNAL_PROMPT_STYLES, trackEvent, LD_EVENTS } from "@/hooks/useFeatureFlags";

function JournalPrompt() {
  // Get the assigned prompt style (LaunchDarkly handles random assignment)
  const promptStyle = useFeatureFlagValue(
    FEATURE_FLAGS.JOURNAL_PROMPT_STYLE,
    JOURNAL_PROMPT_STYLES.TRADITIONAL
  );

  // Track which variant the user saw (for analysis)
  useEffect(() => {
    trackEvent(LD_EVENTS.JOURNAL_STARTED, { prompt_style: promptStyle });
  }, []);

  // Render based on variant
  const prompts = {
    [JOURNAL_PROMPT_STYLES.TRADITIONAL]: "What are you grateful for today?",
    [JOURNAL_PROMPT_STYLES.CONVERSATIONAL]: "Hey! What's been on your heart lately?",
    [JOURNAL_PROMPT_STYLES.SCRIPTURE_LED]: "Reflect on Philippians 4:8 - What is true, noble, and praiseworthy in your life today?",
  };

  return <Text>{prompts[promptStyle]}</Text>;
}

// When user completes journal entry
trackEvent(LD_EVENTS.JOURNAL_COMPLETED, {
  prompt_style: promptStyle,
  word_count: entry.text.length,
  time_to_complete: Date.now() - startTime,
});

import { checkFeatureFlag, FEATURE_FLAGS } from "@/hooks/useFeatureFlags";

async function analyzeEntry(entry: JournalEntry) {
  const useV2 = checkFeatureFlag(FEATURE_FLAGS.AI_SUMMARY_V2);
  
  if (useV2) {
    return analyzeWithV2(entry);
  }
  return analyzeWithV1(entry);
}

import { trackEvent, LD_EVENTS } from "@/hooks/useFeatureFlags";

// Journal events
trackEvent(LD_EVENTS.JOURNAL_STARTED, { entry_type: "guided" });
trackEvent(LD_EVENTS.JOURNAL_COMPLETED, { word_count: 500 });
trackEvent(LD_EVENTS.JOURNAL_ABANDONED);

// Voice events
trackEvent(LD_EVENTS.VOICE_RECORDING_STARTED, { source: "fab_menu" });
trackEvent(LD_EVENTS.VOICE_RECORDING_COMPLETED, { duration: 120 });
trackEvent(LD_EVENTS.LOCAL_TRANSCRIPTION_USED);

// AI events
trackEvent(LD_EVENTS.AI_SUMMARY_GENERATED, { model: "gpt-4" });
trackEvent(LD_EVENTS.AI_GENERATION_TIME, { model: "gpt-4" }, 2500); // metric value

// Conversion events (for experiments)
trackEvent(LD_EVENTS.FIRST_JOURNAL_COMPLETED);
trackEvent(LD_EVENTS.ONBOARDING_COMPLETED);
trackEvent(LD_EVENTS.WEEKLY_ACTIVE);

// ✅ Good - track with context
trackEvent(LD_EVENTS.JOURNAL_COMPLETED, {
  entry_type: "guided",
  word_count: 500,
  has_ai_summary: true,
  prompt_style: promptStyle,
});

// ✅ Good - track timing for experiments
const startTime = Date.now();
const summary = await generateSummary(text);
trackEvent(LD_EVENTS.AI_GENERATION_TIME, { model: "gpt-4" }, Date.now() - startTime);

// ❌ Bad - no context
trackEvent("completed");

// ❌ Bad - string literal (use constants)
trackEvent("journal-completed");

import { identifyUser } from "@/lib/launchdarkly";

// Basic identification
await identifyUser(user.id, {
  email: user.email,
  orgId: user.organization_id,
});

import { identifyUser, LDUserAttributes } from "@/lib/launchdarkly";
import { Platform } from "react-native";
import * as Device from "expo-device";

// Rich identification for advanced targeting
await identifyUser(user.id, {
  // Identity
  email: user.email,
  name: user.full_name,

  // Organization targeting (church-by-church rollouts)
  orgId: user.organization_id,
  orgName: "First Baptist Church",

  // Role targeting (admin-only features)
  role: "admin",
  isPastor: true,

  // Device targeting (platform-specific rollouts)
  platform: Platform.OS,
  appVersion: "1.2.0",
  deviceModel: Device.modelName,

  // Subscription targeting (premium features)
  subscriptionTier: "pro",

  // Beta targeting (early adopters)
  isBetaTester: true,
  betaEnrolledDate: "2025-12-01",
});

import { resetUser } from "@/lib/launchdarkly";

await resetUser();

// Identify user as beta tester
await identifyUser(userId, {
  isBetaTester: user.has_opted_into_beta,
});

// src/hooks/useFeatureFlags.ts
export const FEATURE_FLAGS = {
  // ... existing flags
  MY_NEW_FEATURE: "my-new-feature",
} as const;

// Use mcp_launchdarkly_create-feature-flag
{
  "projectKey": "default",
  "FeatureFlagBody": {
    "key": "my-new-feature",
    "name": "My New Feature",
    "description": "Description of what this flag controls",
    "temporary": false,
    "tags": ["mobile"]
  }
}

// Use mcp_launchdarkly_update-feature-flag
{
  "projectKey": "default",
  "featureFlagKey": "my-new-feature",
  "PatchWithComment": {
    "comment": "Enable for all users",
    "patch": [
      { "op": "replace", "path": "/environments/test/on", "value": true },
      { "op": "replace", "path": "/environments/production/on", "value": true }
    ]
  }
}

// Simple conditional
const isEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.MY_NEW_FEATURE);

// Or use FeatureGate for screens
<FeatureGate flag={FEATURE_FLAGS.MY_NEW_FEATURE} featureName="My Feature">
  <MyFeatureScreen />
</FeatureGate>

// ✅ Good - type-safe
const isEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.VOICE_JOURNALING_ENABLED);

// ❌ Bad - prone to typos
const isEnabled = useFeatureFlagEnabled("voice-journeling-enabled");

// ✅ Good - declarative, shows placeholder
<FeatureGate flag={FEATURE_FLAGS.NEW_TAB} featureName="New Tab">
  <NewTabScreen />
</FeatureGate>

// ⚠️ Okay for small UI elements
{isEnabled && <SmallButton />}

// ✅ Good - track SDK connectivity on init
ldClient.track("sdk-initialized", { source: "cursor" });

// ✅ Good - track feature usage
trackEvent("voice_recording_completed", { duration: 45 });

function FeatureComponent() {
  const { isReady } = useFeatureFlags();
  const isEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.NEW_FEATURE);
  
  if (!isReady) {
    return <LoadingSpinner />;
  }
  
  if (!isEnabled) {
    return null;
  }
  
  return <NewFeature />;
}

// ✅ FeatureGate handles loading state automatically
<FeatureGate flag={FEATURE_FLAGS.MY_FEATURE} featureName="My Feature">
  <MyFeatureScreen />
</FeatureGate>

function MyFeature() {
  const { isReady } = useFeatureFlags();
  const isEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.MY_FEATURE);
  
  // Show loading while SDK initializes
  if (!isReady) {
    return <LoadingSpinner />;
  }
  
  if (!isEnabled) {
    return null;
  }
  
  return <MyFeatureContent />;
}

const { isReady } = useFeatureFlags();
const isEnabled = useFeatureFlagEnabled(FEATURE_FLAGS.MY_BUTTON);

// Only show button after SDK is ready
{isReady && isEnabled && <MyButton />}