# Quick start

This guide provides step-by-step instructions to integrate the NFC SDK into your Android project using locally downloaded AAR files instead of remote dependencies. Follow these steps carefully to ensure a successful integration.

## Before you begin

Ensure that the following requirements are met:

-   The latest stable version of Android Studio
-   Minimum target API level 19 (KitKat)
-   Android Compile SDK Version 34 with Android Build Tools 34.0.0
-   Gradle 7.4 or later
-   A physical Android device or emulator for testing
-   The following AAR files provided by your Alipay+ Solution Architect:

-   _tap-payment-1.x.xx.8000.aar_
-   _tap-payment-ui-1.x.xx.8000.aar_

## **Step 1****:** **Add the SDK to your project**

### **1.1 Add the AAR File to Your Project**

1.  **Locate or create the** **_libs_** **directory**:

-   Locate the _libs_ directory in the root folder of your app module, typically at _app/_.
-   If the _libs_ directory doesn't exist, create a new folder named _libs_ within the _app/_ directory.

2.  **Copy the AAR file**:

-   Copy the downloaded _tap-payment-1.x.xx.8000.aar_ and _tap-payment-ui-1.x.xx.8000.aar_ file into the _app/libs/_ directory.
-   Double-check to ensure that the filenames are correct, including the version numbers.

### **1.2 Update Your Gradle Configuration**

1.  Open the _app/build.gradle_ file in your code editor, and add the `flatDir` repository. Include the _libs_ directory as a local repository by adding the following code block inside the `android` or `repositories` section:

```groovy
repositories {
    flatDir {
        dirs 'libs'  // Points to the libs folder
    }
}
```

#### Sample:

```groovy
android {
    // ... other configurations (for example, compileSdk, buildToolsVersion)
}

repositories {
    flatDir { dirs 'libs' }  // Add this line
}

dependencies {
    // ... dependencies
}
```

2.  Declare the AAR dependency: Replace the remote SDK dependency with the local AAR file in the `dependencies` block:

```plaintext
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])  // Add this line
    // ... other dependencies
}
```

### **1.3 Add other required dependency**

Add the required Fastjson dependency with the following code:

```groovy
fast-json = { group = "com.alibaba", name = "fastjson", version.ref = "fast-json-version"}
fast-json-version = "1.1.76.android_noneautotype"

implementation(libs.fast.json)
implementation 'com.airbnb.android:lottie:6.6.7'

```

### **1.4 Sync and Build**

In Android Studio, click **Sync Now** to apply the changes.

## Step 2: Initialize the Alipay+ NFC SDK

### 2.1 Initialize the SDK

Before enabling NFC payments, call the **init** API to initialize the SDK:

```java
public class BaseApplication extends Application {
    APNFCConfig.Builder builder = new APNFCConfig.Builder()
    .setNeedConfirmActivate(true)
    .setAuthType(NFCAuthMode.FLEXIBLE_WITHOUT_UPPER_AMOUNT)
    .setShowCoreLog(BuildConfig.DEBUG)
    .setSupportLockScreenPay(false);

    ACTapManager.getInstance().init(config);
}
```

The initialization requires the _APNFCConfig_ parameter to handle transaction event notifications such as authentication expiration, transaction start, and transaction result. For detailed configuration options of _APNFCConfig_, see the [**init**](init.md) API.

### 2.2 **Define the HCE Service in** **_AndroidManifest.xml_**

1.  Add the following XML snippet to your app's _AndroidManifest.xml_. This declares your custom HCE service, configures its behavior, and specifies the Application Identifiers (AIDs) it supports:

```xml
<service
  android:name=".MyNFCHCEService"
  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/apdu_service_config" />
</service>
```

2.  Create a new XML file _res/xml/apdu\_service\_config.xml_ to define the metadata of your HCE service:

```xml
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
  android:apduServiceBanner="@drawable/your_service_banner"
  android:description="@string/your_service_description"
  android:requireDeviceUnlock="false">

  <aid-group
    android:category="payment"
    android:description="@string/your_aid_group_description">
     <aid-filter android:name="325041592E5359532E4444463031" />
     <aid-filter android:name="A0000000041010"/>
  </aid-group>

</host-apdu-service>
```

Key attributes in the metadata**:**

-   `android:apduServiceBanner`: A drawable resource (for example, _@drawable/your\_service\_banner_) displayed in NFC payment selection UIs. For example: A 120 x 40 dp logo representing your wallet app.
-   `android:description`: A string resource (for example, _@string/your\_service\_description_) describing your service. For example, _Tap & Pay with AlipayPlus NFC_.
-   `android:requireDeviceUnlock`: Set to `true` if the device must be unlocked to use the service. It is recommended to set to `true` for the payment services.

### 2.3 Implement the HCE Service Class

Create a class (for example, `MyNFCHCEService`) that extends `HostApduService` to handle APDU commands from the NFC readers:

```java
import android.os.Bundle;
import android.util.Log;
import androidx.annotation.NonNull;
import android.nfc.cardemulation.HostApduService;
import com.iap.android.nfc.ACTapManager;
import com.iap.android.nfc.core.apdu.utils.ApduByteArray;

public class IAPNFCHostApduService extends HostApduService {
    @Override
    public void onCreate() {
        super.onCreate();
        ACTapManager.getInstance(getApplication()).connect("UID", null);
    }

    @Override
    public byte[] processCommandApdu(byte[] commandApdu, Bundle extras) {
        Log.d("HCE_TEST", "received: " + ApduByteArray.of(commandApdu).toHexString());
        byte[] ret = ACTapManager.getInstance(getApplication()).processApduCommands(commandApdu);
        Log.d("HCE_TEST", "return : " + ApduByteArray.of(ret).toHexString());
        return ret;
    }

    @Override
    public void onDeactivated(int reason) {
        ACTapManager.getInstance(getApplication()).transactionDeactivate();
    }

}

```