visitory-sdk/README.md

Feature flags and analytics SDK for Visitory

StatsIG SDK
A TypeScript/JavaScript SDK for feature flags and analytics, with first-class React support.
Installation
bashnpm install @your-org/statsig-sdk

# or

yarn add @your-org/statsig-sdk
Quick Start
Vanilla JavaScript/TypeScript
typescriptimport { initialize, checkFeatureFlag, trackCustomEvent } from '@your-org/statsig-sdk'

// Initialize the SDK
initialize({
apiKey: 'your-api-key',
userAttributes: {
age: 28,
country: 'US',
subscription_tier: 'premium'
}
})

// Check feature flags
const result = await checkFeatureFlag('new-feature')
if (result.enabled) {
console.log('Feature enabled for segments:', result.matchedSegments)
// Show new feature
}

// Track events
trackCustomEvent('button_clicked', {
button: 'sign-up',
page: '/landing'
})
React
tsximport React from 'react'
import { StatsigProvider, useFeatureFlag, FeatureFlag } from '@your-org/statsig-sdk'

// 1. Wrap your app with StatsigProvider
function App() {
return (
<StatsigProvider
config={{
        apiKey: 'your-api-key',
        userAttributes: {
          age: 28,
          country: 'US',
          subscription_tier: 'premium'
        }
      }} >
<Dashboard />
</StatsigProvider>
)
}

// 2. Use feature flags in components
function Dashboard() {
const { enabled, loading } = useFeatureFlag('new-dashboard')

if (loading) return <div>Loading...</div>

return (
<div>
{enabled ? <NewDashboard /> : <OldDashboard />}

      {/* Or use the component */}
      <FeatureFlag flagKey="premium-features" fallback={<UpgradePrompt />}>
        <PremiumFeatures />
      </FeatureFlag>
    </div>

)
}
Core Concepts
User Attributes
Instead of user IDs, this SDK uses user attributes to determine feature flag eligibility based on segments you create in your dashboard.
typescriptconst userAttributes = {
age: 25, // Number
country: 'US', // String
subscription_tier: 'premium', // String
device_type: 'mobile', // String
signup_date: '2024-01-15' // String (dates)
}
Segments
Create segments in your dashboard with criteria like:

age > 25 (users older than 25)
country = "US" (US users)
subscription_tier in "premium,enterprise" (premium users)

Feature Flags
Feature flags are associated with segments. When you check a flag, the SDK evaluates your user attributes against segment criteria.
API Reference
Core Functions
initialize(config: StatsigConfig)
Initialize the SDK with your configuration.
typescriptinterface StatsigConfig {
apiKey: string // Your project API key
baseUrl?: string // Custom API endpoint
userAttributes?: Record<string, any> // Default user attributes
sessionId?: string // Custom session ID
}
checkFeatureFlag(flagKey: string, userAttributes?: Record<string, any>)
Check if a feature flag is enabled.
typescriptconst result = await checkFeatureFlag('new-checkout', {
subscription_tier: 'premium'
})

// Returns:
{
enabled: boolean,
matchedSegments?: string[],
reason?: string
}
trackCustomEvent(eventName: string, properties?: Record<string, any>)
Track a custom event.
typescriptawait trackCustomEvent('purchase_completed', {
amount: 99.99,
currency: 'USD',
item_count: 3
})
React Hooks
useFeatureFlag(flagKey: string, userAttributes?: Record<string, any>)
Hook for checking feature flags with loading states.
tsxconst { enabled, loading, matchedSegments } = useFeatureFlag('new-feature')
useTracking()
Hook for tracking events.
tsximport { useTracking } from '@your-org/statsig-sdk'

const { trackClick, trackPageView, trackCustomEvent } = useTracking()

const handleClick = () => {
trackClick('hero-button', { variant: 'blue' })
}
useUserAttributes()
Hook for managing user attributes.
tsximport { useUserAttributes } from '@your-org/statsig-sdk'

const { updateAttributes, getAttributes } = useUserAttributes()

