@amazon-devices/simplesignin
シンプルサインインサービスAPIは、サードパーティのアプリ開発者が、アプリのユーザーアカウントと、顧客がデバイスに登録したAmazonアカウントをリンクし、そのリンクを使用してユーザーをスムーズにサインインさせ、それ以降のログイン試行に利用できるようにする機能を提供します。シンプルサインインサービスAPIでは、次の操作を実行できます。
- サードパーティアプリのユーザーのアカウントをAmazonアカウントにリンクします。
- サードパーティアプリ用に作成されたユーザー用の既存のリンクを取得します。
- サードパーティアプリのユーザーのログイン用オプションを含む選択画面を表示します。
- ビジネス指標を記録します。
開始の手順
セットアップ
-
package.jsonファイルの
dependenciesセクションに、以下のライブラリ依存関係を追加します。"@amazon-devices/simplesignin": "~1.1", -
manifest.tomlに、以下の権限を追加します。
[[wants.module]] id = "/com.amazon.dms.ssi@ISimpleSignIn" [[wants.service]] id = "com.amazon.dms.ssi.service" [[wants.interactive]] id = "com.amazon.dms.ssi.loginselection" [[wants.interactive]] id = "com.amazon.dms.ssi.consent"これにより以下のアクセス権が付与されます。
- シンプルサインインシステムサービスにアクセスする。
- ユーザーの同意を求める画面を表示することを許可する。
- ログインオプションをユーザーに表示する画面を表示することを許可する。
使用方法
次のセクションでは、シンプルサインインを使用してアカウントリンクを実行し、ユーザーをログインさせる方法を示します。
GetUserAndLinks
次の例では、アプリを実行しているデバイスで現在アクティブなAmazonユーザーのシンプルサインイン関連のデータを取得するリクエストを開始します。
let promise = SimpleSignInService.getUserAndLinks(IDP_NAME);
promise.then(
(response) => {
// レスポンスを処理します
}
);
LinkUserAccount
次の例では、ユーザーのアプリアカウントのアカウントリンクを開始します。この例では、Amazonとアプリアカウントの間の多対多マッピングが可能になります。1つのAmazonアカウントに複数のアプリアカウントを同時にリンクさせることができ、また、1つのアプリアカウントに複数のAmazonアカウントをリンクさせることもできます。
let promise = SimpleSignInService.linkUserAccount(request);
promise.then(
(response) => {
// レスポンスを処理します
}
);
ShowLoginSelection
次の例では、ユーザーにログインオプションを表示するダイアログを開きます。このメソッドを呼び出す前に、リンク済みアカウントごとにユーザーが認識しやすい識別子を取得し、この識別子をリクエストに含めます。これらの識別子は、getUserAndLinks()メソッドを呼び出すことで取得します。ユーザーが認識できる識別子には、ログイン名、Eメールアドレス、プロフィール名などがありまます。これらの識別子は画面に表示され、リンクされたアプリアカウントをユーザーが認識しやすくするために使用されます。
let promise = SimpleSignInService.showLoginSelection(request);
promise.then(
(response) => {
// レスポンスを処理します
}
);
RecordMetricEvent
次の例では、指標の公開用に記録されたイベントを起動します。シンプルサインインのビジネス指標レポートは、開発者コンソールの [レポート] タブでダウンロードできます。これらの指標は、シンプルサインインの統合によるビジネス価値や影響を把握するためのものです。
let request = {
ssiEvent: SSIEvent.***,
timestamp : <エポックタイムスタンプ（ミリ秒）>,
failureReason = <FailureReason.***> // SSIEventがFailureとなっている場合、このフィールドは必須です。
};
let promise = SimpleSignInService.recordMetricEvent(request);
promise.then((response) => {
// 通常、このAPIで処理することは何もありません。
});
サインインフローの実装
サインインフローを実装する前に、IDプロバイダー名（IDP_NAME）が必要になります。これは、開発者コンソールでのアプリのオンボーディングプロセス中に提供されます。この一意の識別子により、アプリをシンプルサインインサービスに接続できます。
サインインについて
通常、サインインプロセスは次の場合に開始されます。
- アプリが起動したとき
- ユーザーがログインボタンをクリックしたとき
- セッションで認証が必要になったとき
次の例は、GetUserAndLinks()メソッドを使用して基本的なサインインフローを実装する方法を示しています。
let getUserAndLinksPromise = SimpleSignInService.getUserAndLinks(IDP_NAME); // APIを呼び出します
getUserAndLinksPromise.then( // レスポンスを処理します
(response) => {
if (response.requestStatus != RequestStatus.SUCCESSFUL) {
// requestStatusを確認します。
// たとえば、ユーザーが自分のアカウント、このデバイス、このアプリのいずれかでシンプルサインインを無効にしている場合、リクエストは成功しません。
// フォールバックしてアプリの標準ログインを表示します
} else if (response.links?.length! > 0) {
// これは、ユーザーが使用してログインできるリンクが存在することを意味します
/*
* ShowLoginSelectionを準備します。
* このコードはカスタマイズされたコードです。ユーザーへの各リンクに
* 表示するログイン名を入手する必要があります
* ログイン名は使用するサーバーから取得できます。
*/
let request:LoginNameValue[] = [];
response.links?.forEach((link) => {
request.push({loginName: <リンクのログイン名>, linkId: link.linkId});
});
// ShowLoginSelection APIを呼び出します
let showLoginSelectionPromise = SimpleSignInService.showLoginSelection(request);
showLoginSelectionPromise.then((response) => { // ユーザーが選択した項目を処理します
if (response.userSelection == UserSelection.MANUAL_SIGN_IN) { // ユーザーは新しいアカウントでログインすることを選択しました
// アプリの標準ログインを表示します
} else if (response.userSelection == UserSelection.LOGIN_SELECTED) { // ユーザーは既存のリンクでログインすることを選択しました
// リンクIDを適切なメソッドまたはアプリのサーバーに渡して認証します
} else {
// ユーザーが15分間何も選択しなかったか、リクエストが失敗したことを意味します
// フォールバックしてアプリの標準ログインを表示します
}
});
} else {
// ユーザー用のリンクがまだ作成されていないことを意味します
// フォールバックしてアプリの標準ログインを表示します
}
}
);
アカウントリンクのプロセス
標準ログインに成功したら、ユーザーのアカウントをリンクして、今後のセッションでスムーズにサインインできるようにする必要があります。このプロセスにより、ユーザーのAmazonアカウントとアプリのアカウントが安全に接続されます。
次の例では、アプリの標準ログイン方法を使用してユーザーアカウントをアプリにリンクします。
ユーザーがアプリの標準ログインプロセスを使用してサインインするたびに、LinkUserAccount()メソッドを呼び出します。
let request = {
partnerUserId: <partnerUserId>,
identityProviderName: <IDP_NAME>,
userLoginName: <ユーザーに表示するユーザーアカウントのログイン名>,
linkToken: {
token: <サーバーが生成したトークン>
schema: "LINK-TOKEN-1.0"
},
linkSigningKey: <サーバーが生成したリンク署名キー>
};
// LinkUserAccount APIを呼び出します
let promise = SimpleSignInService.linkUserAccount(request);
promise.then((response) => { // レスポンスを処理します
if (response.successCode == LinkAccountSuccessCode.LINK_ESTABLISHED) {
// アプリのユーザーアカウントに対応する、レスポンスで返されたリンクIDをサーバーに保存します。
// `response.linkId`を使用します。
} else if (response.successCode == LinkAccountSuccessCode.LINK_ALREADY_EXISTS) {
//新しいリンクが作成されたので、アプリのユーザーアカウントに対応する、レスポンスで返されたリンクIDをサーバーに保存します。
// `response.linkId`を使用します。
} else if (response.successCode != LinkAccountSuccessCode.CONSENT_DENIED) {
// ユーザーがこのアカウントをリンクしないことを意味します。
// この時点では何もする必要はありません。アプリのログイン後の処理を続行します。
} else {
// シンプルサインインサービスで何らかのエラーが発生しました。requestStatusを確認し、
// 問題が解決しない場合はAmazonに報告してください。
}
});
トラブルシューティング
-
同意画面またはログイン選択画面が表示されません。
マニフェストが更新されていることを確認してください。[[wants.module]] id = "/com.amazon.dms.ssi@ISimpleSignIn" [[wants.service]] id = "com.amazon.dms.ssi.service" [[wants.interactive]] id = "com.amazon.dms.ssi.loginselection" [[wants.interactive]] id = "com.amazon.dms.ssi.consent" -
API呼び出しで、リクエストステータスに
FEATURE_TURNED_OFFが返されます。これは、ユーザーがアカウントレベル、デバイスレベル、またはアプリでシンプルサインイン機能を無効にしていることを示しています。
-
API呼び出しで、リクエストステータスに
NOT_AVAILABLEが返されます。これは、デバイスが実行されている地域ではシンプルサインイン機能が利用できないことを示しています。
列挙型
クラス
型エイリアス
- GetUserAndLinksResponse
- Link
- LinkUserAccountRequest
- LinkUserAccountResponse
- LoginNameValue
- RecordMetricsEventResponse
- ShowLoginSelectionResponse
- SSIEventRequest
- トークン
Last updated: 2025年10月2日
