Registrar la cartera

Resumen

Inscriba la aplicación de billetera digital después de NFC Wallet SDK la inicialización y antes de comenzar Tokenización.

La inscripción de la billetera aprovisiona a la aplicación de billetera digital con los activos de seguridad necesarios para usar NFC Wallet servicios:

• Ejecute esto una vez por instancia de billetera.
• Ejecute esto solo si la aplicación de billetera digital usa NFC Wallet servicios.
• Ejecute esto solo en dispositivos elegibles.

Inscriba solo las aplicaciones de billetera digital que usan NFC Wallet servicios.

Esto evita tráfico de red innecesario de la aplicación de billetera digital y carga innecesaria en NFC Wallet.

Diagrama de secuencia

Flujo general para inscribir su aplicación de billetera.

Flujo general de inscripción de la billetera.

Este flujo se denomina técnicamente inscripción segura de la billetera en NFC Wallet.

Integración del SDK

Requisitos previos

Antes de comenzar, verifique lo siguiente:

• Su aplicación de billetera digital está incorporada en el backend de NFC Wallet.
• Ha inicializado el NFC Wallet SDK.
• La billetera no está inscrita (véase abajo).

Realice la inscripción de la billetera

La inscripción de la billetera es una acción única en el ciclo de vida de la aplicación de billetera digital.

Ejecútela después de la inicialización del SDK, y solo si la billetera no está inscrita.

1. Obtenga un WalletSecureEnrollmentBusinessService instancia.
2. Compruebe getState() devuelve WSE_REQUIRED.
3. Si es necesario, llame a startWalletSecureEnrollment() para iniciar la inscripción de la billetera.
4. Implemente WalletSecureEnrollmentListener para seguir el progreso.

Estas son las devoluciones de llamada posibles:

• onProgressUpdate con el estado WSE_STARTED: El proceso comienza.
• onProgressUpdate con el estado WSE_COMPLETED: El proceso finaliza correctamente.
• onError: El proceso falla con un error.

Después de que la inscripción de la billetera se complete correctamente, continúe con Tokenizar una tarjeta.

public void performWseIfNeeded() {
    // Primero compruebe el estado actual. Si necesitamos WSE en absoluto.
    final WalletSecureEnrollmentBusinessService wseService 
                = ProvisioningServiceManager.getWalletSecureEnrollmentBusinessService();
    final WalletSecureEnrollmentState state = wseService.getState();

    switch (state) {
        case WSE_COMPLETED:
        case WSE_NOT_REQUIRED:
            // WSE ya se había realizado en la instancia actual o en alguna instancia anterior.
            break;
        case WSE_STARTED:
            // WSE se activó durante esta instancia. Simplemente espere a que termine la primera.
            return;
        case WSE_REQUIRED:
            // Active la inscripción de WS.
            wseService.startWalletSecureEnrollment(new WalletSecureEnrollmentListener() {
                @Override
                public void onProgressUpdate(final WalletSecureEnrollmentState wseState) {
                    if (wseState == WalletSecureEnrollmentState.WSE_COMPLETED) {
                        // Éxito
                    }
                    else if (wseState == WalletSecureEnrollmentState.WSE_STARTED) {
                        // Iniciado
                    }
                }

                @Override
                public void onError(final WalletSecureEnrollmentError wbDynamicKeyRenewalServiceError) {
                    // Registrar error
                }
            });
            break;
        default:
            // Registre el error, ya que no debería ocurrir
            break;
    }
}   

Detalles del código de error

Cuando WalletSecureEnrollmentListener.onError(...) se activa, el SDK proporciona un WalletSecureEnrollmentError.

Incluye un código de error y un mensaje, además de campos adicionales según el tipo de fallo.

Analice WalletSecureEnrollmentError

La estructura del WalletSecureEnrollmentError objeto es la siguiente:

• Código de error del SDK: el tipo de error para esta operación.
• Código de error de CPS: el código de error numérico devuelto por el módulo CPS (lado del servidor).
• Código de estado HTTP: el código de estado HTTP devuelto para errores de comunicación.
• Mensaje: una descripción del error legible por humanos.

El error debe analizarse de la siguiente manera:

1. Leer getSdkErrorCode() para obtener un WalletSecureEnrollmentErrorCodes valor.
2. Si el código de error del SDK indica un error de comunicación (COMM_ERROR), lea getHttpStatusCode().
3. Si el código de error del SDK indica un error del lado del servidor (SERVER_ERROR), lea getCpsErrorCode().
4. Leer getErrorMessage() para una descripción adecuada para los registros.
5. Si el código de error del SDK es DEVICE_SUSPICIOUS, lea getStatusAdditionalInfo() y regístrelo para la resolución de problemas.

