Proteo Onboarding SDK

SDK React Native para onboarding
Permite que apps react native integrem um processo de onboarding de forma simples.

O SDK é plug-and-play no código JavaScript, mas depende de implementações nativas para funcionar.

⚠️ Observações Importantes

• React Native: Versão mínima 0.79
• Expo: Versão mínima SDK 53
  • Este SDK depende de código nativo, portanto não funciona no Expo Go.
  • Para usar em Expo Managed, é necessário criar um Development Build ou usar EAS Build com Expo Config Plugin que configure automaticamente as dependências nativas.

Referência: Expo - Customizing native code

• Android: Versão mínima SDK 26
• iOS: Versão mínima 15.5

📦 Instalação

1. Instale o SDK:

npm install @proteoapp/react-native-onboarding

Dependências Parceiras (Peer Dependencies)

Este SDK requer as seguintes dependências instaladas no seu projeto respeitando os ranges informados:

{
  "@react-native-community/geolocation": ">=3.4.0 <4.0.0",
  "@react-native-community/image-editor": ">=4.3.0 <5.0.0",
  "@react-navigation/native": ">=7.1.18 <7.3.0",
  "@react-navigation/native-stack": ">=7.3.28 <7.5.0",
  "@shopify/react-native-skia": ">=2.2.4 <3.0.0",
  "react-native-compressor": ">=1.16.0 <2.0.0",
  "react-native-fs": ">=2.20.0 <3.0.0",
  "react-native-quick-crypto": ">=0.7.17 <0.8.0",
  "react-native-reanimated": ">=4.1.2 <5.0.0",
  "react-native-safe-area-context": ">=5.6.0 <6.0.0",
  "react-native-screens": ">=4.14.0 <5.0.0",
  "react-native-svg": ">=15.13.0 <16.0.0",
  "react-native-vision-camera": ">=4.7.0 <5.0.0",
  "react-native-vision-camera-face-detector": ">=1.10.1 <1.12.0",
  "react-native-worklets": ">=0.6.0 <0.8.0",
  "react-native-worklets-core": ">=1.6.2 <2.0.0"
}

Recomendamos utilizar esta instalação, evitando a instalação automática de versões com mudanças incompatíveis:

npm install @react-native-community/geolocation@^3.4.0 @react-native-community/image-editor@^4.3.0 @react-navigation/native@">=7.1.18 <7.3.0" @react-navigation/native-stack@">=7.3.28 <7.5.0" @shopify/react-native-skia@^2.2.4 react-native-compressor@^1.16.0 react-native-fs@^2.20.0 react-native-quick-crypto@^0.7.17 react-native-reanimated@^4.1.2 react-native-safe-area-context@^5.6.0 react-native-screens@^4.14.0 react-native-svg@^15.13.0 react-native-vision-camera@^4.7.0 react-native-vision-camera-face-detector@">=1.10.1 <1.12.0" react-native-worklets@">=0.6.0 <0.8.0" react-native-worklets-core@^1.6.2

Importante: Caso você utilize versões fora dos ranges informados acima, a compatibilidade com o SDK não é garantida.
Nesses casos, será necessário validar manualmente se as dependências continuam funcionando corretamente com o processo de onboarding.

2. Limpeza e instalação das dependências nativas (recomendado):

Android:

cd android
./gradlew clean
cd ..

iOS:

cd ios
rm -rf build
rm -rf Podfile.lock
cd ..

Depois, instale os pods:

npx pod-install

Nota: Executar esses comandos de limpeza antes do npx pod-install ajuda a evitar problemas de resolução de módulos nativos e conflitos de dependências, especialmente após instalar ou atualizar bibliotecas do SDK.

🔧 Configuração por Ambiente

React Native CLI / Expo Bare Workflow

Configuração de Permissões

Android

Certifique-se de que seu AndroidManifest.xml contenha:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <application
        ...
        android:allowBackup="false"
        tools:replace="android:allowBackup"
        ...>
        ...
    </application>
</manifest>

iOS

Adicione as seguintes chaves ao seu arquivo Info.plist:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) precisa de acesso a sua Camera.</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) precisa de acesso ao seu Microfone.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) precisa de acesso a sua Localização.</string>

Configuração de Arquivos

Adicione os seguintes plugins ao seu babel.config.js:

