Connettere un lettore

Per iniziare, accertati che il lettore sia acceso e nelle immediate vicinanze.

Quindi, dall’app, cerca i lettori connessi via Bluetooth nelle vicinanze con il metodo discoverReaders , utilizzando 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.
    }
}

Prossimità Bluetooth * BBPOS Chipper 2X BT only

I risultati di ricerca dei filtri di prossimità Bluetooth restituiscono il lettore più vicino. Una volta individuato, sul lettore lampeggiano luci multicolori per consentire all’utente di identificare il lettore individuato tra molti altri lettori. Dopo che l’SDK ha individuato un lettore, non passa a un lettore più vicino a meno che il lettore individuato non si spenga.

Quando utilizzi la prossimità Bluetooth, l’SDK restituisce due volte il lettore al callback dell’app. La prima volta, l’app riceve un oggetto Reader popolato solo con il numero di serie del lettore. Dopo un breve ritardo, l’app riceve lo stesso oggetto Reader popolato con nuove informazioni, ad esempio il livello della batteria del lettore.

Consigliamo di visualizzare il lettore individuato nell’interfaccia utente dell’app, per consentire all’utente di confermare la connessione al lettore o di annullarla se non vuole connettersi a questo lettore.

Scansione Bluetooth

La scansione Bluetooth cerca tutti i lettori nelle vicinanze e restituisce all’app un elenco dei lettori individuati. Mentre è in corso la scansione, l’SDK continua a chiamare il metodo DiscoveryDelegate.didUpdateDiscoveredReaders con l’elenco più recente dei lettori nelle vicinanze.

Durante il processo di individuazione, lo stato SCPConnectionStatus di Terminal passa a SCPConnectionStatus.SCPConnectionStatusDiscovering mentre è in corso l’individuazione.

Con il metodo di rilevamento tramite scansione Bluetooth, puoi impostare un timeout per eseguire la scansione per un determinato periodo di tempo. In questo modo puoi gestire la durata della batteria o attivare un messaggio di errore se non vengono trovati dispositivi.

Nella tua applicazione mobile, ti consigliamo di mostrare un elenco dei lettori individuati che si aggiorna automaticamente, con numeri di serie o etichette per aiutare gli utenti a identificare il loro lettore.

Per connetterti a un lettore individuato, chiama il metodo connectReader dall’app.

Devi registrare il lettore in una posizione al momento della connessione. A tal scopo, durante la connessione, crea e utilizza una BluetoothConnectionConfiguration con locationId impostato sull’ID posizione pertinente.

// 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)")
    }
}

Affinché la tua app venga eseguita in background e rimanga connessa al lettore, configurala per includere la modalità di background richiesta.

Gestire le disconnessioni del lettore

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dalla tua app se è fuori portata o esaurisce la batteria. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

Il MobileReaderDelegate include un metodo reader:didDisconnect: che fornisce all’applicazione il DisconnectReason per consentire di identificare il motivo della disconnessione del lettore.

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Implementa i callback di riconnessione del lettore in MobileReaderDelegate.
2. Specifica il MobileReaderDelegate in BluetoothConnectionConfiguration.
3. Quando l’SDK invia reader:didStartReconnect:disconnectReason: alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   • Puoi utilizzare l’oggetto Cancelable per interrompere il tentativo di riconnessione in qualsiasi momento.
4. Quando l’SDK indica l’avvenuta riconnessione inviando readerDidSucceedReconnect:, visualizza un messaggio che annuncia che la connessione è stata ripristinata e di continuare le normali operazioni.
5. Se l’SDK non riesce a riconnettersi al lettore e invia sia readerDidFailReconnect: chereader:didDisconnect:, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

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
    }
}

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta autoReconnectOnUnexpectedDisconnect su false durante la connessione.
2. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

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
    }
}

Riavviare il lettore connesso

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API rebootReader. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

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

Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’API UserDefaults (iOS).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo discoverReaders in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
2. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a discoverReaders. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

• Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
• Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, il MobileReaderDelegate dell’integrazione riceve il callback didStartInstallingUpdate con un ReaderSoftwareUpdate.

Il ReaderSoftwareUpdate fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da durationEstimate.

Durante la procedura di installazione, lo stato connectionStatusdi Terminal diventa connecting mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore a MobileReaderDelegate con didFinishInstallingUpdate. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

• Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
• La versione dell’SDK iOS è successiva o uguale alla 3.5.0.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

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
    }

    // ...
}

Puoi annullare gli aggiornamenti obbligatori utilizzando l’oggetto Cancelable, che determina la mancata connessione del lettore. Non puoi annullare gli aggiornamenti solo incrementali.

Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti notifica gli aggiornamenti facoltativi tramite MobileReaderDelegate ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, il MobileReaderDelegate dell’applicazione riceve il callback didReportAvailableUpdate con l’oggetto ReaderSoftwareUpdate contenente i dettagli dell’aggiornamento, tra cui:

• Tempo stimato per il completamento dell’aggiornamento (durationEstimate)
• Timestamp dopo il quale l’aggiornamento diventa obbligatorio (requiredAt)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con didReportAvailableUpdate, chiama Terminal.shared.installAvailableUpdate.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come reader.availableUpdate.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedigli di tenere il lettore a portata di mano e acceso fino al completamento dell’operazione. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. MobileReaderDelegate segnala lo stato di avanzamento dell’aggiornamento nel metodo didReportReaderSoftwareUpdateProgress.

Se la data requiredAt di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

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`.
    }

}

Consulta Testare gli aggiornamenti del lettore Bluetooth per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.