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 BluetoothScanDiscoveryConfiguration.

import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try BluetoothScanDiscoveryConfigurationBuilder().build()
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Proximidad Bluetooth * BBPOS Chipper 2X BT only

La proximidad de Bluetooth filtros los resultados de búsqueda para mostrar el lector más cercano. Cuando se detecta, el lector parpadea con luces multicolores, lo que permite al usuario identificar al lector detectado entre muchos otros lectores. Después de que el SDK detecte un lector, no cambiará a un lector más cercano a menos que apagues el lector detectado.

Ten en cuenta que, cuando se utiliza la proximidad Bluetooth, el SDK devuelve el lector a la devolución de llamada de la aplicación dos veces. La primera vez, la aplicación recibe un objeto Reader rellenado solo con el número de serie del lector. Después de un breve retraso, tu aplicación recibe el mismo objeto Reader rellenado con nueva información, como el nivel de batería del lector.

Recomendamos mostrar el lector detectado en la interfaz de usuario, lo que permite al usuario confirmar la conexión con el lector o cancelarla si no quiere conectarse a este lector.

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 DiscoveryDelegate.didUpdateDiscoveredReaders con la última lista de lectores cercanos.

Durante el proceso de detección, el SCPConnectionStatus del Terminal pasa a SCPConnectionStatus.SCPConnectionStatusDiscovering mientras la detección 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.

// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: 
"{{LOCATION_ID}}")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

Para que tu aplicación se ejecute en segundo plano y permanezca conectada al lector, configúrala para incluir el modo de segundo plano requerido.

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 MobileReaderDelegate incluye un método reader:didDisconnect: 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 MobileReaderDelegate.
2. Pasa el MobileReaderDelegate a tu BluetoothConnectionConfiguration.
3. Cuando el SDK envíe reader:didStartReconnect:disconnectReason: a tu aplicación, muestra un mensaje que anuncie 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 realizada correctamente enviando readerDidSucceedReconnect:, muestra un mensaje anunciando que la conexión se ha restablecido y que se reanudarán las operaciones normales.
5. Si el SDK no puede volver a conectarse al lector y envía tanto readerDidFailReconnect: y reader:didDisconnect:, muestra un mensaje que indica que se ha producido una desconexión inesperada.

import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ 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.

import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect 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.shared.rebootReader { error in
    if let error = error {
        // Placeholder for handling the error
    } else {
        // Reboot succeeded and the reader will disconnect.
        // If your app is using automatic reconnect the reconnect will begin.
    }
}

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 UserDefaults (iOS).

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 MobileReaderDelegate de la integración recibe la devolución de llamada didStartInstallingUpdate 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 connecting mientras se instala la actualización 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 MobileReaderDelegate con didFinishInstallingUpdate. 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 iOS 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.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // Show UI communicating that a required update has started installing
    }

    func reader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // Update the progress of the installation
    }

    func reader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // 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 MobileReaderDelegate en cualquier momento en que el lector esté conectado pero no realizando una transacción. Si está disponible una actualización opcional, el MobileReaderDelegate de tu aplicación recibe la devolución de llamada didReportAvailableUpdate con el objeto ReaderSoftwareUpdate que contiene los detalles de la actualización, incluyendo:

• Tiempo estimado para que se complete la actualización (durationEstimate)
• Marca de tiempo 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 didReportAvailableUpdate, llama a Terminal.shared.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 MobileReaderDelegate informa del progreso de la actualización en el método didReportReaderSoftwareUpdateProgress.

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.

import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didReportAvailableUpdate update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.shared.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.