Nextjs

Next.js is a React framework for building modern web applications with features such as server-side rendering (SSR), static site generation (SSG), and hybrid rendering. This guide explains how to integrate the SDK Loader into Next.js applications.

Since the SDK Loader uses browser APIs (DOM manipulation, dynamic script loading), it must run only on the client side. Next.js offers several ways to do this depending on your routing approach.

Environment setup

Create a file .env in the root of your project:

NEXT_PUBLIC_API_KEY=YOUR_API_KEY

Variables with the prefix NEXT_PUBLIC_ are exposed to the browser.

App Router (Next.js 16+)

For the App Router, use the directive 'use client' to make sure the component runs on the client.

Example: app/sdk/page.tsx

app/sdk/page.tsx

'use client';

import { useEffect } from 'react';
import { loadSdk } from '@facephi/sdk-loader';

export default function SdkPage() {
  useEffect(() => {
    const initializeSdk = async () => {
      const apiKey = process.env.NEXT_PUBLIC_API_KEY || '';

      const sdkElement = await loadSdk({
        apiKey,
        containerId: 'sdk-container',
      });

      if (sdkElement) {
        sdkElement.addEventListener('emitIDVIntegration', (event) => {
          console.log('emitIDVIntegration:', event);
        });
      }
    };

    initializeSdk();
  }, []);

  return (
    <main>
      <section>
        <div id="sdk-container" />
      </section>
    </main>
  );
}

The directive 'use client' is necessary because the SDK Loader uses browser APIs.

Pages Router (Next.js 16+)

For the Pages Router, use next/dynamic with ssr: false to disable server-side rendering for the SDK component.

Example: pages/sdk.tsx

pages/sdk.tsx

import { useEffect } from 'react';
import dynamic from 'next/dynamic';

function SdkComponent() {
  useEffect(() => {
    const initializeSdk = async () => {
      const { loadSdk } = await import('@facephi/sdk-loader');
      const apiKey = process.env.NEXT_PUBLIC_API_KEY || '';

      const sdkElement = await loadSdk({
        apiKey,
        containerId: 'sdk-container',
      });

      if (sdkElement) {
        sdkElement.addEventListener('emitIDVIntegration', (event) => {
          console.log('emitIDVIntegration:', event);
        });
      }
    };

    initializeSdk();
  }, []);

  return (
    <main>
      <section>
        <div id="sdk-container" />
      </section>
    </main>
  );
}

// Desactivar SSR para este componente
export default dynamic(() => Promise.resolve(SdkComponent), {
  ssr: false,
});

Using dynamic with ssr: false guarantees that the SDK Loader only runs on the client.

Styles

Add styles in your global CSS or in CSS modules:

styles/globals.css

/* styles/globals.css */
#sdk-container {
  min-height: 400px;
  width: 100%;
}

For advanced styling options, consult the SDK Provider customization documentation.

Known issues

Hydration error (hydration mismatch)

1

Make sure to initialize only on the client

The SDK is only initialized on the client.

2

Verify that the container exists

The container element exists before calling loadSdk().

3

Use the appropriate Next.js tools

Use the directive 'use client' (App Router) or dynamic with ssr: false (Pages Router).

Module not found

1

Check .npmrc

The file .npmrc is configured correctly.

2

Verify installation

The package @facephi/sdk-loader is installed.

3

Use dynamic import

Use dynamic import in the Pages Router approach.

Next steps

• SDK Configuration: Learn about all available configuration options

• SDK Web Components: Explore the available widgets and their properties