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

# Android Setup

> Configure your Android project to support NFC tap-to-pay with the TapRails SDK.

## Requirements

* `minSdkVersion` **23** or higher
* Android device with NFC hardware

***

## 1. App-Level build.gradle

Open `android/app/build.gradle` and add the following inside the `android {}` block and under `dependencies`:

```gradle android/app/build.gradle theme={null}
android {
    defaultConfig {
        minSdkVersion 23       // Required for Keychain & NFC APIs
        // ...
    }
}

dependencies {
    // Required by react-native-keychain v8
    implementation "androidx.datastore:datastore-core:1.0.0"
    implementation "androidx.datastore:datastore-preferences:1.0.0"
    implementation "androidx.datastore:datastore-preferences-core:1.0.0"

    // Fix Kotlin stdlib version conflicts
    configurations.all {
        resolutionStrategy {
            force "org.jetbrains.kotlin:kotlin-stdlib:1.8.0"
            force "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.8.0"
            force "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.0"
        }
    }
}
```

***

## 2. Project-Level build.gradle

Open `android/build.gradle` and ensure Kotlin is configured in the `buildscript` block:

```gradle android/build.gradle theme={null}
buildscript {
    ext {
        kotlinVersion = "1.8.0"
    }
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
    }
}
```

***

## 3. AndroidManifest.xml — Permissions & HCE Service

Open `android/app/src/main/AndroidManifest.xml` and add the NFC permissions **and the HCE card service**:

```xml android/app/src/main/AndroidManifest.xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

  <!-- NFC Permissions -->
  <uses-permission android:name="android.permission.NFC" />
  <uses-feature android:name="android.hardware.nfc" android:required="true" />
  <uses-feature android:name="android.hardware.nfc.hce" android:required="true" />

  <application ...>

    <!-- TapRails HCE Service (merchant NFC emulation) -->
    <service
      android:name="com.taprails.hce.TapRailsHCEService"
      android:exported="true"
      android:enabled="true"
      android:permission="android.permission.BIND_NFC_SERVICE">
      <intent-filter>
        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
        <category android:name="android.intent.category.DEFAULT"/>
      </intent-filter>
      <meta-data
        android:name="android.nfc.cardemulation.host_apdu_service"
        android:resource="@xml/aid_list" />
    </service>

  </application>
</manifest>
```

<Note>
  `android:enabled="true"` is required. The HCE session lifecycle (on/off) is managed internally by the SDK's JS bridge. The service itself must be enabled in the manifest for the Android OS to discover it.
</Note>

***

## 4. AID List XML

Create the file `android/app/src/main/res/xml/aid_list.xml` (create the `xml/` directory if it doesn't exist):

```xml android/app/src/main/res/xml/aid_list.xml theme={null}
<host-apdu-service
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:description="@string/app_name"
  android:requireDeviceUnlock="true">
  <aid-group android:category="other" android:description="@string/app_name">
    <!-- REPLACE WITH YOUR DASHBOARD-ASSIGNED AID -->
    <aid-filter android:name="YOUR_UNIQUE_AID" />
  </aid-group>
</host-apdu-service>
```

This AID (Application Identifier) tells the Android NFC stack which APDU service to route incoming NFC requests to — specifically the TapRails HCE emulation service.

***

## 5. Verify

Build and run your Android app:

```bash theme={null}
npm run android
# or
react-native run-android
```

The app should launch without build errors. To confirm NFC is working, proceed to the [Get Started](/get-started) and run the merchant flow on an Android device.

<Check>
  **All done on Android!** No additional linking is required — React Native's autolinking handles the native module registration.
</Check>