アプリで必要な変更

シンプルサインインを実装するには、アプリに次の変更を加えます。

• Appstore SDKとの統合
• シンプルサインインAPIの統合
  • 手順1： 非同期レスポンスメッセージを処理する
  • 手順2： 具象実装を登録する
  • 手順3： サインインフローを変更してシンプルサインインを有効にする
  • 手順4： アプリのアップグレードシナリオを処理する
    • 実装に関するガイダンス
• シンプルサインインの統合のテスト

Appstore SDKとの統合

シンプルサインイン機能はAppstore SDKで提供されます。アプリにシンプルサインインを統合するには、Appstore SDKを統合し、コードでシンプルサインインAPIを使用します。

Appstore SDKをプロジェクトに追加するために必要な手順については、Appstore SDKの統合を参照してください。AmazonのAppstore SDKには、アプリ内課金（IAP）やデジタル著作権管理（DRM）などの機能も含まれています。既存のアプリの統合手順は、既にアプリ内課金（IAP）やAmazon管理のDRMを使用しているかどうかによって異なります。詳細については、Appstore SDKへの移行を参照してください。

シンプルサインインAPIの統合

SDK内のcom.amazon.device.simplesigninパッケージには、シンプルサインインと統合するためのクラスとインターフェイスが含まれています。このパッケージには主に2つのファイルがあります。

SimpleSignInServiceクラス

このクラスは、アプリをシンプルサインインと統合するためのメソッドを公開し、その他の構成を保持するエントリポイントです。このクラスのメソッドを使用すると、アプリはシンプルサインインサーバーと通信できます。

SimpleSignInServiceには次のメソッドが含まれています。

• registerResponseHandler(Context appContext, ISimpleSignInResponseHandler responseHandler)： ほかのSimpleSignInService APIを呼び出す前に、ISimpleSignInResponseHandlerのインスタンスを作成し、そのインスタンスをアプリコンテキストと共にこのメソッドに渡して、レスポンスハンドラーを登録する必要があります。このメソッドを呼び出す前にほかのAPIを呼び出すと、IllegalStateExceptionがスローされます。
• linkUserAccount(LinkUserAccountRequest linkUserAccountRequest)： このメソッドは、ユーザーのアカウントをAmazonアカウントにリンクするためのリクエストを開始します。レスポンスが返されると、ISimpleSignInResponseHandlerのコールバックメソッドonLinkUserAccountResponse()が呼び出されます。
• getUserAndLinks(String identityProviderName)： 現在ログインしているユーザーのリンクデータを取得するリクエストを開始するには、このメソッドを呼び出します。レスポンスが返されると、ISimpleSignInResponseHandlerのコールバックメソッドonGetUserAndLinksResponseが呼び出されます。identityProviderNameパラメーターは、SSIのオンボーディング中に受け取る一意のSSI IDです。
• showLoginSelection(Map <String, String> loginNames)： 使用可能なリンク済みアカウントの一覧を表示し、ユーザーがそこから選択できるようにするリクエストを開始するには、このメソッドを呼び出します。loginNamesパラメーターは、linkIdをユーザーが認識できる識別子に対応付けるマップです。ユーザーが選択すると、ISimpleSignInResponseHandlerのコールバックメソッドonShowLoginSelectionResponse()が呼び出されます。
• recordMetricEvent(SSIEventRequest ssiEventRequest)： 指標公開用のSSIイベントを記録するリクエストを開始するには、このメソッドを呼び出します。レスポンスが返されると、ISimpleSignInResponseHandlerのコールバックメソッドonRecordMetricsEventResponse()が呼び出されます。

ISimpleSignInServiceResponseHandlerインターフェイス

このインターフェイスには、SimpleSignInServiceを通じてリクエストを開始したときに非同期レスポンスをアプリに送信する、コールバックメソッドの定義が含まれています。このインターフェイスの実装を作成し、registerResponseHandler()メソッドを呼び出して、SimpleSignInServiceに実装を登録する必要があります。ISimpleSignInServiceResponseHandlerのインスタンスには、次のメソッドを実装する必要があります。

• onLinkUserAccountResponse(LinkUserAccountResponse linkUserAccountResponse)： このコールバックメソッドは、SimpleSignInService.linkUserAccount()を呼び出した後、AmazonからLinkUserAccountResponseオブジェクトが返されるときに呼び出されます。
• onGetUserAndLinksResponse(GetUserAndLinksResponse getUserAndLinksResponse)： このコールバックメソッドは、SimpleSignInService.getUserAndLinks()を呼び出した後、AmazonからGetUserAndLinksResponseオブジェクトが返されるときに呼び出されます。
• onShowLoginSelectionResponse(ShowLoginSelectionResponse showLoginSelectionResponse)： このコールバックメソッドは、SimpleSignInService.showLoginSelection()を呼び出した後、AmazonからShowLoginSelectionResponseオブジェクトが返されるときに呼び出されます。
• onRecordMetricsEventResponse(RecordMetricsEventResponse recordMetricsEventResponse)： このコールバックメソッドは、SimpleSignInService.recordMetricEvent()を呼び出した後、AmazonからRecordMetricsEventResponseオブジェクトが返されるときに呼び出されます。

