Conectarse a un lector

Para empezar, asegúrate de que el lector esté encendido y cerca de él.

Luego, desde tu aplicación, busca lectores cercanos conectados a Bluetooth con el método discoverReaders, usando BluetoothDiscoveryConfiguration.

class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {

    var discoverCancelable: Cancelable? = null

    // ...

    // Action for a "Discover Readers" button
    fun discoverReadersAction() {
        val timeout = 0
        val isSimulated = false

        val config = BluetoothDiscoveryConfiguration(
            timeout = timeout,
            isSimulated = isSimulated
        )

        discoverCancelable = Terminal.getInstance().discoverReaders(
            config,
            this,
            object : Callback {
                override fun onSuccess() {
                    // Placeholder for handling successful operation
                }

                override fun onFailure(e: TerminalException) {
                    // Placeholder for handling exception
                }
            }
        )
    }

    // DiscoveryListener
    override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Escaneo Bluetooth

El escaneo Bluetooth busca todos los lectores cercanos y devuelve a tu aplicación una lista de lectores detectados. A medida que continúa el proceso de detección, el SDK sigue invocando el método onUpdateDiscoveredReaders con la última lista de lectores cercanos.

Durante el proceso de detección, el connectionStatus del Terminal pasa a ConnectionStatus.DISCOVERING mientras el descubrimiento está en curso.

Con el método de detección de escaneo Bluetooth, puedes establecer un tiempo de espera para escanear durante un período de tiempo determinado, que puedes usar para gestionar la vida útil de la batería o activar un mensaje de error si no se encuentran dispositivos.

En tu aplicación móvil, te recomendamos mostrar una lista de actualización automática de los lectores detectados, con números de serie o etiquetas para ayudar a los usuarios a identificar sus lectores.

Para conectarte a un lector detectado, llama al método connectReader desde tu aplicación.

Debes registrar tu lector en una ubicación tras la conexión. Para hacerlo, crea y utiliza una BluetoothConnectionConfiguration con el locationId establecido en el ID de ubicación relevante al conectarte.

// Implement your MobileReaderListener
val mobileReaderListener = yourMobileReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val connectionConfig = BluetoothConnectionConfiguration(
    
"{{LOCATION_ID}}",
    autoReconnectOnUnexpectedDisconnect,
    mobileReaderListener
)

Terminal.getInstance().connectReader(
    selectedReader,
    connectionConfig,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Gestiona las desconexiones del lector

A veces pueden producirse desconexiones del lector entre tu aplicación y el lector. Por ejemplo, el lector puede desconectarse de la aplicación si , está fuera de rango o se queda sin batería. Para simular una desconexión inesperada durante las pruebas, puedes apagar el lector.

El MobileReaderListener incluye una devolución de llamada onDisconnect que proporciona a tu aplicación el DisconnectReason para ayudar a identificar por qué se desconectó el lector.

Cuando un lector se desconecta, intentamos reconectarlo automáticamente de forma predeterminada y te recomendamos que muestres notificaciones en tu aplicación que retransmitan el estado del lector durante todo el proceso.

Para mostrar notificaciones en tu aplicación durante la reconexión automática, haz lo siguiente:

1. Implementa las devoluciones de llamada de reconexión del lector en el MobileReaderListener.
2. Transfiere el MobileReaderListener a tu BluetoothConnectionConfiguration.
3. Cuando el SDK envía onReaderReconnectStarted a tu aplicación, muestra un mensaje anunciando que el lector ha perdido la conexión y que la reconexión está en curso.
   • Puedes usar el objeto Cancelable para detener el intento de reconexión en cualquier momento.
4. Cuando el SDK indique una reconexión exitosa enviando onReaderReconnectSucceeded, muestra un mensaje anunciando que la conexión se ha restaurado y que se reanudará el funcionamiento con normalidad.
5. Si el SDK no puede volver a conectarse al lector y envía tanto onReaderReconnectFailed como onDisconnect, muestra un mensaje que indique que se ha producido una desconexión inesperada.

class CustomMobileReaderListener : MobileReaderListener {
    // ...

    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }

    // ...
}

Para gestionar las desconexiones del lector, puedes hacer lo siguiente:

1. Establece autoReconnectOnUnexpectedDisconnect en false durante la conexión.
2. Gestiona la devolución de llamada de desconexión para mostrar un mensaje en la aplicación que alerte al usuario de que el lector se ha desconectado inesperadamente, y que se inicia la detección y conexión del lector.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

Reinicia el lector conectado

Stripe Reader M2 y BBPOS WisePad 3 se reinician automáticamente después de 24 horas de funcionamiento. Sin embargo, puedes forzar al lector a que se reinicie y restablezca su temporizador de 24 horas con la API rebootReader. Después de esta acción, el lector se desconecta del SDK y se reinicia. Si estás utilizando la reconexión automática, el SDK intenta restaurar la conexión con el lector.

Terminal.getInstance().rebootReader(
    object : Callback {
        override fun onSuccess() {
            // Reboot succeeded and the reader will disconnect.
            // If your app is using automatic reconnect the reconnect will begin.
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Reconexión automática al iniciar la aplicación

Stripe Terminal no se vuelve a conectar automáticamente a un lector cuando se inicia la aplicación. En su lugar, puedes crear un flujo de reconexión almacenando los ID del lector e intentando conectarte a un lector conocido al iniciarse.

1. Cuando te conectes a un lector de forma satisfactoria, guarda su número de serie en una ubicación de almacenamiento persistente de datos, como la API Shared Preferences (Android).

1. Cuando se inicie la aplicación, comprueba si hay un número de serie guardado en la ubicación de almacenamiento persistente de datos. Si se encuentra uno, llama al método discoverReaders para que tu aplicación pueda intentar encontrar ese lector nuevamente.
2. Si el número de serie guardado coincide con cualquiera de los lectores detectados, intenta conectarte a ese lector con el objeto de lector coincidente devuelto de la llamada a discoverReaders. Si no se encuentra el lector previamente conectado, detén el proceso de detección.

Muestra alguna interfaz de usuario durante el proceso de detección y conexión para indicar que se está produciendo una reconexión automática.

Tu aplicación debe actualizar los lectores móviles para aplicar lo siguiente:

• Configuraciones regionales que te mantienen al día respecto a los requisitos de la red de tarjetas y del emisor
• Actualizaciones de seguridad

Las actualizaciones necesarias comienzan a instalarse cuando te conectas al lector. No puedes usar el lector hasta que se complete la actualización.

Actualizaciones necesarias

Cuando las actualizaciones urgentes están disponibles para el lector, el MobileReaderListener de la integración recibe onStartInstallingUpdate con un ReaderSoftwareUpdate.

El ReaderSoftwareUpdate proporciona los detalles necesarios de la actualización, incluida una estimación de la duración total de la actualización, indicada por durationEstimate.

Durante el proceso de instalación, el connectionStatus del Terminal pasa a ConnectionStatus.CONNECTING mientras la actualización se instala en el lector.

Tu aplicación debe avisar a los usuarios de que se está instalando una actualización y mostrar el progreso en tu interfaz de usuario. Deja claro por qué la conexión puede tardar más de lo habitual.

Si falla el proceso de la actualización necesaria, Stripe comunica el error al MobileReaderListener con onFinishInstallingUpdate. No puedes volver a conectarte al lector después de que falle la actualización requerida, a menos que se cumplan las siguientes condiciones:

• El lector ejecuta la última versión del software disponible para la ubicación en los últimos 30 días.
• La versión del SDK de Android es mayor o igual a 3.5.0.

Si se cumplen las condiciones, el proceso de conexión se realiza correctamente a pesar de una actualización incompleta. Stripe volverá a intentar realizar la actualización necesaria la próxima vez que te conectes a ese lector hasta que se instale correctamente.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onStartInstallingUpdate(update: ReaderSoftwareUpdate, cancelable: Cancelable) {
        // Show UI communicating that a required update has started installing
    }

    override fun onReportReaderSoftwareUpdateProgress(progress: Float) {
        // Update the progress of the installation
    }

    override fun onFinishInstallingUpdate(update: ReaderSoftwareUpdate?, e: TerminalException?) {
        // Report success or failure of the update
    }

    // ...
}

Puedes cancelar las actualizaciones obligatorias utilizando el objeto Cancelable, que también provoca un fallo en la conexión con el lector. No puedes cancelar actualizaciones solo incrementales.

Actualizaciones opcionales

Puedes aplazar las actualizaciones opcionales hasta la fecha especificada, después de la cual serán obligatorias. El SDK te avisa de las actualizaciones opcionales a través del MobileReaderListener en cualquier momento en que el lector esté conectado pero no realizando una transacción. Si está disponible una actualización opcional, el MobileReaderListener de tu aplicación recibe la devolución de llamada onReportAvailableUpdate con el objeto ReaderSoftwareUpdate que contiene los detalles de la actualización, incluyendo:

• Tiempo estimado para que se complete la actualización (durationEstimate)
• Fecha a partir de la cual se requiere la actualización (requiredAt)

En tu aplicación, notifica a los usuarios que hay una actualización disponible y muestra un mensaje para continuar opcionalmente con la actualización.

Para proceder a la actualización previamente informada con onReportAvailableUpdate, llama a Terminal.getInstance().installAvailableUpdate.

La actualización disponible también se almacena en el objeto lector como reader.availableUpdate.

A medida que avanza la actualización, bloquea al usuario para que no abandone la página en tu aplicación e indícale que debe mantener el lector dentro del alcance y encendido hasta que se complete la actualización. Recomendamos también que le proporciones a tu usuario un indicador visual del progreso de la actualización. El MobileReaderListener informa del progreso de la actualización en el método onReportReaderSoftwareUpdateProgress.

Cuando haya pasado la fecha requiredAt de una actualización opcional, la actualización se instalará la próxima vez que se conecte el lector.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onReportAvailableUpdate(update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.getInstance().installAvailableUpdate`.
    }

    // ...
}

Para obtener más información sobre cómo asegurarse de que la aplicación gestiona los diferentes tipos de actualizaciones que puede tener un lector, consulta Prueba de actualizaciones del lector.