XuqmGroup-Web/docs-site/docs/rn/license.md

React Native 授权管理（License SDK）

包名：@xuqm/rn-license · 依赖：react-native-quick-crypto（peer dep）

---

1. 安装

yarn add @xuqm/rn-license react-native-quick-crypto

iOS 需要执行 pod install：

cd ios && pod install

---

2. 放置 License 文件

从租户平台下载 .xuqmlicense 加密文件，通过 require() 将其作为文本资源嵌入 App。

// 将 license.xuqm 放入 src/assets/
const licenseContent = require('./assets/license.xuqm')

---

3. 检查授权

import { initializeFromFile, checkLicense } from '@xuqm/rn-license'

// 启动时从加密文件自动初始化
const licenseContent = require('./assets/license.xuqm')
await initializeFromFile(licenseContent)

// 检查授权（有缓存时直接返回，否则网络验证）
const result = await checkLicense()
if (result.type === 'success') {
  console.log('授权通过:', result.reason)
} else {
  console.warn('授权失败:', result.message)
}

---

4. 携带用户信息

import type { LicenseUserInfo } from '@xuqm/rn-license'

const userInfo: LicenseUserInfo = {
  userId: 'user_001',
  name: '张三',
  email: 'zhangsan@company.com',
}

const result = await checkLicense(userInfo)

---

5. API 说明

initializeFromFile

initializeFromFile(encryptedContent: string): Promise<void>

从加密 License 文件内容自动解析 appKey 和 baseUrl 并初始化。

checkLicense

checkLicense(userInfo?: LicenseUserInfo): Promise<LicenseResult>

返回 { type: 'success', reason: string } 或 { type: 'error', message: string }。

缓存策略：10 分钟有效期，有效期内直接返回缓存结果（不发起网络请求）。

getStatus

getStatus(): Promise<LicenseStatus>  // 'ok' | 'denied' | 'unknown'

getDeviceId

getDeviceId(): Promise<string>

clear

clear(): Promise<void>

---

6. 数据存储

数据	存储方式
deviceId	AsyncStorage
token	AsyncStorage
授权状态	AsyncStorage
statusTime	AsyncStorage

---

7. 离线模式

• 首次激活需要网络连接
• 激活后 10 分钟缓存内可离线使用
• 网络异常时，若历史缓存成功，继续返回授权通过

---

8. 完整示例

import React, { useEffect, useState } from 'react'
import { View, Text } from 'react-native'
import { initializeFromFile, checkLicense } from '@xuqm/rn-license'

export default function App() {
  const [licensed, setLicensed] = useState<boolean | null>(null)

  useEffect(() => {
    async function verify() {
      const content = require('./assets/license.xuqm')
      await initializeFromFile(content)
      const result = await checkLicense({ userId: 'user_001' })
      setLicensed(result.type === 'success')
    }
    verify()
  }, [])

  if (licensed === null) return <Text>验证中...</Text>
  if (!licensed) return <Text>授权验证失败，请联系管理员</Text>
  return <View>{ /* 主界面 */ }</View>
}

---

9. 常见问题

Q: 提示 react-native-quick-crypto not available？ 确认已安装 react-native-quick-crypto 并执行了 pod install（iOS）或重新 build（Android）。

Q: License 文件如何用 require 加载？ 需要在 Metro 配置中将 .xuqm 加入 assetExts：

// metro.config.js
const config = {
  resolver: {
    assetExts: [...defaultConfig.resolver.assetExts, 'xuqm'],
  },
}