Implementação

Pré-requisito: obtendo o token

A função startDeviceScan exige um token. Esse token é temporário e deve ser gerado no seu backend por meio de uma requisição server-to-server para a nossa API, antes de chamar a função do SDK.

Endpoint

Ambiente	URL
Sandbox	https://d.sandbox.viewpkg.com/device_scan/token
Produção	https://d.viewpkg.com/device_scan/token

Requisição

Method: POST

Headers:

{
  "Authorization": "YOUR_DEVICE_SCAN_API_KEY"
}

Body:

{
  "session_id": "unique_session_id"
}

Resposta

A resposta bem-sucedida conterá o token que deve ser repassado à função startDeviceScan.

{
  "token": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6..."
}

Aviso Importante!

A API Key de Device Scan nunca deve ser embarcada no aplicativo. A requisição acima deve partir exclusivamente do seu backend. O session_id usado para gerar o token deve ser o mesmo repassado à função startDeviceScan.

observação

O device scan pode ser executado de forma assíncrona. Portanto, não é necessário bloquear a interface para aguardar a resolução da Promise. O usuário pode interagir normalmente com o app enquanto o device scan é processado em segundo plano.

observação

Recomendamos que o device scan seja executado o mais cedo possível — por exemplo, dentro de um useEffect. Como ele pode precisar de mais tempo de execução para coletar todos os dados, essa chamada antecipada garante que as informações mais completas do dispositivo sejam extraídas.

Assinatura da função

await startDeviceScan(
  token,            // string - token obtido na API
  document_number,  // string - CPF do usuário
  session_id,       // string - identificador da sessão
  event_id,         // string - identificador do evento
  event_type,       // string - tipo do evento (ex.: 'onboarding')
  environment       // CAAS_ENVIRONMENT.SANDBOX ou CAAS_ENVIRONMENT.PRODUCTION
);

Veja A função startDeviceScan para a descrição completa de cada parâmetro.

Exemplo completo

import * as React from 'react';
import { useCallback, useEffect } from 'react';
import { View, Button, Platform, PermissionsAndroid, Permission } from 'react-native';
import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
import { CAAS_ENVIRONMENT, startDeviceScan } from '@qitech/react-native-device-scan';

const DEVICE_SCAN_API_URL = 'https://d.sandbox.viewpkg.com/device_scan/token';
const DEVICE_SCAN_API_KEY = '<DEVICE_SCAN_API_KEY>';

const config = {
  environment: CAAS_ENVIRONMENT.SANDBOX,
  sessionId: '<SESSION_ID>',
  documentNumber: '<CPF_NUMBER>',
  deviceScanEventId: '1',
  deviceScanEventType: 'onboarding',
};

export default function App() {
  // Etapa 1: solicitar as permissões que ampliam a coleta
  const requestDeviceScanPermissions = async (): Promise<boolean> => {
    if (Platform.OS === 'ios') {
      const result = await request(PERMISSIONS.IOS.LOCATION_WHEN_IN_USE);
      return result === RESULTS.GRANTED;
    }

    const permissionsToRequest: Permission[] = [
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
      PermissionsAndroid.PERMISSIONS.READ_PHONE_STATE,
      PermissionsAndroid.PERMISSIONS.READ_CONTACTS,
    ];

    // BLUETOOTH_CONNECT só é necessária no Android 12+ (API 31+)
    if (Platform.Version >= 31) {
      permissionsToRequest.push('android.permission.BLUETOOTH_CONNECT' as Permission);
    }

    const results = await PermissionsAndroid.requestMultiple(permissionsToRequest);

    return (
      results[PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION] ===
        PermissionsAndroid.RESULTS.GRANTED ||
      results[PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION] ===
        PermissionsAndroid.RESULTS.GRANTED
    );
  };

  // Etapa 2: obter o token por meio do seu backend
  const fetchDeviceScanToken = useCallback(async () => {
    const response = await fetch(DEVICE_SCAN_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': DEVICE_SCAN_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ session_id: config.sessionId }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const data = await response.json();

    if (!data.token) {
      throw new Error("No 'token' found in response.");
    }

    return data.token;
  }, []);

  // Etapa 3: executar a coleta
  const captureDeviceScan = async (): Promise<void> => {
    try {
      const deviceScanToken = await fetchDeviceScanToken();

      const result = await startDeviceScan(
        deviceScanToken,
        config.documentNumber,
        config.sessionId,
        config.deviceScanEventId,
        config.deviceScanEventType,
        config.environment
      );

      console.log('Device Scan result: ' + String(result));
    } catch (error) {
      console.log('Error executing device scan: ' + error);
    }
  };

  useEffect(() => {
    const init = async () => {
      await requestDeviceScanPermissions();
      await captureDeviceScan();
    };
    init();
  }, []);

  return (
    <View>
      <Button title="Executar Device Scan" onPress={captureDeviceScan} />
    </View>
  );
}

Boas práticas

• Execute o device scan o mais cedo possível (por exemplo, em um useEffect) — ele precisa de tempo para coletar os dados completos do dispositivo.
• O device scan é assíncrono e não bloqueia a interface. Não é necessário aguardar a resolução da Promise para prosseguir com os demais fluxos.
• Solicite as permissões antes de chamar startDeviceScan. O SDK não solicita permissões por conta própria — ele apenas coleta o que já foi concedido.

Aplicativos de exemplo

O repositório do módulo contém dois aplicativos prontos para execução, na pasta examples:

• QITechReactNativeExample — React Native puro
• QITechExpoExample — Expo

Em ambos, o arquivo App_ds.tsx demonstra o uso do Scan de dispositivo com o @qitech/react-native-device-scan. Substitua as API Keys de exemplo pelas suas credenciais. Caso ainda não as tenha recebido, entre em contato com o suporte.caas@qitech.com.br.