Nextjs

Next.js é um framework de React para criar aplicações web modernas com funções como renderização no servidor (SSR), geração de sites estáticos (SSG) e renderização híbrida. Este guia explica como integrar o SDK Loader em aplicações Next.js.

Como o SDK Loader usa APIs do navegador (manipulação do DOM, carregamento dinâmico de scripts), deve ser executado somente no lado do cliente. O Next.js oferece várias formas de fazer isso, dependendo da sua abordagem de roteamento.

Configuração do ambiente

Crie um arquivo .env na raiz do seu projeto:

NEXT_PUBLIC_API_KEY=YOUR_API_KEY

As variáveis com o prefixo NEXT_PUBLIC_ são expostas ao navegador.

App Router (Next.js 16+)

Para o App Router, use a diretiva 'use client' para garantir que o componente seja executado no cliente.

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

A diretiva 'use client' é necessária porque o SDK Loader usa APIs do navegador.

Pages Router (Next.js 16+)

Para o Pages Router, use next/dynamic com ssr: false para desativar a renderização no servidor do componente do SDK.

Exemplo: 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,
});

Usar dynamic com ssr: false garante que o SDK Loader seja executado somente no cliente.

Estilos

Adicione estilos no seu CSS global ou em módulos CSS:

styles/globals.css

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

Para opções de estilo avançadas, consulte a documentação de Personalização do SDK Provider.

Problemas conhecidos

Erro de hidratação (hydration mismatch)

1

Certifique-se de inicializar somente no cliente

O SDK é inicializado somente no cliente.

2

Verifique se o contêiner existe

O elemento contêiner existe antes de chamar loadSdk().

3

Use as ferramentas adequadas do Next.js

Use a diretiva 'use client' (App Router) ou dynamic com ssr: false (Pages Router).

Módulo não encontrado

1

Verifique .npmrc

O arquivo .npmrc esteja configurado corretamente.

2

Verifique a instalação

O pacote @facephi/sdk-loader esteja instalado.

3

Use importação dinâmica

Use importação dinâmica na abordagem com Pages Router.

Próximos passos

• Configuração do SDK: Conheça todas as opções de configuração disponíveis

• Web Components do SDK: Explore os widgets disponíveis e suas propriedades