实现

前置条件：获取 token

startDeviceScan 函数需要一个 token。该 token 是临时的，必须在调用 SDK 函数之前，由您的后端通过服务器到服务器请求向我们的 API 生成。

Endpoint

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

请求

Method: POST

Headers:

{
  "Authorization": "YOUR_DEVICE_SCAN_API_KEY"
}

Body:

{
  "session_id": "unique_session_id"
}

响应

成功的响应中包含需要传给 startDeviceScan 函数的 token。

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

重要提示！

设备扫描 API Key 绝不能嵌入到应用中。上述请求必须且只能由您的后端发起。用于生成 token 的 session_id 必须与传给 startDeviceScan 函数的值完全一致。

备注

设备扫描可以异步执行。因此无需阻塞界面等待 Promise 完成。在后台处理设备扫描期间，用户可以正常与应用交互。

备注

我们建议尽早执行设备扫描——例如在 useEffect 中。由于采集全部数据可能需要更长的执行时间，提前调用可确保提取到最完整的设备信息。

函数签名

await startDeviceScan(
  token,            // string - 从 API 获取的 token
  document_number,  // string - 用户的 CPF
  session_id,       // string - 会话标识
  event_id,         // string - 事件标识
  event_type,       // string - 事件类型（例如 'onboarding'）
  environment       // CAAS_ENVIRONMENT.SANDBOX 或 CAAS_ENVIRONMENT.PRODUCTION
);

每个参数的完整说明参见 startDeviceScan 函数。

完整示例

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() {
  // 第 1 步：申请可扩大采集范围的权限
  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 仅在 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
    );
  };

  // 第 2 步：通过您的后端获取 token
  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;
  }, []);

  // 第 3 步：执行采集
  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="执行设备扫描" onPress={captureDeviceScan} />
    </View>
  );
}

最佳实践

• 尽早执行设备扫描（例如在 useEffect 中）——它需要时间来采集完整的设备数据。
• 设备扫描是异步的，不会阻塞界面。无需等待 Promise 完成即可继续其他流程。
• 请在调用 startDeviceScan 之前申请权限。SDK 不会主动申请权限——它只采集已被授予的权限对应的数据。

示例应用

模块仓库的 examples 目录下包含两个可直接运行的应用：

• QITechReactNativeExample — 纯 React Native
• QITechExpoExample — Expo

在两者中，App_ds.tsx 演示了使用 @qitech/react-native-device-scan 的设备扫描。请将示例中的 API Key 替换为您的凭证。如果您尚未收到凭证，请联系 suporte.caas@qitech.com.br。