@amazon-devices/security-manager-lib
セキュリティマネージャーAPIは、アプリが実行時の権限をリクエストできるようにする機能を提供します。
実行時の権限は、システムから提供されるプライバシーにかかわるリソースへのアクセスを制限するために使用されます。実行時の権限で保護されているリソースにアプリからアクセスするには、その前にユーザーの明示的な同意を得る必要があります。このような制限されたリソースの例としては、マイクやカメラがあります。
開始の手順
セットアップ
package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。
"@amazon-devices/security-manager-lib: "~1.0",
使用方法
実行時の権限のリクエスト
カメラやマイクなどのリソースにアクセスする許可をリクエストするには、以下のメソッドを使用します。
利用可能なすべての権限のセットについては、PermissionsKeplerのPERMISSIONSを参照してください。
呼び出し側パッケージ用のgetPrivilegeState()
getPrivilegeState()メソッドには2つのバージョンがあります。アプリで使用するためのバージョンは、次のように定義されています。
static async getPrivilegeState(
privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>
このメソッドを使用すると、実行時の権限によって保護されているメソッドを使用する許可があるかどうかをアプリで判断できます。
このメソッドは非同期で動作し、awaitまたはthen()コンストラクトを使用して待機できるPromise<SecurityManagerTypes.PrivilegeState>オブジェクトを返します。
成功すると、Promiseのペイロードは権限の現在の状態を示します。これは次のいずれかになります。
SecurityManagerTypes.PrivilegeState.ALLOW- ユーザーは既に、リクエストされた権限をこのアプリに付与することに同意しています。ユーザーに権限をリクエストする必要はありません。SecurityManagerTypes.PrivilegeState.DENY- ユーザーは既に権限のリクエストを拒否しているか、まだ同意のリクエストが行われていません。requestPrivilege()メソッドを使用して、ユーザーに同意を求める画面を表示します。
エラーが発生した場合、Promiseは拒否され、エラーメッセージが表示されます。
requestPrivilege()
アプリから権限にアクセスする必要があるときは、requestPrivilege()メソッドを呼び出します。OSは権限リクエストハンドラーを起動して応答します。権限リクエストハンドラーは、ユーザーに同意を求めて結果を保存するシステムコンポーネントです。
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を指定する必要があるという点です。
このメソッドは非同期で動作し、アプリでawaitまたはthen()コンストラクトを使用して待機できるPromise<SecurityManagerTypes.PrivilegeState>オブジェクトを返します。
成功すると、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日
