Guia de Migração: CafSDK 2.1.0 → 3.0.0-rc.3

Resumo das Mudanças

Esta documentação descreve as principais alterações na API do @caf.io/react-native-sdk entre as versões 2.1.0 e 3.0.0-rc.3, com foco específico nos métodos de inicialização.

---

🔄 Mudanças na Inicialização

1. Hook useCafSdk

Versão 2.1.0 (Anterior)

const { initialize, response } = useCafSdk(configuration, callback);

// initialize chamava automaticamente startSDK
const initialize = async () => {
  module.initialize(configurationRef.current, async (success: boolean) => {
    if (success) {
      await new Promise((resolve) => {
        callback();
        setTimeout(resolve, 10);
      });
      
      // ⚠️ startSDK era chamado automaticamente
      module.startSDK();
    }
  });
};

Características:

• Método initialize era assíncrono (async)
• Usava callback como segundo parâmetro do module.initialize
• Iniciava o SDK automaticamente após a inicialização bem-sucedida
• Retornava apenas { initialize, response }

---

Versão 3.0.0-rc.3 (Atual)

const { initialize, startSDK, loadSession, response } = useCafSdk(
  configuration, 
  callback
);

// initialize agora retorna Promise e NÃO chama startSDK automaticamente
const initialize = () => {
  module
    .initialize(configurationRef.current)
    .then((res: boolean) => {
      if (res) {
        callback();
      } else {
        throw new Error('Failed to initialize the CafSDK');
      }
    })
    .catch((error: Error) => {
      throw error;
    });
};

// Novos métodos expostos
const startSDK = () => {
  module.startSDK();
};

const loadSession = () => {
  module.loadSession();
};

Características:

• Método initialize usa Promise ao invés de callback
• NÃO inicia o SDK automaticamente - controle manual necessário
• Expõe três novos métodos: initialize, startSDK e loadSession
• Melhor tratamento de erros com .catch()

---

⚡ Ganho de Performance com loadSession()

O que é o loadSession()?

O método loadSession() é uma otimização de performance introduzida na versão 3.0.0-rc.3. Ele permite pré-carregar a sessão do SDK antes de iniciar a câmera.

🚀 Benefício de Performance

Problema na versão 2.1.0:

initialize() → startSDK() → Criação de sessão + Abertura de câmera
                            └─────────────┬─────────────┘
                                    Tempo total de espera

Solução na versão 3.0.0-rc.3:

initialize() → loadSession() → [usuário prepara-se] → startSDK() → Abertura da Câmera
              └── Sessão criada ──┘                              └── Sessão já pronta ──┘

*Tempo varia conforme latência de rede e dispositivo

💡 Quando Usar

✅ Cenários Recomendados

// 1. Carregar sessão enquanto usuário lê instruções
const onShowInstructions = () => {
  loadSession(); // Carrega em background
  showInstructionsModal();
};

// 2. Carregar após aceite de termos
const onAcceptTerms = () => {
  loadSession(); // Prepara sessão
  navigate('CameraScreen');
};

// 3. Carregar antecipadamente em fluxos com múltiplas etapas
useEffect(() => {
  if (userCompletedForm) {
    loadSession(); // Próxima etapa será a câmera
  }
}, [userCompletedForm]);

❌ Quando NÃO Usar

// ❌ Carregar muito cedo (usuário pode desistir)
const onAppLaunch = () => {
  loadSession(); // Pode não ser necessário
};

// ❌ Carregar sem initialize primeiro
const wrong = () => {
  loadSession(); // Erro: SDK não inicializado
};

O que acontece no loadSession():

1. ✅ Cria sessão com servidor CAF
2. ✅ Autentica credenciais
3. ✅ Prepara contexto de captura
4. ✅ Aloca recursos necessários

🎁 Vantagens Adicionais

✅ Melhor UX: Usuário tem um carregamento mais fluido ✅ Flexibilidade: Controle total sobre quando carregar