// Update when user logs in
useEffect(() => {
updateAttributes({
age: user.age,
subscription_tier: user.plan
})
}, [user])
React Components
<FeatureFlag>
Conditional rendering based on feature flags.
tsx<FeatureFlag
flagKey="premium-features"
userAttributes={{ subscription_tier: 'premium' }}
fallback={<UpgradePrompt />}
loading={<Spinner />}

>   <PremiumContent />
> </FeatureFlag>
> withFeatureFlag(flagKey, userAttributes?)(Component)
> Higher-order component for feature flags.
> tsxconst BetaFeature = withFeatureFlag('beta-features')(MyComponent)
> Advanced Usage
> Dynamic User Attributes
> Update user attributes as your app state changes:
> tsximport { useUserAttributes } from '@your-org/statsig-sdk'

function UserProfile({ user }) {
const { updateAttributes } = useUserAttributes()

useEffect(() => {
updateAttributes({
age: user.age,
country: user.country,
subscription_tier: user.plan,
days_since_signup: Math.floor((Date.now() - user.createdAt) / (1000 _ 60 _ 60 \* 24))
})
}, [user])

return <div>...</div>
}
A/B Testing
tsxconst { variant } = useVariant('homepage-test', ['control', 'variant-a', 'variant-b'])

switch (variant) {
case 'variant-a':
return <HeroVariantA />
case 'variant-b':
return <HeroVariantB />
default:
return <HeroControl />
}
Page View Tracking with React Router
tsximport { useLocation } from 'react-router-dom'
import { useTracking } from '@your-org/statsig-sdk'

function PageTracker() {
const location = useLocation()
const { trackPageView } = useTracking()

useEffect(() => {
trackPageView(location.pathname)
}, [location])

return null
}
Error Handling
tsxconst { enabled, loading, error } = useFeatureFlag('risky-feature')

if (error) {
// Flag evaluation failed, use safe default
return <SafeDefault />
}
Environment Setup
Environment Variables
bash# .env
REACT_APP_STATSIG_API_KEY=your_api_key_here
REACT_APP_STATSIG_BASE_URL=https://your-app.vercel.app
TypeScript Support
The SDK is written in TypeScript and includes full type definitions.
typescriptimport type { StatsigConfig, FeatureFlagResult } from '@your-org/statsig-sdk'
Examples
E-commerce
tsxfunction CheckoutButton({ cart }) {
const { enabled: expressCheckout } = useFeatureFlag('express-checkout')
const { trackCustomEvent } = useTracking()

const handleCheckout = () => {
trackCustomEvent('checkout_started', {
cart_value: cart.total,
checkout_type: expressCheckout ? 'express' : 'standard'
})
}

return expressCheckout ? (
<button onClick={handleCheckout} className="express">
Express Checkout
</button>
) : (
<button onClick={handleCheckout}>
Proceed to Checkout
</button>
)
}
User Onboarding
tsxfunction Onboarding({ user }) {
const { enabled: newOnboarding } = useFeatureFlag('new-onboarding-flow', {
signup_date: user.signupDate,
account_type: user.type
})

return newOnboarding ? <NewOnboardingFlow /> : <ClassicOnboarding />
}
Feature Rollout
tsxfunction BetaFeatures() {
const { enabled: betaAccess } = useFeatureFlag('beta-program', {
subscription_tier: 'enterprise',
beta_opt_in: true
})

if (!betaAccess) {
return (
<div>
<h2>Beta Features</h2>
<p>Join our beta program to access cutting-edge features!</p>
<button>Request Beta Access</button>
</div>
)
}

return <BetaProgramDashboard />
}
Building and Publishing
Development
bashnpm run dev # Watch mode
npm run build # Production build
npm run test # Run tests
npm run lint # Lint code
Publishing
bashnpm run build
npm publish
Browser Support

Chrome/Edge 88+
Firefox 85+
Safari 14+
Node.js 16+

License
MIT
Support
For questions and support, please refer to the main platform documentation or create an issue in the repository.