@amazon-devices/security-manager-lib
安全管理器API提供的功能可让您的应用申请运行时权限。
运行时权限用于限制对系统提供的隐私敏感资源的访问。必须在用户明确同意后，应用方可访问受运行时权限保护的资源。此类受限资源的示例包括麦克风和摄像头。
开始使用
设置
将以下库依赖项添加到package.json文件的dependencies部分。
"@amazon-devices/security-manager-lib: "~1.0",
用法
申请运行时权限
使用以下方法申请授权，以访问摄像头或麦克风等资源。
有关可用的全套权限，请参阅PermissionsKepler中的PERMISSIONS。
用于调用程序包的getPrivilegeState()
getPrivilegeState() 方法有两个版本。应用需要使用的版本定义如下：
static async getPrivilegeState(
privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>
此方法允许应用确定是否允许其使用受运行时权限限制的方法。
此方法是异步的，返回一个Promise<SecurityManagerTypes.PrivilegeState>对象，可以使用await或then() 构造来等待该对象。
成功后，Promise的有效负载是权限的当前状态，具体为以下之一：
SecurityManagerTypes.PrivilegeState.ALLOW- 这表示用户已经同意向该应用授予所申请的权限。无需向用户申请权限。SecurityManagerTypes.PrivilegeState.DENY- 这表示已申请用户提供权限但用户拒绝，或表示从未向用户申请过同意。使用requestPrivilege()方法提示用户予以同意。
如果发生错误，Promise将被拒绝，并显示一条错误消息。
requestPrivilege()
应用在需要访问权限时使用requestPrivilege() 方法。操作系统通过启动“权限申请处理程序”进行响应，该处理程序是负责征求用户同意并存储结果的系统组件。
static async requestPrivilege(
privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>
成功后，Promise的有效负载是权限的新状态，具体为以下之一：
SecurityManagerTypes.PrivilegeState.ALLOW- 用户已同意向应用授予权限。该应用应继续访问其所需的特权资源。SecurityManagerTypes.PrivilegeState.DENY- 用户拒绝了权限申请。应用应适当将功能降级。该应用不应持续提示用户，申请其允许访问。只有在用户执行了另一项表明他们希望应用访问受保护资源的操作后，才应再次调用此方法。
如果发生错误，Promise将被拒绝，并显示一条错误消息。
用法示例
以下示例演示如何使用安全管理器在您的应用中实现麦克风访问权限。此代码显示了当用户尝试访问录制功能时检查和请求麦克风权限的完整流程，包括正确的错误处理以及根据用户的权限选择导航到相应的界面。如果授予权限，用户将被定向到录制界面；如果被拒绝，则会向他们显示访问被拒绝界面。
const handleRecordButtonPress = () => {
// 通过上面的数组来包装索引
SecurityManager.getPrivilegeState('com.amazon.audio.privilege.microphone.access').then(
function(state: PrivilegeState) {
if (state == PrivilegeState.ALLOW) {
navigation.navigate('RecordScreen');
} else {
SecurityManager.requestPrivilege('com.amazon.audio.privilege.microphone.access').then(
function(state: PrivilegeState) {
if (state == PrivilegeState.ALLOW) {
navigation.navigate('RecordScreen');
} else {
navigation.navigate('MicrophoneAccessDeniedScreen');
}
},
function(error: Object) { KPLOG().error("申请权限失败：{}", error["message"]); }
)
}
},
function(error: Object) { KPLOG().error("无法获取权限状态：{}", error["message"]); }
)
};
权限申请处理程序和隐私控制面板
权限申请处理程序是一个系统组件，负责从用户那里获得访问权限的同意并存储结果。
隐私控制面板是设置应用中的一个集中位置，用户可以在其中查看和更改其隐私设置。
权限申请处理程序的getPrivilegeState()
特权组件使用的getPrivilegeState() 方法的版本定义如下。
static async getPrivilegeState(
packageId: string,
privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>
这与其他变体的不同之处在于，必须指定所需程序包的程序包ID。
此方法是异步的，返回一个Promise<SecurityManagerTypes.PrivilegeState>对象，应用可以使用await或then() 构造来等待该对象。
成功后，Promise的有效负载是权限的当前状态，具体为以下之一：
SecurityManagerTypes.PrivilegeState.ALLOW- 这表示用户已经同意向该应用授予所申请的权限。SecurityManagerTypes.PrivilegeState.DENY- 这表示已申请用户提供权限但用户拒绝，或表示从未向用户申请过同意。
如果发生错误，Promise将被拒绝，并显示一条错误消息。
使用示例
SecurityManager.getPrivilegeState(
'com.amazon.keplersampleapp',
'com.amazon.audio.privilege.microphone.access'
).then(
function(state: PrivilegeState) {
// 权限状态：state
},
function(error: Object) {
// 无法获取权限状态：error["message"]
}
);
访问控制
此方法需要 com.amazon.privilege.package.query运行时权限，因为它可让调用者确定用户安装了哪些应用，这是一个隐私问题。此权限要求调用应用具有平台签名。
为了防止权限申请影响体验，Kepler仅在应用首次申请权限时显示此模式对话框。用户使用对话框做出选择，该设置将被记录下来。用户可以随时通过设置应用自由更改该选择。
权限错误
如果您的应用使用未在清单上声明的服务，您在启动应用时会收到错误。
以下示例日志消息说的是应用未在应用清单中正确声明Wi-Fi服务依赖项。
Apr 24 13:39:59.613429 firestick-c93bfe9ecdeea42f local0.err netsvc[985]: 1317 E securitymgr:[SecurityManager.cpp:124] Privilege 'com.amazon.wifi.privilege.read-wifi-credential' not granted
相关主题
模块
- index
- native-security-manager
- SecurityManager
- types
- types
- types/SecurityManagerTypes
- types/SecurityManagerTypes
Last updated: 2025年10月2日