Consulte WalletSecureEnrollmentErrorCodes en la API de Android documentación de referencia para la lista completa de códigos.

WalletSecureEnrollmentErrorCodes

Utilice las siguientes recomendaciones para decidir si reintentar, detener o restablecer el SDK.

Llamar a SDKDataController.wipeAll() cuando la recomendación sea restablecer el SDK.

Tablas de códigos de error

Código de error	Cuándo ocurre	Acción recomendada
WSE_INTERNAL_ERROR	Se produce un error interno del SDK.	Reintente la inscripción de la billetera. Si el problema persiste, restablezca el SDK.
COMMON_NO_INTERNET	El dispositivo no tiene conectividad de red.	Pida al usuario final que se conecte a una red y luego reintente la inscripción de la billetera.
COMMON_COMM_ERROR	Se produce un error de comunicación al recuperar los activos de seguridad.	Reintente la inscripción de la billetera.
COMMON_SERVER_ERROR	Se produce un error del lado del servidor al recuperar los activos de seguridad.	Reintente la inscripción de la billetera. Si el problema persiste, póngase en contacto con el equipo de entrega de Thales para validar la configuración del entorno.
RE_ENROLLMENT_REQUIRED	Se requiere reinscripción por motivos de seguridad.	Restablezca el SDK y luego ejecute de nuevo la inscripción de la billetera.
WSE_STORAGE_ACCESS_ERROR	El SDK supera su límite interno de reintentos al acceder al almacenamiento seguro.	Restablezca el SDK y luego reintente la inscripción de la billetera.
JSON_PARSING_ERROR	Los datos de respuesta no se pueden analizar.	Reintente la inscripción de la billetera. Si el problema persiste, restablezca el SDK.
WSE_REQUEST_ERROR	La solicitud de inscripción falla.	Reintente la inscripción de la billetera.
WSE_DOWNLOAD_ERROR	La descarga de los activos de seguridad falla.	Verifique la conectividad de red y luego reintente la inscripción de la billetera.
WSE_ERROR_INIT_SESSION	La inicialización de la sesión WSE falla (normalmente relacionada con la autenticación).	Reintente la inscripción de la billetera.
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_PACKAGE_NOT_FOUND	El SDK no puede calcular el valor de autenticación porque no se puede resolver el nombre del paquete.	Verifique el nombre del paquete de la aplicación usado en su configuración de incorporación y luego reintente la inscripción de la billetera.
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_CERT_EXCEPTION	El SDK no puede calcular el valor de autenticación debido a un problema con la firma de la aplicación o la clave pública.	Verifique el certificado de firma de la aplicación usado en su configuración de incorporación y luego reintente la inscripción de la billetera.
WSE_CPS_COMPONENT_NOT_INITIALIZED	La inscripción de la billetera comienza antes de que se inicialice el componente CPS.	Inicialice el SDK y luego reintente la inscripción de la billetera.
WSE_MG_COMPONENT_NOT_INITIALIZED	La inscripción de la billetera comienza antes de que se inicialice el componente MobileGateway.	Inicialice el SDK y luego reintente la inscripción de la billetera.
DEVICE_SUSPICIOUS	El SDK detecta una amenaza de seguridad en el dispositivo.	Detenga el flujo e informe al usuario final de que el dispositivo no se puede usar. Capture y comparta getStatusAdditionalInfo() al contactar con el soporte de Thales.
WSE_KCV_ERROR	El SDK no puede validar los activos de seguridad descargados (la comprobación KCV falla).	Reintente la inscripción de la billetera.

Clave de vinculación de la aplicación (notas)

Como se describe en incorporación debe proporcionar la clave de vinculación de la aplicación.

Si no se proporciona la clave de vinculación de la aplicación o es incorrecta, la inscripción de la billetera fallará.

Revise la advertencia y la nota siguientes.

Rotación de la clave de firma / Múltiples firmantes

Si la clave de firma más antigua no se proporciona como el primer valor del firmante en la estructura proof-of-rotation, la inscripción de la billetera fallará

Degradación a versiones anteriores de NFC Wallet SDK

Para degradar a una versión anterior de NFC Wallet SDK, la aplicación debe asegurarse de que la clave de firma más antigua se proporcione como el primer firmante en la estructura proof-of-rotation.