---

Código na Versão 2.1.0

import { useCafSdk } from '@caf.io/react-native-sdk';

const MyComponent = () => {
  const { initialize, response } = useCafSdk(
    configuration,
    () => {
      console.log('SDK initialized');
      // Módulos aplicados aqui
      applyCafDocumentDetector();
      applyCafFaceLiveness();
    }
  );

  return (
    <Button 
      title="Inicializar e Iniciar SDK" 
      onPress={initialize} // Já iniciava tudo automaticamente
    />
  );
};

---

Código na Versão 3.0.0-rc.3

import { useCafSdk } from '@caf.io/react-native-sdk';

const MyComponent = () => {
  const { initialize, startSDK, loadSession, response } = useCafSdk(
    configuration,
    () => {
      console.log('SDK initialized');
      // Módulos aplicados no callback
      applyCafDocumentDetector();
      applyCafFaceLiveness();
    }
  );

  return (
    <>
      {/* 1. Inicializar SDK (preparar configuração) */}
      <Button title="Init" onPress={initialize} />
      
      {/* 2. Carregar sessão (opcional) */}
      <Button title="Load Session" onPress={loadSession} />
      
      {/* 3. Iniciar fluxo do SDK */}
      <Button title="Start SDK" onPress={startSDK} />
    </>
  );
};

---

⚠️ Breaking Changes

1. Separação de Responsabilidades

• Antes: initialize() fazia tudo (configurar + iniciar)
• Agora: Métodos separados para cada etapa

2. Chamada Manual Obrigatória

// ❌ Não funciona mais - SDK não inicia automaticamente
initialize();

// ✅ Correto na v3.0.0-rc.3
initialize();
loadSession();

// ... depois quando necessário:
startSDK();

3. Mudança de Callback para Promise

// ❌ Versão 2.1.0
module.initialize(config, (success: boolean) => {
  if (success) { /* ... */ }
});

// ✅ Versão 3.0.0-rc.3
module
  .initialize(config)
  .then((res: boolean) => {
    if (res) { /* ... */ }
  })
  .catch((error) => { /* ... */ });

4. Novos Métodos Disponíveis

const {
  initialize,  // ✅ Modificado
  startSDK,    // ✨ NOVO
  loadSession, // ✨ NOVO
  response
} = useCafSdk(configuration, callback);

---

🔍 Mudanças no Response State

Tratamento de Múltiplos Sucessos

Versão 2.1.0:

// Sobrescrevia o sucesso anterior
success: event

Versão 3.0.0-rc.3:

// Acumula múltiplos sucessos em array
success: [...(prev.success || []), event]

Impacto no Código

// Antes (2.1.0)
if (response.success) {
  const result = response.success; // Objeto único
}

// Agora (3.0.0-rc.3)
if (response.success) {
  response.success.forEach((item) => {
    // Array de resultados
    if (item.moduleName === 'DOCUMENT_DETECTOR') {
      // processar
    }
  });
}

---

📊 Comparação Resumida

Aspecto	2.1.0	3.0.0-rc.3
initialize	async, auto-start	Promise-based, manual start
startSDK	❌ Automático	✅ Manual
loadSession	❌ Não existe	✅ Novo método (otimização)
Callback Pattern	Callback nativo	Promise
response.success	Objeto único	Array de objetos
Controle do Fluxo	Automático	Manual (mais controle)

---

✅ Checklist de Migração

• Atualizar todas as chamadas de initialize() para não esperar início automático
• Adicionar chamadas explícitas a startSDK() onde necessário
• ⚡ Adicionar loadSession() para otimizar tempo de abertura de câmera (recomendado)
• Identificar pontos no fluxo onde usuário "espera" (instruções, formulários) para chamar loadSession()
• Atualizar handlers de response.success para lidar com arrays
• Testar fluxo completo: init → load (background) → start