configure()

Configures the Encore SDK for use throughout your application. This must be called once, typically before your app renders, before using any other SDK methods.

Call configure() before using any other SDK methods. Only the first call is honored - subsequent calls will be ignored with a warning.

Signature

function configure(config: EncoreConfig): void

Parameters

config

EncoreConfig

required

Configuration object for the SDK

interface EncoreConfig {
  apiKey: string
  userId: string 
  environment?: 'production' | 'development'
  logLevel?: 'none' | 'debug'
  uiConfiguration?: UIConfiguration
}

config.apiKey

string

required

Your public API key from the Encore Dashboard. This key identifies your app and is safe to use in client-side code.

apiKey: 'pk_live_1234567890abcdef'

Get your API key from the Encore Dashboard

config.userId

string

required

Unique identifier for the user. This should persist across sessions and be set before user authentication.

userId: 'user-123'

Best Practices:

Generate an anonymous ID on first visit and store in localStorage
Use opaque identifiers (not email or sensitive data)
Keep consistent across sessions for accurate tracking
Can be different from the ID used in identify()

Example ID Generation:

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

Never use personally identifiable information (email, SSN, etc.) as the userId. Use opaque identifiers only.

config.environment

string

default:"production"

API environment to use. Options: 'production' or 'development'.

production: https://svc.joinyaw.com/product/encore/v1 (default)
development: http://localhost:8080/encore/v1 (for local testing)

environment: 'production'

config.logLevel

string

default:"none"

Debug logging level. Options: 'none' or 'debug'.

none: No debug logs (recommended for production)
debug: Verbose logging for development

logLevel: 'debug'

config.uiConfiguration

UIConfiguration

Customize the text displayed in the offer modal. All fields are optional.

interface UIConfiguration {
  titleText?: string
  subtitleText?: string
  offerDescriptionText?: string
  instructionsTitleText?: string
  lastStepHeaderText?: string
  lastStepDescriptionText?: string
  creditClaimedTitleText?: string
  creditClaimedSubtitleText?: string
  applyCreditsButtonText?: string
}

uiConfiguration: {
  titleText: 'Get Premium Access',
  subtitleText: 'Complete a quick offer to unlock features'
}

Return Value

Type: void The method doesn’t return a value. It configures the SDK for subsequent use.

Examples

Basic Configuration

import Encore from '@encorekit/web-sdk';

// Generate or retrieve userId
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: 'pk_your_api_key_here',
  userId: userId 
});

Full Configuration

import Encore from '@encorekit/web-sdk';

Encore.configure({
  apiKey: 'pk_your_api_key_here',
  userId: 'user-abc123',
  environment: 'production',
  logLevel: 'debug',
  uiConfiguration: {
    titleText: 'Unlock Premium Features',
    subtitleText: 'Complete an offer to get instant access',
    creditClaimedTitleText: 'Success! 🎉',
    creditClaimedSubtitleText: 'Your premium access is now active'
  }
});

With Environment Variables

Vite (Vue/Svelte)
React (CRA)
Angular

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: import.meta.env.VITE_ENCORE_API_KEY,
  userId: userId,
  logLevel: import.meta.env.MODE === 'development' ? 'debug' : 'none'
});

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: process.env.REACT_APP_ENCORE_API_KEY,
  userId: userId,
  logLevel: process.env.NODE_ENV === 'development' ? 'debug' : 'none'
});

// In your service
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: environment.encoreApiKey,
  userId: userId,
  logLevel: environment.production ? 'none' : 'debug'
});

Framework Integration

App.tsx

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

function App() {
  useEffect(() => {
    // Generate or retrieve userId
    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: process.env.REACT_APP_ENCORE_API_KEY,
      userId: userId,
      environment: 'production'
    });
  }, []);

  return <div>Your App</div>;
}

App.vue

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

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

encore.service.ts

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

@Injectable({ providedIn: 'root' })
export class EncoreService {
  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'
    });
    return userId;
  }
}

Next.js App Router Pattern:

components/EncoreProvider.tsx

'use client';

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

export function EncoreProvider({ 
  apiKey,
  children 
}: { 
  apiKey: string;
  children: React.ReactNode;
}) {
  useEffect(() => {
    // Generate or retrieve userId
    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: 'production'
    });
  }, [apiKey]);

  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!}>
          {children}
        </EncoreProvider>
      </body>
    </html>
  );
}

See the complete Next.js example for a full implementation with offer presentation.

App.svelte

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

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

<script src="https://encorekit.com/encore.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', function() {
    // Get SDK instance (UMD export)
    var EncoreSDK = Encore.default || Encore;
    
    // Generate or retrieve userId
    var storageKey = 'encore_user_id';
    var userId = localStorage.getItem(storageKey);
    
    if (!userId) {
      userId = 'user_' + Math.random().toString(36).substring(2, 15);
      localStorage.setItem(storageKey, userId);
    }
    
    EncoreSDK.configure({
      apiKey: 'YOUR_API_KEY_HERE',
      userId: userId,
      environment: 'production'
    });
  });
</script>

UI Customization

Customize all text in the offer modal:

Encore.configure({
  apiKey: 'pk_your_api_key_here',
  userId: 'user-123',
  uiConfiguration: {
    // Header
    titleText: 'Special Offer',
    subtitleText: 'Complete a task to get rewards',
    
    // Offer section
    offerDescriptionText: 'Choose an offer below to get started',
    
    // Instructions
    instructionsTitleText: 'How It Works',
    
    // Last step
    lastStepHeaderText: 'Almost Done',
    lastStepDescriptionText: 'Complete the advertiser\'s requirements',
    
    // Success screen
    creditClaimedTitleText: 'Congratulations!',
    creditClaimedSubtitleText: 'You\'ve unlocked premium access',
    applyCreditsButtonText: 'Get Started'
  }
});

