Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide walks through integrating the Encore Web SDK in a Next.js application, including handling Server Components and App Router patterns.

​
Installation

npm install @encorekit/web-sdk

​
Why Next.js is Different

Next.js uses Server Components by default in the App Router, which cannot run client-side code like SDK initialization. The SDK ships a built-in EncoreProvider component that handles this for you.

​
Complete Setup Example

​
Step 1: Wrap Your App with EncoreProvider

app/layout.tsx
'use client';

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

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

​
Step 2: Use Encore in Page Components

app/page.tsx
'use client';

import { useState } from 'react';
import { useEncore } from '@encorekit/web-sdk/react';

export default function PricingPage() {
  const encore = useEncore();
  const [loading, setLoading] = useState(false);

  const handleUnlock = async () => {
    setLoading(true);
    try {
      const result = await encore.placement().show();

      if (result.granted) {
        console.log('Offer granted:', result.entitlement);
        // Handle user completed Encore offer
      } else {
        console.log('Offer declined:', result.reason);
      }
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <h1>Premium Feature</h1>
      <button onClick={handleUnlock} disabled={loading}>
        {loading ? 'Loading...' : 'Unlock with Offer'}
      </button>
    </div>
  );
}

​
Environment Variables

Create a .env.local file: 
NEXT_PUBLIC_ENCORE_API_KEY=your-api-key-here
Next.js requires the NEXT_PUBLIC_ prefix for environment variables that need to be accessible in client components.

​
Server-Side API Route for Validation

app/api/offer-granted/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { userId, entitlement } = await request.json();
  
  try {
    // Validate with Encore backend
    const response = await fetch('https://api.encorekit.com/encore/publisher/sdk/v1/entitlements/validate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ENCORE_SECRET_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ userId, entitlement })
    });
    
    const data = await response.json();
    
    if (data.isActive) {
      // Grant access in your database
      // await grantPremiumAccess(userId);
      
      return NextResponse.json({ success: true });
    }
    
    return NextResponse.json({ success: false }, { status: 403 });
  } catch (error) {
    console.error('Validation error:', error);
    return NextResponse.json({ error: 'Validation failed' }, { status: 500 });
  }
}
Store ENCORE_SECRET_KEY in .env.local (without the NEXT_PUBLIC_ prefix) so it’s only available on the server.

​
Next.js Patterns

​
Pages Router (Legacy)

If you’re using the Pages Router instead of App Router:
pages/_app.tsx
import type { AppProps } from 'next/app';
import { EncoreProvider } from '@encorekit/web-sdk/react';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <EncoreProvider apiKey={process.env.NEXT_PUBLIC_ENCORE_API_KEY!}>
      <Component {...pageProps} />
    </EncoreProvider>
  );
}

​
Working Example

Complete working example: See the Next.js demo app for a full implementation with pricing page and offer presentation.

​
Next Steps