Configure the SDK

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:

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

App.vue

<script setup lang="ts">
import { onMounted } from 'vue';
import Encore from '@encorekit/web-sdk';

onMounted(() => {
  // 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: import.meta.env.VITE_ENCORE_API_KEY,
    userId: storedUserId,
    environment: 'production',
    logLevel: 'debug',
  });
});
</script>

Environment Variable: Create a .env file:

VITE_ENCORE_API_KEY=your-api-key-here

encore.service.ts

import { Injectable } from '@angular/core';
import Encore from '@encorekit/web-sdk';

@Injectable({ providedIn: 'root' })
export class EncoreService {
  private isInitialized = false;

  private generateUserId(): string {
    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);
    }
    
    return userId;
  }

  initializeWithAutoUserId(apiKey: string): string {
    const userId = this.generateUserId();
    Encore.configure({
      userId,
      apiKey,
      environment: 'production',
      logLevel: 'debug',
    });
    this.isInitialized = true;
    return userId;
  }
}

app.component.ts

import { Component, OnInit } from '@angular/core';
import { EncoreService } from './encore.service';
import { environment } from '../environments/environment';

@Component({
  selector: 'app-root',
  template: '<div>Your App</div>'
})
export class AppComponent implements OnInit {
  constructor(private encoreService: EncoreService) {}

  ngOnInit() {
    this.encoreService.initializeWithAutoUserId(
      environment.encoreApiKey
    );
  }
}

Environment Configuration:

environment.ts

export const environment = {
  production: true,
  encoreApiKey: 'your-api-key-here'
};

Next.js requires a client component wrapper because the SDK initialization must happen on the client side.

components/EncoreProvider.tsx

'use client';

import { useEffect } from 'react';
import Encore from '@encorekit/web-sdk';

interface EncoreProviderProps {
  apiKey: string;
  environment?: 'production' | 'development';
  logLevel?: 'none' | 'debug';
  children: React.ReactNode;
}

export function EncoreProvider({ 
  apiKey, 
  environment = 'production',
  logLevel = 'none',
  children 
}: EncoreProviderProps) {
  useEffect(() => {
    // Generate or retrieve userId from 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);
    }
    
    Encore.configure({
      apiKey,
      userId,
      environment,
      logLevel,
    });
  }, [apiKey, environment, logLevel]);

  return <>{children}</>;
}

app/layout.tsx

import { EncoreProvider } from '@/components/EncoreProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <EncoreProvider 
          apiKey={process.env.NEXT_PUBLIC_ENCORE_API_KEY!}
          logLevel={process.env.NODE_ENV === 'development' ? 'debug' : 'none'}
        >
          {children}
        </EncoreProvider>
      </body>
    </html>
  );
}

Environment Variable: Create a .env.local file:

NEXT_PUBLIC_ENCORE_API_KEY=your-api-key-here

Next.js requires the NEXT_PUBLIC_ prefix for environment variables accessible in client components.

App.svelte

<script lang="ts">
  import { onMount } from 'svelte';
  import Encore from '@encorekit/web-sdk';

  onMount(() => {
    // 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: import.meta.env.VITE_ENCORE_API_KEY,
      userId: storedUserId,
      environment: 'production',
      logLevel: 'debug',
    });
  });
</script>

<div>Your App</div>

Environment Variable: Create a .env file:

VITE_ENCORE_API_KEY=your-api-key-here

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Your App</title>
  <!-- Load Encore SDK from CDN -->
  <script src="https://encorekit.com/encore.min.js"></script>
</head>
<body>
  <div id="app">Your App</div>

  <script>
    document.addEventListener('DOMContentLoaded', function() {
      // Get SDK instance (UMD export uses .default)
      var EncoreSDK = Encore.default || Encore;
      
      // Generate or retrieve userId from localStorage
      var storageKey = 'encore_user_id';
      var storedUserId = localStorage.getItem(storageKey);
      
      if (!storedUserId) {
        storedUserId = 'user_' + Math.random().toString(36).substring(2, 15);
        localStorage.setItem(storageKey, storedUserId);
      }
      
      EncoreSDK.configure({
        apiKey: 'YOUR_API_KEY_HERE',
        userId: storedUserId,
        environment: 'production',
        logLevel: 'debug'
      });
    });
  </script>
</body>
</html>

For vanilla JavaScript, the SDK is loaded from CDN and accessed via Encore.default || Encore due to UMD module format.

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 });

Link to Authenticated Users

After user login, associate the anonymous ID with their real account:

// After user logs in
Encore.identify('authenticated-user-id', {
  email: '[email protected]',
  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:

Identify Users - Associate users with offers after login
Present Offers - Display targeted offers to users
Track Entitlements - Validate user entitlements server-side

For complete working examples, visit our Examples repository.

Troubleshooting

Error: userId is required

Problem: SDK throws error about missing userId parameter.Solution: Add the userId parameter to your configuration:

Encore.configure({
  apiKey: 'your-key',
  userId: 'user-123'
});

Vanilla JS: Encore.configure is not a function

Problem: In vanilla JS, getting “Encore.configure is not a function”.Solution: Use the UMD export pattern:

const EncoreSDK = Encore.default || Encore;
EncoreSDK.configure({ ... });

User ID changes on every page load

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
}

Environment variables not working

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.

Getting Started

iOS SDK

Web SDK

Initialize Encore in Your App

User ID Requirement

Framework-Specific Examples

Configuration Options

User ID Best Practices

Generate Anonymous IDs

Link to Authenticated Users

Security Considerations

Verify Configuration

Next Steps

Troubleshooting

Getting Started

iOS SDK

Web SDK

​Initialize Encore in Your App

​User ID Requirement

​Framework-Specific Examples

​Configuration Options

​User ID Best Practices

​Generate Anonymous IDs

​Link to Authenticated Users

​Security Considerations

​Verify Configuration

​Next Steps

​Troubleshooting

Initialize Encore in Your App

User ID Requirement

Framework-Specific Examples

Configuration Options

User ID Best Practices

Generate Anonymous IDs

Link to Authenticated Users

Security Considerations

Verify Configuration

Next Steps

Troubleshooting