Best Practices

1. Generate Persistent User IDs

Always generate and persist user IDs in localStorage:

function getOrCreateUserId() {
  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;
}

const userId = getOrCreateUserId();
Encore.configure({ apiKey: 'your-key', userId });

2. Configure Early

Call configure() as early as possible in your app lifecycle:

// Good: Configure before app initialization
const userId = getOrCreateUserId();
Encore.configure({ apiKey: 'your-key', userId });
initApp();

// Avoid: Configuring inside components
function MyComponent() {
  Encore.configure({ apiKey: 'your-key', userId: 'user-123' }); // ❌ Too late
}

3. Use Environment Variables

Never hardcode API keys:

// Good
Encore.configure({
  apiKey: process.env.ENCORE_API_KEY,
  userId: getOrCreateUserId()
});

// Avoid
Encore.configure({
  apiKey: 'pk_live_abc123', // ❌ Hardcoded
  userId: 'user-123'
});

4. Enable Debug Logging in Development

Encore.configure({
  apiKey: 'your-key',
  userId: getOrCreateUserId(),
  logLevel: process.env.NODE_ENV === 'development' ? 'debug' : 'none'
});

5. Configure Once

Don’t call configure() multiple times:

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

// Avoid: Multiple calls
Encore.configure({ apiKey: 'your-key', userId: 'user-123' });
Encore.configure({ logLevel: 'debug' }); // ⚠️ Ignored

6. User ID vs Identity

The userId in configure is for tracking. Use identify() for personalization:

// Step 1: Configure with tracking ID
Encore.configure({
  apiKey: 'your-key',
  userId: 'anonymous-user-123'
});

// Step 2: After login, identify with real user data
Encore.identify('authenticated-user-456', {
  email: '[email protected]',
  subscriptionTier: 'premium'
});

identify() - Associate user with attributes after authentication
getCurrentUserId() - Get the current userId
getVersion() - Get SDK version
setLogLevel() - Change log level after initialization

Utility Methods

getCurrentUserId()

Get the user ID that was provided during configuration:

const userId = Encore.getCurrentUserId();
console.log('Current user ID:', userId); // "user-abc123"

getVersion()

Get the current SDK version:

const version = Encore.getVersion();
console.log('SDK version:', version); // "0.1.1"

setLogLevel()

Change the log level after initialization:

// Enable debug logging
Encore.setLogLevel('debug');

// Disable debug logging
Encore.setLogLevel('none');

Troubleshooting

Error: userId is required

Symptom: SDK throws error about missing userId parameterSolution: Add the userId parameter to your configuration:

const userId = getOrCreateUserId(); // Implement this function
Encore.configure({
  apiKey: 'your-key',
  userId: userId 
});

See Migration from v0.1.0 for details.

Configuration warnings

Symptom: Warning about duplicate configuration callsSolution:

configure() should only be called once
Subsequent calls are ignored
First configuration is used
If you need to reconfigure, reload the page

API key errors

Symptom: Unauthorized or API errorsSolutions:

Verify your API key is correct in the Dashboard
Ensure you’re using the public API key (starts with pk_)
Check that your API key hasn’t been revoked
Verify the package name is @encorekit/web-sdk
Contact [email protected] if issues persist

TypeScript errors

Symptom: Type errors in configurationSolution:

Ensure @encorekit/web-sdk is installed
TypeScript types are included automatically
Use proper type imports if needed:

import type { EncoreConfig } from '@encorekit/web-sdk';

const config: EncoreConfig = {
  apiKey: 'pk_your_key',
  userId: 'user-123'
};

Vanilla JS: Encore.configure is not a function

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

const EncoreSDK = Encore.default || Encore;
EncoreSDK.configure({
  apiKey: 'your-key',
  userId: 'user-123'
});

Next Steps

After configuration, continue with:

identify() - Associate users with attributes
presentOffer() - Display targeted offers
Framework Integration - Complete framework examples

For complete working examples, visit our Examples repository.

Getting Started

iOS SDK

Web SDK

Signature

Parameters

Return Value

Examples

Basic Configuration

Full Configuration

With Environment Variables

Framework Integration

UI Customization

Best Practices

1. Generate Persistent User IDs

2. Configure Early

3. Use Environment Variables

4. Enable Debug Logging in Development

5. Configure Once

6. User ID vs Identity

Utility Methods

getCurrentUserId()

getVersion()

setLogLevel()

Troubleshooting

Next Steps

Getting Started

iOS SDK

Web SDK

​Signature

​Parameters

​Return Value

​Examples

​Basic Configuration

​Full Configuration

​With Environment Variables

​Framework Integration

​UI Customization

​Best Practices

​1. Generate Persistent User IDs

​2. Configure Early

​3. Use Environment Variables

​4. Enable Debug Logging in Development

​5. Configure Once

​6. User ID vs Identity

​Related Methods

​Utility Methods

​getCurrentUserId()

​getVersion()

​setLogLevel()

​Troubleshooting

​Next Steps

Signature

Parameters

Return Value

Examples

Basic Configuration

Full Configuration

With Environment Variables

Framework Integration

UI Customization

Best Practices

1. Generate Persistent User IDs

2. Configure Early

3. Use Environment Variables

4. Enable Debug Logging in Development

5. Configure Once

6. User ID vs Identity

Related Methods

Utility Methods

getCurrentUserId()

getVersion()

setLogLevel()

Troubleshooting

Next Steps