> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Android アプリにログイン機能を追加する

<div id="get-started">
  ## はじめに
</div>

<Steps>
  <Step title="新しい Android プロジェクトを作成" stepNumber={1}>
    このクイックスタート用に新しい Android プロジェクトを作成します。

    **Android Studio で:**

    1. **File** → **New** → **New Project**
    2. **Phone and Tablet** → **Empty Activity** テンプレートを選択します
    3. プロジェクトを次のように設定します:
       * **Name**: `Auth0-Android-Sample`
       * **Package name**: `com.auth0.samples.android`
       * **Language**: **Kotlin**
       * **Minimum SDK**: **API 24 (Android 7.0)**
       * **Build configuration language**: **Kotlin DSL**
    4. **Finish** をクリックします

    <Tip>
      これにより、Kotlin と Gradle Kotlin DSL を使用し、最新の Android 開発のベストプラクティスに従ったモダンな Android アプリが作成されます。
    </Tip>
  </Step>

  <Step title="Gradle を使って Auth0 ソフトウェア開発キット (SDK) を追加する" stepNumber={2}>
    Gradle を使って、Auth0 Android ソフトウェア開発キット (SDK) をプロジェクトに追加します。

    **アプリレベルの `build.gradle.kts` ファイルを更新します：**

    ```kotlin app/build.gradle.kts lines theme={null}
    dependencies {   
        // Auth0 SDK
        implementation("com.auth0.android:auth0:3.11.0")
    }
    ```

    **`AndroidManifest.xml` にインターネット権限を追加する:**

    ```xml app/src/main/AndroidManifest.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools">
        <uses-permission android:name="android.permission.INTERNET" />
    </manifest>
    ```

    <Tip>
      Auth0 ソフトウェア開発キット (SDK) は依存関係の解決を自動的に行い、安全なトークン保存機能を提供します。
    </Tip>
  </Step>

  <Step title="Auth0 アプリケーションのセットアップ" stepNumber={3}>
    次に、Auth0 テナントに新しいアプリケーションを作成し、その設定を Android プロジェクトに追加します。

    まず、プレースホルダー値を使って `app/src/main/res/values/strings.xml` ファイルを用意します。

    ```xml app/src/main/res/values/strings.xml theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <string name="com_auth0_domain">{yourDomain}</string>
        <string name="com_auth0_client_id">YOUR_AUTH0_CLIENT_ID</string>
        <string name="com_auth0_scheme">https</string>
    </resources>
    ```

    1. [Auth0 Dashboard](https://manage.auth0.com/dashboard/) にアクセスします
    2. **Applications** > **Applications** > **Create Application** をクリックします
    3. ポップアップでアプリ名を入力し、アプリ タイプとして `Native` を選択して **Create** をクリックします
    4. Application Details ページの **Settings** タブに切り替えます
    5. `strings.xml` ファイル内の `{yourDomain}` と `YOUR_AUTH0_CLIENT_ID` を、ダッシュボードの **Domain** と **Client ID** の値に置き換えます

    最後に、Application Details ページの **Settings** タブで、次の URL を設定します。

    **Allowed Callback URLs:**

    ```
    https://{yourDomain}/android/PACKAGE_NAME/callback
    ```

    **許可されたログアウトURL：**

    ```
    https://{yourDomain}/android/PACKAGE_NAME/callback
    ```

    `{yourDomain}` を実際の Auth0 ドメイン（例: `dev-abc123.us.auth0.com`）に置き換えてください。

    <Info>
      **許可されたコールバックURL** は、認証後にユーザーを安全にアプリケーションへ戻すための重要なセキュリティ対策です。一致するURLがない場合、ログイン処理は失敗し、ユーザーはアプリにアクセスできず Auth0 のエラーページでブロックされます。

      **許可されたログアウトURL** は、サインアウト時にシームレスなユーザー体験を提供するために不可欠です。一致するURLがない場合、ユーザーはログアウト後にアプリケーションへリダイレクトされず、一般的な Auth0 ページに留まることになります。

      URLスキームには、コールバックが特定のアプリにルーティングされるように、パッケージ名（`com.auth0.samples.android`）が含まれます。
    </Info>

    <Warning>
      **重要**: コールバックURL内のパッケージ名が、`build.gradle.kts` の `applicationId` と一致していることを確認してください。認証が失敗する場合は、これらの値が同一であることを確認してください。
    </Warning>
  </Step>

  <Step title="Auth0 ソフトウェア開発キット (SDK) の初期化" stepNumber={4}>
    Auth0 と通信するために、Activity で Auth0 インスタンスを作成してください。

    **`MainActivity.kt` で:**

    ```kotlin MainActivity.kt lines theme={null}
    import com.auth0.android.Auth0
    import com.auth0.android.authentication.AuthenticationException
    import com.auth0.android.callback.Callback
    import com.auth0.android.provider.WebAuthProvider
    import com.auth0.android.result.Credentials

    class MainActivity : ComponentActivity() {
        private lateinit var auth0: Auth0

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            
            // Auth0 を初期化
            auth0 = Auth0.getInstance(
                getString(R.string.com_auth0_client_id),
                getString(R.string.com_auth0_domain)
            )
        }
    }
    ```

    <Tip>
      Auth0 インスタンスは、前の手順で設定した `strings.xml` ファイル内のクライアントIDとドメインを使って初期化されます。このインスタンスは、すべての認証処理に使用されます。
    </Tip>
  </Step>

  <Step title="ログイン／ログアウトを実装する" stepNumber={5}>
    **ログインを実装する:** WebAuthProvider を使用して Universal Login ページを起動します。

    次のメソッドを `MainActivity` に追加します:

    <Tabs>
      <Tab title="Kotlin コールバック">
        ```kotlin MainActivity.kt lines theme={null}
        private fun login() {
            WebAuthProvider.login(auth0)
                .withScheme("https")
                .withScope("openid profile email offline_access")
                .start(this, object : Callback<Credentials, AuthenticationException> {
                    override fun onSuccess(credentials: Credentials) {
                        // 資格情報を保存する
                        // ユーザーが認証された
                    }

                    override fun onFailure(exception: AuthenticationException) {
                        // エラーを処理する
                    }
                })
        }
        ```
      </Tab>

      <Tab title="コルーチン">
        ```kotlin MainActivity.kt lines theme={null}
        private fun login() {
            lifecycleScope.launch {
                try {
                    val credentials = WebAuthProvider.login(auth0)
                        .withScheme("https")
                        .withScope("openid profile email offline_access")
                        .await(this@MainActivity)
                    // 資格情報を保存する
                    // ユーザーが認証された
                } catch (exception: AuthenticationException) {
                    // エラーを処理する
                }
            }
        }
        ```
      </Tab>
    </Tabs>

    **ログアウトを実装する:** WebAuthProvider を使用してユーザーのセッションをクリアします。

    <Tabs>
      <Tab title="Kotlin コールバック">
        ```kotlin MainActivity.kt lines theme={null}
        private fun logout() {
            WebAuthProvider.logout(auth0)
                .withScheme("https")
                .start(this, object : Callback<Void?, AuthenticationException> {
                    override fun onSuccess(result: Void?) {
                        // 保存済みの資格情報をクリアする
                        // ユーザーがログアウトした
                    }

                    override fun onFailure(exception: AuthenticationException) {
                        // エラーを処理する
                    }
                })
        }
        ```
      </Tab>

      <Tab title="コルーチン">
        ```kotlin MainActivity.kt lines theme={null}
        private fun logout() {
            lifecycleScope.launch {
                try {
                    WebAuthProvider.logout(auth0)
                        .withScheme("https")
                        .await(this@MainActivity)
                    // 保存済みの資格情報をクリアする
                    // ユーザーがログアウトした
                } catch (exception: AuthenticationException) {
                    // エラーを処理する
                }
            }
        }
        ```
      </Tab>
    </Tabs>

    <Info>
      `login()` と `logout()` メソッドは、ユーザーが UI のそれぞれのボタンをタップしたときに呼び出す必要があります。コードでは、WebAuthProvider が Chrome Custom Tabs を起動し、認証フローを処理するために必要となるコンテキスト引数として `this`（Activity を参照）を使用しています。
    </Info>
  </Step>

  <Step title="アプリを実行する" stepNumber={6}>
    Android アプリケーションをビルドして実行します。

    **Android Studio の場合:**

    ```shellscript theme={null}
    # Gradleファイルとプロジェクトを同期(またはAndroid Studioの「今すぐ同期」を使用)
    ./gradlew clean build

    # 接続されたデバイスまたはエミュレーターでビルドしてインストール
    ./gradlew installDebug

    # またはAndroid Studioから直接実行
    # 「実行」ボタンをクリックするか、Shift+F10を押す
    ```

    **想定されるフロー:**

    1. アプリが起動し、「Log In」ボタンとシールドアイコンが表示される
    2. 「Log In」をタップ → Chrome Custom Tab が開く → ログインを完了する
    3. 自動的にアプリに戻る
    4. 成功!!

    <Warning>
      複数のブラウザがインストールされている場合、Android はブラウザ選択ダイアログを表示します。Chrome Custom Tabs を使用すると、Auth0 認証において最適なユーザーエクスペリエンスを提供できます。
    </Warning>
  </Step>
</Steps>

<Check>
  **チェックポイント**

  ここまでの手順で、Android デバイスまたはエミュレーター上で Auth0 のログインエクスペリエンスが問題なく動作しているはずです。アプリでは安全な認証のために Chrome Custom Tabs を使用し、認証情報を自動的に保存します。
</Check>

***

<div id="troubleshooting-advanced">
  ## トラブルシューティング & 高度な設定
</div>

<Accordion title="一般的な問題と解決策">
  ### Chrome Custom Tab がアプリにリダイレクトされない

  **解決策:**

  1. Auth0 Dashboard で **Allowed Callback URLs** が `applicationId` と完全に一致していることを確認してください
  2. `build.gradle.kts` 内のマニフェストプレースホルダーが正しいことを確認してください
  3. HTTPS とカスタムスキームの両方の URL が構成されていることを確認してください
  4. クリーン & 再ビルド: **Build** → **Clean Project** → **Rebuild Project**

  ### アプリがクラッシュする: 'Auth0 domain not found'

  **対処方法:**

  1. `com_auth0_domain` と `com_auth0_client_id` の値が正しいことを確認してください
  2. ドメイン形式にタイプミスがないことを確認してください（`https://` を含めないでください）

  ### 依存関係に関連するビルドエラー

  **対処方法:**

  1. `build.gradle`（プロジェクトレベル）で Android Gradle Plugin を最新バージョンに更新してください
  2. プロジェクトを同期してください: **File** → **Sync Project with Gradle Files**
  3. クリーンビルドを実行してください: `./gradlew clean build`

  ### ユーザーによって認証がキャンセルされる

  エラーコールバック内で適切に処理してください:

  ```kotlin {3,4,5,6} expandable theme={null}
  override fun onFailure(exception: AuthenticationException) {
      when {
          exception.isAuthenticationCanceled -> 
              showMessage("Login was cancelled")
          exception.isBrowserAppNotAvailable -> 
              showMessage("No browser available")
          else -> 
              showMessage("Login failed: ${exception.getDescription()}")
      }
  }
  ```

  ### 互換性のあるブラウザがないというエラー

  * デバイス／エミュレータに Chrome などの最新のブラウザをインストールしてください
  * より良いユーザー体験のために Chrome Custom Tabs を有効にしてください
  * Chrome がインストールされた実機デバイスでテストしてください
</Accordion>

<Accordion title="本番デプロイ">
  ### ストア公開前の準備

  * シームレスな認証のために Android App Links を構成してください
  * 複数の Android バージョンと画面サイズでテストしてください
  * ネットワーク障害に対する適切なエラー処理を実装してください
  * コード難読化を使用している場合は Auth0 ソフトウェア開発キット (SDK) 用の ProGuard ルールを追加してください
  * 認証フローに関する Google Play Store のポリシーに従ってください

  ### セキュリティ上の考慮事項

  * 本番環境の認証情報ストレージには `SecureCredentialsManager` を使用してください
  * 追加の API セキュリティのために証明書ピンニングを実装してください
  * 強化された認証情報保護のために Android Keystore の利用を検討してください
  * 機微な操作には生体認証を有効にしてください
</Accordion>

<Accordion title="高度な Android 統合">
  ### 認証情報のセキュリティ強化

  認証情報へのアクセスに生体認証を次のように実装します:

  ```kotlin AuthenticationManager.kt expandable lines theme={null}
  class AuthenticationManager(private val context: Context) {
      
      private val credentialsManager: SecureCredentialsManager
      
      init {
          val authentication = AuthenticationAPIClient(auth0)
          val storage = SharedPreferencesStorage(context)
          credentialsManager = SecureCredentialsManager(context, authentication, storage)
          
          // 生体認証を有効にする
          credentialsManager.requireAuthentication(
              context as FragmentActivity,
              REQUEST_CODE_BIOMETRIC,
              "Biometric Authentication",
              "Please authenticate to access your account"
          )
      }
      
      companion object {
          private const val REQUEST_CODE_BIOMETRIC = 321
      }
  }
  ```

  ### カスタムスコープとオーディエンス

  API 用に特定のスコープとオーディエンスを要求します:

  ```kotlin AuthenticationManager.kt expandable lines theme={null}
  fun login() {
      WebAuthProvider.login(auth0)
          .withScheme("https")
          .withScope("openid profile email offline_access read:posts")
          .withAudience("https://myapi.example.com")
          .withParameter("prompt", "login")
          .start(context as MainActivity, loginCallback)
  }
  ```

  ### ネットワーク構成

  ネットワークセキュリティと証明書ピンニングを設定します:

  ```xml app/src/main/res/xml/network_security_config.xml expandable lines theme={null}
  <?xml version="1.0" encoding="utf-8"?>
  <network-security-config>
      <domain-config>
          <domain includeSubdomains="true">your-auth0-domain.auth0.com</domain>
          <pin-set>
              <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
          </pin-set>
      </domain-config>
  </network-security-config>
  ```

  `AndroidManifest.xml` に次を追加します:

  ```xml theme={null}
  <application
      android:networkSecurityConfig="@xml/network_security_config"
      ... />
  ```
</Accordion>