0.3.4 • Published 21h ago

@proteoapp/react-native-onboarding

Licence

SEE LICENSE IN LICENSE

Version

0.3.4

Deps

Size

1.2 MB

Vulns

Weekly

Summary Dependency Versions

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.

O aplicativo hospedeiro não inclui tela de configuração. Os dados iniciais (environment, tenant, backgroundCheckId, document e onFinish) devem ser passados por props.

Observações Importantes

React: 19
React Native: >=0.79.0 <0.82.0
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.

Referência: Expo - Customizing native code

Android: Versão mínima SDK 26
iOS: Versão mínima 15.5
O fluxo é em retrato. Trave a orientação do app em portrait.

Instalação

Instale o SDK:

npm install @proteoapp/react-native-onboarding

A partir da 0.3.2, essa instalação inclui Face Liveness. Use @0.3.2 (ou superior) se o lockfile ainda estiver em 0.3.1.

Dependências Parceiras (Peer Dependencies)

Este SDK requer as seguintes dependências no projeto do app, respeitando os ranges:

{
  "react": ">=19.0.0 <20.0.0",
  "react-native": ">=0.79.0 <0.82.0",
  "@react-native-async-storage/async-storage": ">=3.1.0 <4.0.0",
  "@react-native-community/geolocation": ">=3.4.0 <4.0.0",
  "@react-native-community/image-editor": ">=4.3.0 <5.0.0",
  "@react-native-documents/picker": ">=12.0.1 <13.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-gesture-handler": ">=2.30.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-webview": ">=13.13.0 <15.0.0",
  "react-native-worklets": ">=0.6.0 <0.8.0",
  "react-native-worklets-core": ">=1.6.2 <2.0.0"
}

Recomendamos esta instalação, evitando versões com mudanças incompatíveis (react e react-native já devem existir no app):

npm install @react-native-async-storage/async-storage@^3.1.0 @react-native-community/geolocation@^3.4.0 @react-native-community/image-editor@^4.3.0 @react-native-documents/picker@^12.0.1 @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-gesture-handler@^2.30.0 react-native-quick-crypto@">=0.7.17 <0.8.0" 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-webview@^13.13.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.

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

Metro (obrigatório para Face Liveness)

O AWS SDK v3 tenta carregar módulos Node no bundle. Sem este ajuste, o app costuma falhar com Symbol(node-only) ou erros de node:http.

No metro.config.js do app hospedeiro:

const { getDefaultConfig } = require('@react-native/metro-config')
const {
  withProteoOnboardingMetro,
} = require('@proteoapp/react-native-onboarding/metro')

module.exports = withProteoOnboardingMetro(getDefaultConfig(__dirname))

Se o projeto já tiver um metro.config.js (Expo, Reanimated, monorepo), aplique o helper por cima do config existente:

module.exports = withProteoOnboardingMetro(existingConfig)

Reinicie o Metro com cache limpo:

npm start -- --reset-cache

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.INTERNET" />
    <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"
        ...>
        <activity
            ...
            android:screenOrientation="portrait"
            ...>
        </activity>
    </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>
<key>UISupportedInterfaceOrientations</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
</array>

Face Liveness (AWS Rekognition)

A verificação facial usa Amazon Rekognition Face Liveness (mesmo fluxo do onboarding-web):

CreateFaceLivenessSession
Challenge via Amplify Face Liveness Detector (WebView)
GetFaceLivenessSessionResults
Upload da ReferenceImage no S3 e done_*

Requer react-native-webview, o helper de Metro acima e rede para carregar o Amplify UI (CDN) e conectar à AWS. O limiar de confidence do liveness é 5 (paridade com o web), podendo ser sobrescrito pela API (liveness_config.min_confidence).

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 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."
        }
      ],
      "react-native-webview"
    ],
    "ios": {
      "infoPlist": {
        "NSLocationWhenInUseUsageDescription": "$(PRODUCT_NAME) precisa de acesso a sua Localização.",
        "UISupportedInterfaceOrientations": [
          "UIInterfaceOrientationPortrait"
        ]
      }
    },
    "android": {
      "permissions": [
        "CAMERA",
        "RECORD_AUDIO",
        "ACCESS_FINE_LOCATION",
        "ACCESS_COARSE_LOCATION",
        "INTERNET"
      ]
    },
    "orientation": "portrait"
  }
}

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.

O metro.config.js do Expo também precisa do helper withProteoOnboardingMetro descrito acima.

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

O SDK não pede tenant, CPF ou ambiente em tela. O app hospedeiro obtém esses dados (login, backend, deep link) e passa nas props.

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: () => void
Descrição: Função chamada quando o SDK deve devolver o controle ao app hospedeiro. Isso ocorre quando:
- o usuário conclui o fluxo (sucesso ou recusa) e sai da tela final
- o processo já estava concluído na API (o SDK encerra sem novo ciclo)
- o usuário escolhe encerrar após erro ou recusa de permissão de câmera

O callback não recebe o resultado da análise. Consulte o status no backend da Proteo com o backgroundCheckId.

Uso Básico

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

export default function OnboardingScreen({ route, navigation }) {
  const { tenant, backgroundCheckId, document } = route.params

  return (
    <Onboarding
      environment="production"
      tenant={tenant}
      backgroundCheckId={backgroundCheckId}
      document={document}
      objective="onboarding"
      onFinish={() => {
        navigation.goBack()
      }}
    />
  )
}

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:

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

Keywords

proteo onboarding sdk react-native

@proteoapp/react-native-onboarding

Proteo Onboarding SDK

Observações Importantes

Instalação

Dependências Parceiras (Peer Dependencies)

Configuração por Ambiente

Metro (obrigatório para Face Liveness)

React Native CLI / Expo Bare Workflow

Configuração de Permissões

Face Liveness (AWS Rekognition)

Configuração de Arquivos

Expo Managed Workflow

Configuração do Config Plugin

Configuração de Arquivos

Gerando o Build Nativo

Componente Onboarding

Props

`environment` (obrigatório)

`tenant` (obrigatório)

`backgroundCheckId` (obrigatório)

`document` (obrigatório)

`objective` (opcional)

`onFinish` (obrigatório)

Uso Básico

Solução de Problemas

Problemas Comuns

`npm install` instalou a `0.3.1`

Erro `Symbol(node-only)`, `node:http` ou falha ao iniciar o liveness

A câmera não funciona no simulador

Erros de build no Android

Erros de build no iOS

Suporte

Keywords