Connettere un lettore

Assicurati che il lettore sia acceso e connesso con un cavo USB 2.0 al dispositivo che esegue l’app e che sia stata concessa l’autorizzazione per accedere al lettore connesso tramite USB.

Se stai collegando il lettore per la prima volta, viene visualizzato un messaggio del sistema Android per connetterti al lettore. Puoi selezionare la casella di controllo “Sempre aperta” per aprire la tua app senza chiedere quando è connessa a un lettore.

Quindi, dall’app, cerca il lettore connesso con il metodo discoverReaders, utilizzando UsbDiscoveryConfiguration.

class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {
    // ...

    var discoverCancelable: Cancelable? = null

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

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

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

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

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

    // ...
}

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

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

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

val connectionConfig = UsbConnectionConfiguration(
    
"{{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
        }
    }
)

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 il cavo USB che lo collega al dispositivo è scollegato. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

Il MobileReaderListener include il callback onDisconnect 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 MobileReaderListener.
2. Specifica il MobileReaderListener in UsbConnectionConfiguration.
3. Quando l’SDK invia onReaderReconnectStarted 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 onReaderReconnectSucceeded, visualizza un messaggio che annuncia che la connessione è stata ripristinata e di continuare le normali operazioni.
5. Se l’SDK non è in grado di riconnettersi al lettore e invia sia onReaderReconnectFailed che onDisconnect, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

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
    }

    // ...
}

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.

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

    override fun onDisconnect(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.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
        }
    }
)

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 SharedPreferences (Android).

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 MobileReaderListener dell’integrazione riceve un onStartInstallingUpdate 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 ConnectionStatus.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 MobileReaderListener con onFinishInstallingUpdate. 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 Android è 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.

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
    }

    // ...
}

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 avvisa degli aggiornamenti facoltativi tramite MobileReaderListener ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, il MobileReaderListener dell’applicazione riceve il callback onReportAvailableUpdate con l’oggetto ReaderSoftwareUpdate contenente i dettagli dell’aggiornamento, tra cui:

• Tempo stimato per il completamento dell’aggiornamento (durationEstimate)
• Data a partire dalla 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 onReportAvailableUpdate, chiama Terminal.getInstance().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 chiedi all’utente di mantenere connesso il lettore fino al completamento dell’aggiornamento. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. Il MobileReaderListener segnala lo stato di avanzamento dell’aggiornamento nel metodo onReportReaderSoftwareUpdateProgress.

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

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

    // ...
}

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.