Inicio rápido: Tu primera inicialización

Antes de poder procesar cualquier pago, tu app cliente debe inicializar la app Tap on Phone. Esta inicialización establece una sesión segura, activa la validación de Single Sign-On (SSO) con tu backend y prepara el terminal.

Normalmente, se realiza esta inicialización una vez cuando el usuario inicia sesión en tu app. La sesión permanece activa entre los inicios de la app y los reinicios del dispositivo hasta que se restablece (reset) explícitamente.

Este tutorial te guiará en la creación del intent InitActivity, el paso de los parámetros necesarios y la gestión del resultado.

Prerrequisitos

Antes de empezar, asegúrate de que tienes:

• Tu Client ID, Merchant ID, User ID y User Token. (Puedes utilizar los valores de prueba del entorno de pruebas proporcionados en la guía Requisitos Previos y Configuración).
• Has configurado tu backend para gestionar las solicitudes de SSO, tal como se describe en Integración Backend: Gestión de Solicitudes de SSO.
• Has integrado las APIs Activity Result de AndroidX en tu proyecto Android.

Paso 1: Preparar los metadatos de la operación

Para enrutar correctamente la solicitud de SSO a tu backend, debes pasar tu Client ID en el extra operationMetadata. Este campo requiere una cadena JSON válida.

Formatea tu Client ID como una cadena JSON en tu código:

// Replace with your actual Client ID or the sandbox test value
val operationMetadata = "{\"ClientID\":\"your-client-id-here\"}"

Paso 2: Registrar el Activity Result Launcher

Para gestionar la respuesta de la app Tap on Phone, registra un callback de Activity Result. Este callback escucha la finalización del proceso de inicialización.

val posInitResult = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // Initialization successful. The POS is ready to process payments.
        println("SoftPOS Initialization completed successfully.")
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        // Initialization failed. Extract the error details.
        val data = result.data
        val errorCode = data?.getStringExtra("errorCode") ?: "None"
        val errorName = data?.getStringExtra("errorName") ?: "None"
        val errorMessage = data?.getStringExtra("errorMessage") ?: "None"

        println("Initialization failed: $errorName ($errorCode) - $errorMessage")
        // Manage the error and display options to your user
    }
}

Paso 3: Iniciar el Intent InitActivity

Construye un Android Intent dirigido a la InitActivity de la app Tap on Phone. Debes incluir el package name, el class name y todos los extras obligatorios.

Crea una función para construir e iniciar el intent:

private fun startPosInit(userId: Int, merchantId: Int, userToken: String, operationMetadata: String) {
    val intent = Intent().apply {
        // Specify the Tap on Phone package and the InitActivity class
        setClassName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.InitActivity"
        )

        // Add the mandatory extras
        putExtra("userId", userId)
        putExtra("merchantId", merchantId)
        putExtra("userToken", userToken)
        putExtra("operationMetadata", operationMetadata)
    }

    // Launch the intent using the registered callback
    posInitResult.launch(intent)
}

Paso 4: Ejecutar y verificar

Llama a tu función startPosInit utilizando tus credenciales del entorno de pruebas.

Si la validación de SSO tiene éxito y el dispositivo supera las comprobaciones de seguridad iniciales, el callback recibe RESULT_OK. Tu app ya está lista para procesar transacciones.

Si recibes RESULT_CANCELED, comprueba el errorCode y el errorMessage devueltos. Los problemas comunes durante la inicialización incluyen timeouts de red, Client IDs incorrectos o respuestas no autorizadas de tu backend de SSO.

Próximos pasos

Ahora que has inicializado correctamente la app Tap on Phone, puedes explorar los conceptos principales o pasar directamente al procesamiento de pagos.

• Comprende la Arquitectura.
• Aprende cómo Procesar una Transacción de Compra.