module.exports = {
  // ... outras configurações
  plugins: [
    ['react-native-worklets-core/plugin'],
    'react-native-worklets/plugin',
  ],
}

Importante: O plugin react-native-worklets/plugin deve sempre ficar em último lugar na lista de plugins.

Android - MainActivity.kt

Adicione o seguinte código ao seu MainActivity.kt:

class MainActivity: ReactActivity() {
  // ...
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(null)
  }
  // ...
}

e certifique-se de adicionar a seguinte importação no topo deste arquivo, abaixo da definição do pacote:

import android.os.Bundle

Após configurar é recomendado limpar o cache do Metro Bundler:

npm start -- --reset-cache

Expo Managed Workflow

⚠️ Aviso: O suporte para Expo Managed Workflow ainda não foi totalmente testado.
Embora a documentação siga as recomendações do Expo, recomendamos cautela e testes adicionais antes de usar em produção.

Configuração do Config Plugin

Adicione o seguinte plugin ao seu app.json:

{
  "expo": {
    "plugins": [
      [
        "react-native-vision-camera",
        {
          "cameraPermissionText": "$(PRODUCT_NAME) precisa de acesso a sua Camera.",
          "enableMicrophonePermission": true,
          "microphonePermissionText": "$(PRODUCT_NAME) precisa de acesso ao seu Microfone."
        }
      ]
    ]
  }
}

Configuração de Arquivos

Adicione os seguintes plugins ao seu babel.config.js:

module.exports = {
  // ... outras configurações
  plugins: [
    ['react-native-worklets-core/plugin'],
    'react-native-worklets/plugin',
  ],
}

Importante: O plugin react-native-worklets/plugin deve sempre ficar em último lugar na lista de plugins.

Gerando o Build Nativo

Após adicionar o plugin, execute:

npx expo prebuild --clean

Consulte a Documentação EAS Build para mais informações.

🧩 Componente Onboarding

Props

environment (obrigatório)

• Tipo: 'development' | 'staging' | 'production'
• Descrição: Define o ambiente de execução:
  • 'development': Ambiente local ou de desenvolvimento, utilizado durante implementação e testes
  • 'staging': Ambiente de homologação ou pré-produção, usado para validação do processo e seus fluxos de execução, além de testes de QA
  • 'production': Ambiente de produção, utilizado por usuários finais, operando apenas com serviços e dados definitivos, com foco em estabilidade, segurança e desempenho

tenant (obrigatório)

• Tipo: string
• Descrição: Identificador único do cliente que está utilizando o SDK. Este valor é fornecido pela Proteo durante o processo de integração.

backgroundCheckId (obrigatório)

• Tipo: string
• Descrição: ID único da verificação de antecedentes associada ao processo de onboarding. Identifica a sessão específica de verificação do usuário.

document (obrigatório)

• Tipo: string
• Descrição: CPF do usuário que irá fazer o onboarding. Deve ser enviado sem formatação (apenas números).

objective (opcional)

• Tipo: 'onboarding' | 'face-auth'
• Padrão: 'onboarding'
• Descrição: Define o processo a ser executado:
  • 'onboarding': Processo completo com captura de documento e autenticação facial
  • 'face-auth': Processo com apenas autenticação facial

onFinish (obrigatório)

• Tipo: Function
• Descrição: Função que será chamada ao finalizar o processo.

Uso Básico

import { Onboarding } from '@proteoapp/react-native-onboarding'

export default function App() {
  return (
    <Onboarding
      environment="development"
      tenant="minha-empresa"
      backgroundCheckId="bg-check-123456"
      document="12345678900"
      onFinish={() => {
        navigation.navigate('Screen')
      }}
    />
  )
}

🛠️ Solução de Problemas

Problemas Comuns

A câmera não funciona no simulador

Simuladores iOS e Android não suportam câmera. Teste em dispositivos físicos.

Erros de build no Android

• Certifique-se de que o minSdkVersion é 26 ou superior em build.gradle
• Verifique se todas as dependências nativas foram instaladas corretamente

Erros de build no iOS

• Execute pod install no diretório ios
• Verifique se a versão do Xcode é compatível
• Certifique-se de que as configurações de signing estão corretas
• A versão mínima do iOS é 15.5 - verifique as configurações de deployment target

🧑‍💻 Suporte

Se você encontrar problemas ao usar o SDK, por favor:

1. Verifique a seção de Solução de Problemas
2. Entre em contato com o suporte