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:

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

Sample:

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:

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:

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:

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 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:

<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:

<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:

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();
    }
    
}