3. Consider application start

Overview

When your application starts, initialize the NFC Wallet SDK.

Also set the payment experience your digital wallet application supports:

• Support single-tap payments.
• Or require two-tap payments.

Even if you enable single-tap, some transactions can fall back to two-tap. See Single-tap can fall back to two-tap.

Payment application in background

When the digital wallet application is the default payment application (see Default payment app), Android may keep it in the background. This lets it respond quickly to contactless payment APDUs from the POS terminal without recreating the Application.

Some devices terminate the default payment application while it is in the background. On these devices, contactless payments can trigger an application cold start. See Optimize cold starts.

SDK integration

Update application startup

In Application.onCreate(), your application must:

1. Run SDK quick configuration.
2. Set the expected payment experience:

   • ONE_TAP_ENABLED to support single-tap transactions
   • TWO_TAP_ALWAYS to always require authentication after the first tap (always two-tap payments)
3. Initialize the SDK in a separate thread.
4. Optional: after initialization succeeds, activate pre-entry. See Activate pre-entry.

For steps 1 and 2, see Initialize the NFC Wallet SDK.

MyApp.java

public class MyApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        
        // Build custom config with no value change (same config since the first SDK init)
        CustomConfiguration customConfig = new CustomConfiguration.Builder()
                .domesticCurrencyCode(978)
                .keyValidityPeriod(60)
                .build();
        
        // 1 - Run quick configuration
        // ... to make sure SDK has the 'Context'
        try {
            SDKInitializer.INSTANCE.configure(this,  customConfig);
        } catch (InternalComponentException e){
            // SDK internal component exception
            // App can ignore this, 
            // and proceed with the actual SDK initialization API and perform the error handling there if Exception is raised
        } catch (Exception e) {
            // Generic exception, this is a safeguard as to prevent any event 
            // that could lead to a crash durign Application startup. 
            // App can ignore this, and proceed with the actual SDK initialization API and perform the error handling there if Exception is raised
        } catch (Throwable e) {
            // this is unlikely to happen, however because this piece of code resides in Application class,
            // in oder to minimized the impact of any error that could implact on the whole application, 
            // we recommend to catch this error. 
            // In case of this error, app shall NOT call SDKInitializer.INSTANCE.initialize()
        }
    
        // 2 - Set the payment experience.
        PaymentExperienceSettings.setPaymentExperience(this, PaymentExperience.ONE_TAP_ENABLED);
        
        // 3 - Initialize the SDK (in separate thread)
        Thread sdkInit = new Thread(new Runnable() {
            @Override
            public void run() {
                SDKInitializer.INSTANCE.initialize(this, customConfig);
            }
        });
        sdkInit.start();
        
        // 4 - Activate pre-entry (optional).
        activatePreEntry();
    }
    
    // Activate pre-entry.
    private void activatePreEntry() {
        final DeviceCVMPreEntryReceiver receiver = new DeviceCVMPreEntryReceiver();
        receiver.init();
        final IntentFilter filter = new IntentFilter(Intent.ACTION_USER_PRESENT);
        registerReceiver(receiver, filter);
    }
    
    

}

Single-tap can fall back to two-tap

If you enable ONE_TAP_ENABLED, not every transaction is performed as single-tap.

Treat single-tap as the best-case flow. If the required conditions are not met, NFC Wallet SDK falls back to two-tap.

Examples:

• The end user does not tap within the configured validity period after unlocking the device. See keyValidityPeriod in Initialize the NFC Wallet SDK.
• An LVT transaction without authentication reaches a configured risk threshold. In that case, NFC Wallet SDK requires authentication. See Define risk management.

Reduce cold start time

Some devices terminate the default payment application while it is in the background. On these devices, a contactless payment can trigger an application cold start.

APDU processing starts immediately after the cold start.

The cold start process includes:

• Service binding (around 100–200 milliseconds)
• Completion of Application.onCreate()

Minimize work in Application.onCreate(). Limit it to NFC Wallet SDK configuration and initialization.

Avoid other operations in the first 0.5 seconds after Application.onCreate() starts. Parallel work can delay APDU handling when Android sends APDU commands to the POS terminal.

If needed, delay non-payment work by at least 0.5 seconds after SDK initialization completes.

Activate pre-entry

Use pre-entry to support single-tap payments.

Pre-entry lets the end user authenticate before the payment flow starts.

Authentication happens when the end user unlocks the device with biometrics or device keyguard (PIN, pattern, or password). This enables a payment without an additional verification step.

Only one payment is allowed per device unlock when this mode is enabled.

private void activatePreEntry() {
    DeviceCVMPreEntryReceiver receiver = new DeviceCVMPreEntryReceiver();
    receiver.init();
    IntentFilter filter = new IntentFilter(Intent.ACTION_USER_PRESENT);
    registerReceiver(receiver, filter);
}

Do not add additional intent filters with DeviceCVMPreEntryReceiver. This class is designed to act only on the ACTION_USER_PRESENT intent.