Skip to main content
As soon as your application loads, you need to configure the SDK with your API Key and a User ID. You’ll receive your public API key from the Encore Dashboard.

​
Initialize Encore in Your App

The SDK must be configured before calling any other methods. Call configure() as early as possible in your application lifecycle with both your API key and a user ID.
Call configure() before using any other SDK methods. The SDK will only initialize once - subsequent calls will be ignored with a warning.

​
User ID Requirement

You must provide a userId when configuring the SDK. This ID should:
  • Be unique per user
  • Persist across sessions (use localStorage or your auth system)
  • Be set before the user authenticates (use anonymous ID if needed)
Generate an anonymous user ID and store it in localStorage on first visit. Later, you can associate it with the actual user via Encore.identify() after login.

​
Framework-Specific Examples

Choose your framework below to see the complete setup:
  • React
  • Vue
  • Angular
  • Next.js
  • Svelte
  • Vanilla JS
App.tsx
import { useEffect } from 'react';
import Encore from '@encorekit/web-sdk';

function App() {
  useEffect(() => {
    // Generate or retrieve userId from localStorage
    const storageKey = 'encore_user_id';
    let storedUserId = localStorage.getItem(storageKey);
    
    if (!storedUserId) {
      storedUserId = 'user_' + Math.random().toString(36).substring(2, 15);
      localStorage.setItem(storageKey, storedUserId);
    }
    
    Encore.configure({
      apiKey: process.env.REACT_APP_ENCORE_API_KEY,
      userId: storedUserId,
      environment: 'production',
      logLevel: 'debug',
    });
  }, []);

  return <div>Your App</div>;
}
Environment Variable: Create a .env file:
REACT_APP_ENCORE_API_KEY=your-api-key-here

​
Configuration Options

​
apiKey
string
required
Your public API key from the Encore Dashboard. Get yours at dashboard.encorekit.com.
​
userId
string
required
Unique identifier for the user. Should persist across sessions. Use an anonymous ID before authentication, then associate with real user via identify().
​
environment
'production' | 'development'
default:"production"
Runtime environment. Use 'development' for local testing with additional logging.
​
logLevel
'none' | 'debug'
default:"none"
Controls SDK logging verbosity. Use 'debug' during development to see detailed logs.

​
User ID Best Practices

​
Generate Anonymous IDs

Generate a persistent anonymous ID for users before they log in: 
function getOrCreateUserId() {
  const storageKey = 'encore_user_id';
  let userId = localStorage.getItem(storageKey);
  
  if (!userId) {
    // Generate random ID
    userId = 'user_' + Math.random().toString(36).substring(2, 15);
    localStorage.setItem(storageKey, userId);
  }
  
  return userId;
}

const userId = getOrCreateUserId();
Encore.configure({ apiKey: 'your-key', userId });
After user login, associate the anonymous ID with their real account: 
// After user logs in
Encore.identify('authenticated-user-id', {
  email: 'user@example.com',
  subscriptionTier: 'free'
});
The userId in configure() can be different from the ID in identify(). Use configure for tracking, use identify for personalization.

​
Security Considerations

  • Never use sensitive data (email, SSN, etc.) as the userId
  • Use opaque identifiers that don’t reveal user information
  • Store userId securely in localStorage or your session management system
  • Consider GDPR/privacy requirements when generating user IDs

​
Verify Configuration

After configuring, verify the SDK is initialized: 
// Check SDK version
console.log('Encore SDK version:', Encore.getVersion());

// Check current user ID
console.log('Current user ID:', Encore.getCurrentUserId());
Expected output: 
Encore SDK version: 0.1.1
Current user ID: user_abc123xyz

​
Next Steps

Now that the SDK is configured, continue with: For complete working examples, visit our Examples repository.

​
Troubleshooting

Problem: SDK throws error about missing userId parameter.Solution: Add the userId parameter to your configuration:
Encore.configure({
  apiKey: 'your-key',
  userId: 'user-123'
});
Problem: In vanilla JS, getting “Encore.configure is not a function”.Solution: Use the UMD export pattern:
const EncoreSDK = Encore.default || Encore;
EncoreSDK.configure({ ... });
Problem: Users are getting a new ID on each visit.Solution: Ensure you’re persisting the userId in localStorage:
const storageKey = 'encore_user_id';
let userId = localStorage.getItem(storageKey);

if (!userId) {
  userId = 'user_' + Math.random().toString(36).substring(2, 15);
  localStorage.setItem(storageKey, userId); // Persist it
}
Problem: API key is undefined at runtime.Solution: Make sure your environment variable has the correct prefix:
  • React: REACT_APP_ prefix
  • Vite (Vue/Svelte): VITE_ prefix
  • Next.js: NEXT_PUBLIC_ prefix
  • Angular: Configure in environment.ts
Restart your dev server after adding environment variables.