🚀 How to Use Feature Flags in Apps

Installation

npm install @kalkaai/js-sdk
# or
yarn add @kalkaai/js-sdk

Basic Setup

import { KalkaAI } from '@kalkaai/js-sdk';

// Initialize the client
const kalkaai = new KalkaAI({
  apiKey: process.env.NEXT_PUBLIC_KALKAAI_API_KEY,
  environmentId: process.env.NEXT_PUBLIC_KALKAAI_ENVIRONMENT_ID,
  userId: 'user-123', // Optional: for user-specific flags
  attributes: { // Optional: for attribute-based targeting
    plan: 'premium',
    region: 'us-east-1',
    betaUser: true
  }
});

React Hook Usage

import { useFeatureFlag } from '@kalkaai/js-sdk/react';

function MyComponent() {
  const { isEnabled, isLoading, variant } = useFeatureFlag('new-checkout-flow');

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      {isEnabled ? (
        <NewCheckoutFlow variant={variant} />
      ) : (
        <OldCheckoutFlow />
      )}
    </div>
  );
}

Node.js/Express

const { KalkaAI } = require('@kalkaai/node-sdk');

const kalkaai = new KalkaAI({
  apiKey: process.env.KALKAAI_API_KEY,
  environmentId: process.env.KALKAAI_ENVIRONMENT_ID
});

app.get('/api/features', async (req, res) => {
  const userId = req.user.id;
  const userAttributes = {
    plan: req.user.plan,
    region: req.user.region
  };

  const isNewFeatureEnabled = await kalkaai.isEnabled(
    'new-api-endpoint',
    userId,
    userAttributes
  );

  res.json({ newFeatureEnabled: isNewFeatureEnabled });
});

Next.js API Routes

// pages/api/features.js or app/api/features/route.js
import { KalkaAI } from '@kalkaai/js-sdk';

const kalkaai = new KalkaAI({
  apiKey: process.env.KALKAAI_API_KEY,
  environmentId: process.env.KALKAAI_ENVIRONMENT_ID
});

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const userId = searchParams.get('userId');

  const flags = await kalkaai.getAllFlags(userId, {
    plan: 'premium'
  });

  return Response.json({ flags });
}

React Native

npm install @kalkaai/react-native-sdk

import { KalkaAI } from '@kalkaai/react-native-sdk';

const kalkaai = new KalkaAI({
  apiKey: 'your-api-key',
  environmentId: 'your-env-id',
  userId: 'user-123'
});

// In your component
const [featureEnabled, setFeatureEnabled] = useState(false);

useEffect(() => {
  kalkaai.isEnabled('new-feature').then(setFeatureEnabled);
}, []);

iOS (Swift)

import KalkaAISDK

let kalkaai = KalkaAI(
    apiKey: "your-api-key",
    environmentId: "your-env-id",
    userId: "user-123"
)

kalkaai.isEnabled("new-feature") { enabled in
    if enabled {
        // Show new feature
    } else {
        // Show fallback
    }
}

Android (Kotlin)

implementation 'com.kalkaai:android-sdk:1.0.0'

val kalkaai = KalkaAI.Builder()
    .apiKey("your-api-key")
    .environmentId("your-env-id")
    .userId("user-123")
    .build()

kalkaai.isEnabled("new-feature") { enabled ->
    if (enabled) {
        // Show new feature
    } else {
        // Show fallback
    }
}

WebSocket Connection

import { KalkaAI } from '@kalkaai/js-sdk';

const kalkaai = new KalkaAI({
  apiKey: process.env.NEXT_PUBLIC_KALKAAI_API_KEY,
  environmentId: process.env.NEXT_PUBLIC_KALKAAI_ENVIRONMENT_ID,
  realTimeUpdates: true // Enable real-time updates
});

// Listen for flag changes
kalkaai.onFlagUpdate('new-feature', (enabled, variant) => {
  // Update your UI immediately
});

React Hook with Real-Time

import { useFeatureFlag } from '@kalkaai/js-sdk/react';

function MyComponent() {
  const { isEnabled, variant, isLoading } = useFeatureFlag('new-feature', {
    realTime: true // Automatically update when flag changes
  });

  // Component re-renders automatically when flag is updated
  return (
    <div>
      {isEnabled ? <NewFeature variant={variant} /> : <OldFeature />}
    </div>
  );
}

Tracking Flag Usage

// Track when a feature is used
kalkaai.track('feature-used', {
  flagKey: 'new-checkout-flow',
  userId: 'user-123',
  properties: {
    variant: 'blue-button',
    conversionValue: 99.99
  }
});

// Track custom events
kalkaai.track('purchase-completed', {
  userId: 'user-123',
  properties: {
    amount: 149.99,
    featureFlags: kalkaai.getActiveFlags()
  }
});

A/B Testing Metrics

// Automatically track conversion metrics
const { isEnabled, variant, trackConversion } = useFeatureFlag('ab-test-checkout');

const handlePurchase = (amount) => {
  // Track conversion with value
  trackConversion('purchase', { value: amount });

  // Continue with purchase logic
  processPurchase(amount);
};

Environment Variables

# .env.local
NEXT_PUBLIC_KALKAAI_API_KEY=kka_development_your_api_key
NEXT_PUBLIC_KALKAAI_ENVIRONMENT_ID=dev-env-id

# .env.production
NEXT_PUBLIC_KALKAAI_API_KEY=kka_production_your_api_key
NEXT_PUBLIC_KALKAAI_ENVIRONMENT_ID=prod-env-id

# Server-side only (no NEXT_PUBLIC prefix)
KALKAAI_API_KEY=kka_production_server_key
KALKAAI_ENVIRONMENT_ID=prod-env-id

Advanced Configuration

const kalkaai = new KalkaAI({
  apiKey: process.env.NEXT_PUBLIC_KALKAAI_API_KEY,
  environmentId: process.env.NEXT_PUBLIC_KALKAAI_ENVIRONMENT_ID,

  // Optional configurations
  timeout: 5000, // API timeout in milliseconds
  retryAttempts: 3, // Number of retry attempts
  cacheTimeout: 300000, // Cache timeout (5 minutes)
  realTimeUpdates: true, // Enable WebSocket updates

  // Default user attributes
  defaultAttributes: {
    platform: 'web',
    version: '1.0.0'
  },

  // Logging
  logLevel: 'warn', // 'debug', 'info', 'warn', 'error'

  // Fallback values for offline mode
  fallbacks: {
    'new-feature': false,
    'beta-feature': true
  }
});

Flag Naming Conventions

• Use descriptive names: new-checkout-flow instead of flag1
• Use kebab-case: user-profile-redesign
• Include context: mobile-app-dark-mode

Deployment Strategy

Error Handling

// Always provide fallback values
const { isEnabled, isLoading, error } = useFeatureFlag('new-feature', {
  fallback: false // Default value if API fails
});

if (error) {
  // Continue with fallback behavior
}

// Or use try-catch for synchronous calls
try {
  const enabled = await kalkaai.isEnabled('new-feature');
  return enabled;
} catch (error) {
  return false; // Safe fallback
}

Common Issues

Debug Mode

// Enable debug logging
const kalkaai = new KalkaAI({
  apiKey: 'your-api-key',
  environmentId: 'your-env-id',
  logLevel: 'debug' // Shows detailed logs
});

// Check SDK status
console.log('SDK Status:', kalkaai.getStatus());
console.log('Active Flags:', kalkaai.getActiveFlags());
console.log('Connection Status:', kalkaai.isConnected());

Getting Help