手順1： 非同期レスポンスメッセージを処理する

シンプルサインインサービスからの非同期レスポンスメッセージを処理するために、ISimpleSignInServiceResponseHandlerの実装を提供します。

例として、 シンプルサインインからのレスポンスメッセージを処理する方法を以下に示します。

public class ResponseHandlerImpl implements ISimpleSignInResponseHandler {
  public void onLinkUserAccountResponse(LinkUserAccountResponse response) {
    // ユーザーに通知するカスタムロジックを追加します。これは省略可能であり、
    // 開発者がユーザーエクスペリエンスを決定できます。
  }

  public void onGetUserAndLinksResponse(GetUserAndLinksResponse response) {
    /*
     *（a）新しいアカウントリンクの設定中は、デバイスでアクティブなAmazonユーザーアカウントの
     *     Directed IDをレスポンスから抽出し、それをlinkTokenの生成に使用します。
     *（b）新しいサインインの試行中は、リンク済みユーザーアカウントのSSIトークンを
     *     レスポンスから抽出し、それを使用して開発者側でユーザーを認証します。必要に応じて、
     *     ShowLoginSelection APIを呼び出して、ログイン選択画面からユーザーの確認を
     *     求めます。
     */
  }
  public void onShowLoginSelectionResponse(ShowLoginSelectionResponse response) {
    /*
     * ユーザーがログイン選択画面で行った選択に応じて、選択されたリンク済み
     * アカウントに対応するSSIトークンを使用してユーザーをログインさせるか、
     * 標準のサインインエクスペリエンスに誘導します。
     */
  }
  public void onLinkUserAccountResponse(LinkUserAccountResponse response) {
    // ユーザーに通知するカスタムロジックを追加します。これは省略可能であり、
    // 開発者がユーザーエクスペリエンスを決定できます。
  }
  public void onRecordMetricsEventResponse(RecordMetricsEventResponse recordMetricsEventResponse) {
    // 指標が正常に公開されたかどうかを追跡するためのログをここに追加できます。
    // これは省略可能です。
  }
}

SSIクライアントからレスポンスメッセージをAndroidインテントとして受信するには、アプリのマニフェストファイルで次のブロードキャストレシーバーを宣言します。

<receiver android:name="com.amazon.device.simplesignin.BroadcastHandler" >
    <intent-filter>
        <action android:name="com.amazon.simplesignin.NOTIFY" android:permission="com.amazon.simplesignin.Permission.NOTIFY" />
    </intent-filter>
</receiver>

手順2： 具象実装を登録する

アプリの初期化中に、メインアクティビティクラスから、ISimpleSignInServiceResponseHandlerの具象実装のインスタンスをSimpleSignInServiceに登録します。

@Override
protected void onCreate(Bundle savedInstanceState) {

  final ISimpleSignInResponseHandler responseHandler = new ResponseHandlerImpl();
  SimpleSignInService.registerResponseHandler(getApplicationContext(), responseHandler);
}

手順3： サインインフローを変更してシンプルサインインを有効にする

ユーザーがアプリ内でサインインフローに移ったら、getUserAndLinks()を呼び出して、シンプルサインインを有効にするために使用できるリンク済みアカウントがないか確認します。

• リンク済みアカウントが見つからない場合は、標準のサインインフローにフォールバックします。
• リンク済みアカウントが見つかった場合は、showLoginSelection()を呼び出してSSIログイン画面を表示し、サインインに使用するアカウントの選択をユーザーに求めます。

ユーザーが手動で認証情報を入力してサインインした場合は、サインインの成功時に次の処理を実行します。

• recordMetricEvent()リクエストを送信して、SSIイベント MANUAL_SIGNIN_SELECTEDを記録します。
• linkUserAccount()リクエストを送信して、アカウントのリンクに関する同意をユーザーに求め、リンクプロセスを開始します。

ユーザーが手動で認証情報を入力せず、リンクトークンを使用してサインインした場合は、次の処理を実行します。

• サインインに成功した場合は、recordMetricEvent()リクエストを送信して、SSIイベント LOGIN_SUCCESSを記録します。
• リンクトークンを使用したサインインに失敗した場合は、recordMetricEvent()リクエストを送信してSSIイベント LOGIN_FAILUREを記録し、標準のサインインフローにフォールバックします。

ユーザーが新しいアカウントにサインアップした場合は、サインアップの成功時に、linkUserAccount()リクエストを送信して、アカウントのリンクに関する同意をユーザーに求め、リンクプロセスを開始します。

クライアントAPIの詳細については、SSIクライアントAPIを参照してください。

手順4： アプリのアップグレードシナリオを処理する

