4. Inicializar el SDK de NFC Wallet

Inicializar el SDK de NFC Wallet

Inicialice el SDK de NFC Wallet antes de llamar a cualquier otra API del SDK.

Flujo recomendado:

1. Agregue los archivos de propiedades requeridos.
2. Compile un CustomConfiguration.
3. (Opcional) Llame a SDKInitializer.INSTANCE.configure(...) durante el inicio de la aplicación.
4. Llamar a SDKInitializer.INSTANCE.initialize(...) en un hilo en segundo plano.
5. Llamar a MobileGatewayManager.INSTANCE.configure(...) para configurar Mobile Gateway (MG).

Comprobar la versión de Android

Verifique que la versión de Android cumpla con los requisitos mínimos del SDK de Android de NFC Wallet antes de inicializar el SDK.

Ocultar las funciones de NFC Wallet para versiones de Android no compatibles.

Agregar los archivos de propiedades requeridos

Cree los siguientes archivos en su Android aplicación de cartera digital assets carpeta:

• mobilegateway.properties
• rages.properties
• gemcbp.properties

Establezca los valores proporcionados por Thales (a menos que un valor esté explícitamente marcado como fijo a continuación).

mobilegateway.properties

Descripción de mobilegateway.properties

Clave	Descripción
MG_CONNECTION_URL	[String] URL del servidor MG (proporcionada por Thales).
MG_TRANSACTION_HISTORY_CONNECTION_URL	[String] URL para recuperar el historial de transacciones (proporcionada por Thales).
WALLET_PROVIDER_ID	[String] ID del proveedor de billetera.
WALLET_APPLICATION_ID	[String] ID de la aplicación del proveedor de billetera (Opcional). Requerido cuando el proveedor de billetera admite varias aplicaciones de billetera.
MG_CONNECTION_TIMEOUT	[Integer] Tiempo de espera de conexión en milisegundos. Recomendado: 30000.
MG_CONNECTION_READ_TIMEOUT	[Integer] Tiempo de espera de lectura en milisegundos. Recomendado: 30000.
MG_RETRY_COUNTER	[Integer] Número de reintentos. Recomendado: 3.
MG_RETRY_INTERVAL	[Integer] Intervalo en milisegundos entre reintentos. Recomendado: 10000.

rages.properties

Descripción de rages.properties

Clave	Descripción
REALM	[String] Valor fijo: CBP.
OAUTH_CONSUMER_KEY	[String] Clave de consumidor OAuth (proporcionada por Thales).
RAGES_GATEWAY_URL	[String] URL de la pasarela RAGES (proporcionada por Thales).
RAGES_CONNECTION_TIMEOUT	[Integer] Tiempo de espera de conexión en milisegundos. Recomendado: 30000.
CSR_DOMAIN	[String] Dominio usado en la solicitud de firma de certificado (CSR) para HTTPS. Solicite el valor al equipo de entrega de Thales.
CSR_EMAIL	[String] Dirección de correo electrónico de la empresa.

gemcbp.properties

Descripción de gemcbp.properties

Clave	Descripción
CPS_URL	[String] URL de CPS (proporcionada por Thales).
CPS_CONNECTION_TIMEOUT	[Integer] Tiempo de espera de conexión en milisegundos. Recomendado: 30000.
CPS_READ_TIMEOUT	[Integer] Tiempo de espera de lectura en milisegundos. Recomendado: 30000.

Configurar el comportamiento de pago

CustomConfiguration define el comportamiento de pago:

• keyValidityPeriod: Tiempo (en segundos) entre la autenticación del usuario final y el toque en el terminal POS. Rango: 0–300. Predeterminado: 45.
• domesticCurrencyCode: código de moneda numérico ISO 4217 usado para CDCVM durante pagos LVT (Transacción de bajo valor). Predeterminado: 978 (EUR).

CustomConfiguration admite parámetros adicionales de gestión de riesgos y CDCVM. Consulte Definir la gestión de riesgos.

Recomendamos revisar estos parámetros al implementar el pago sin contacto.

El SDK usa CustomConfiguration durante la inicialización.