シンプルサインインの追加前にアプリにサインインしたユーザーに対しては、シンプルサインインをサポートする最新バージョンのアプリにアップグレードする際に、アカウントをリンクするためのオプションを提供します。アップグレード後のアプリの初回起動時に、ログイン済みユーザーのリンクトークンを生成し、linkUserAccount()を呼び出してアカウントのリンクを設定します。これを実装するには、以下のガイダンスを参照してください。

実装に関するガイダンス

Amazonアプリストアでは、アプリの起動時にアカウントリンクを設定するフローを推奨していますが、好みに応じて実装することもできます。たとえば、アプリの起動時にアカウントリンクのダイアログを表示するのではなく、ユーザーがアプリのアカウント設定ページに移動してから表示しても構いません。ユーザーが既にシンプルサインインの使用に同意している場合は、SSIへの同意画面が再び表示されないようにしてください。

これは、アプリで共有設定を使用するなど、永続的なステートプロパティを2つローカルに保持し、それらに基づいて条件付きロジックを使用することで実装できます。

• プロパティ#1： （データ型： ブール型）ユーザーがアプリにサインイン済みかどうかを示します。ほとんどの場合、ログインステータスは、デバイスにキャッシュされたデータ（認証トークンやユーザー設定など）に基づいて推測することができます。新しいステート変数を導入して追跡する必要はありません。
• プロパティ#2： （データ型： ブール型）現在サインインしているユーザーに対して、アプリのユーザーアカウントをAmazonアカウントにリンクするオプションが既に提示されたかどうかを示します。
  • 値がTRUEの場合、ユーザーが同意したかどうかにかかわらず、SSIへの同意ダイアログが表示されたことを意味します。
  • 値がnullまたはFALSEの場合、SSIへの同意ダイアログがまだ表示されていないことを示します。

たとえば、上記の2つのプロパティの名前がそれぞれloginStatusとssiConsentStatusであるとすると、ロジックは次のようになります。

if (loginStatus == Boolean.TRUE && ssiConsentStatus != Boolean.TRUE) {
  /*
  ログイン済みのユーザーに、アカウントをSSIにリンクするオプションが
  提示されたことはありません。ログイン時にデバイス／アプリで
  SSI機能が利用できなかったか、ログイン時にユーザーが
  SSI機能をオフにしたかのどちらかです。
  */

  // アカウントリンクフローを開始します。

  /*
  手順：

  1. getUserAndLinks APIを呼び出して、AmazonアカウントのdirectedAmazonUserIdを取得します。
  2. getUserAndLinksのresultStatusがSUCCESSFULである場合にのみ、次の手順に進みます。
  3. バックエンドサーバーを呼び出してlinkTokenを生成します。
  4. linkUserAccount APIを呼び出してアカウントリンクを設定します。
  5. linkUserAccount APIレスポンスで返されたresultStatusに基づいて
  ssiConsentStatusプロパティを更新します。
  5a. resultStatusがSUCCESSFULの場合は、ssiConsentStatusをTRUEに設定します。
  */
}

ユーザーがアプリをインストールしたとき、初期状態ではssiConsentStatusフィールドは設定されていません（デフォルトのFALSEになります）。ユーザーがサインインまたはサインアウトしたら、ssiConsentStatusフィールドを次のように更新する必要があります。

ユーザーがサインインした場合：

• ユーザーが手動でアプリにサインインし、linkUserAccount()が呼び出されてSSIのユーザー同意ダイアログが表示された場合、linkUserAccount()からのレスポンスに応じてssiConsentStatusが更新される可能性があります。resultStatusがSUCCESSFULの場合、ssiConsentStatusをTRUEに更新する必要があります。
• ユーザーが以前にリンクされたアカウントを使用してSSIにサインインした場合、SSIのアカウントリンクへの同意を再度求める必要はありません。したがって、ssiConsentStatusをTRUEに設定する必要があります。

ユーザーがサインアウトした場合：

• ユーザーがログアウトするとき、SSIにリンクされたアカウントがある場合は、次のどの動作を希望するかをユーザーに確認します。
  • アプリからサインアウトするとともに、デバイスでシンプルサインイン機能からサインアウトする。
  • アプリからサインアウトするが、シンプルサインインは今後のサインインに備えてそのままにする。
  • アカウントでシンプルサインインが使用されているアプリのすべてのインスタンスからサインアウトする。
• 基本動作は1つ目の選択肢（アプリからサインアウトするとともに、デバイスでシンプルサインイン機能からサインアウトする）です。
• ユーザーがアプリからサインアウトしたら、ssiConsentStatusフィールドをリセットする必要があります。リセットするには、プロパティを削除するか、値をFALSEに設定します。

シンプルサインインの統合のテスト

Amazonアプリストアに公開する前に、アプリでシンプルサインインの動作をテストするには、App Tester APKをテストデバイスにインストールし、アプリをサンドボックスモードで実行します。詳細については、App Testerを使用してアプリをテストする方法を参照してください。

次のステップ： バックエンドで必要な変更

Last updated: 2024年5月6日