/* Inicializar el SDK con valores distintos de los predeterminados */
CustomConfiguration customConfig = new CustomConfiguration.Builder()
                .domesticCurrencyCode(978)
                .keyValidityPeriod(60)
                .build();

No cambie keyValidityPeriod y domesticCurrencyCode después de la primera inicialización.

Los cambios pueden introducir retrasos y problemas intermitentes entre la autenticación y el toque final en el terminal POS.

Ejecutar la configuración rápida del SDK (opcional)

Use SDKInitializer.INSTANCE.configure(...) para precargar el Android Context, CustomConfiguration, y las bibliotecas nativas.

Después de configure(...), puede llamar a las APIs que solo leen el almacenamiento local del SDK.

Consulte Requisitos de la API del SDK para obtener más detalles.

configure() no ejecuta la migración del SDK. Si se requiere migración, se ejecuta durante initialize().

MyApp.java

public class MyApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        try {
            // 1. Compile su CustomConfiguration (ver arriba).
            ...

            // 2. Ejecute la configuración rápida para asegurarse de que el SDK tenga un Android Context.
            SDKInitializer.INSTANCE.configure(this, customConfig);
        } catch (InternalComponentException e) {
            // Puede registrar el error y continuar con initialize().
        } catch (Exception e) {
            // Medida de seguridad contra fallos durante el inicio de Application.
            // Puede registrar el error y continuar con initialize().
        } catch (Throwable e) {
            // Esto es poco probable.
            // Si ocurre, no llame a initialize().
            return;
        }

        // 3. Inicialice el SDK de forma asíncrona para que el inicio de Application no se bloquee.
        // Consulte "Inicializar el SDK (pago)" más abajo.
    }
}

Inicializar el SDK (pago)

Compruebe el estado del SDK usando SDKController.getInstance().getSDKServiceState() e inicialice solo cuando sea necesario.

Use SDKInitializer.INSTANCE.initialize(...) para inicializar los componentes de pago:

• Proporcione CustomConfiguration como parámetro de entrada.
• Esta API es síncrona. Llámela desde un hilo en segundo plano.

Inicializar el SDK de NFC Wallet (Java)

final Context appContext = getApplicationContext();

if (SDKController.getInstance().getSDKServiceState() != SDKServiceState.STATE_INITIALIZED) {
    Thread sdkInit = new Thread(new Runnable() {
        @Override
        public void run() {
            SDKInitializer.INSTANCE.initialize(appContext, customConfig);
        }
    });
    sdkInit.start();
}

Las APIs de inicialización son idempotentes. Puede llamarlas varias veces de forma segura.

Configurar Mobile Gateway (MG)

Después de que se complete la inicialización del SDK, llame a MobileGatewayManager.INSTANCE.configure(...) para habilitar la tokenización, la LCM de la tarjeta digital y el historial de transacciones.

Use MobileGatewayManager.INSTANCE.getConfigurationState() para comprobar el estado de la configuración.

Configurar Mobile Gateway (Java)

protected void initMgSdk(@NonNull final Context context) {
    final MobileGatewayManager mgManager = MobileGatewayManager.INSTANCE;

    try {
        // Evite múltiples inicializaciones.
        if (mgManager.getConfigurationState() == MGSDKConfigurationState.NOT_CONFIGURED) {
            mgManager.configure(context);
        }
    } catch (final MGConfigurationException exception) {
        // Registrar error.
    }
}

Obtener el ID de la billetera

Use getWalletId() de MGCardEnrollmentService para recuperar el identificador de la billetera.

Obtener el ID de la billetera (Java)

MGCardEnrollmentService enrollService = MobileGatewayManager.INSTANCE.getCardEnrollmentService();
String walletId = enrollService.getWalletId();

MGSDKException se lanza si ocurre un error al recuperar el ID de la billetera.

Use el ID de la billetera para resolución de problemas y soporte.

El SDK genera el ID de la billetera la primera vez que inicializa el SDK:

• El ID de la billetera permanece estable entre reinicios de la aplicación.
• Si restablece el SDK, el ID de la billetera se vuelve a generar.