Connettere un lettore

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella Dashboard.

Registra per codice di registrazione

1. Nella pagina Lettori, fai clic su Registra lettore.
2. Se hai un Verifone P400, inserisci la sequenza di tasti 0-7-1-3-9 per visualizzare un codice di registrazione univoco. Se hai un BBPOS WisePOS E o Stripe Reader S700, vai alle impostazioni e tocca Genera codice di accoppiamento.
3. Inserisci il codice di registrazione e fai clic su Avanti.
4. Facoltativamente, scegli un nome per il lettore.
5. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su + Aggiungi nuovo.
6. Fai clic su Registra per completare la registrazione del lettore.

Registra per numero di serie

1. Nella pagina Lettori, fai clic su Registra lettore.
2. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
3. Facoltativamente, scegli un nome per il lettore.
4. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su + Aggiungi nuovo.
5. Fai clic su Registra per completare la registrazione del lettore.

Registra per ordine hardware

1. Nella pagina Ordini hardware, trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra () alla fine della riga, poi fai clic su Registra.
2. Nella pagina Registra lettori, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su Registra.
3. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
4. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su + Aggiungi nuovo.
5. Fai clic su Registra per completare la registrazione dei lettori.

Registrare con l’API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per registrare un lettore con l’API Stripe.

1. Se hai un Verifone P400, inserisci la sequenza di tasti 0-7-1-3-9 per visualizzare un codice di registrazione univoco. Se hai un BBPOS WisePOS E o Stripe Reader S700, vai alle impostazioni e tocca Genera codice di accoppiamento.
2. L’utente inserisce il codice nell’applicazione.
3. L’applicazione invia il codice a Stripe:

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

curl https://api.stripe.com/v1/terminal/readers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per connetterti alla tua applicazione POS con discoverReaders utilizzando InternetDiscoveryConfiguration.

Puoi definire l’ambito della tua scoperta utilizzando la location in cui hai registrato il lettore nel passaggio precedente.

import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {
  func discoverReadersAction() throws {
      let config = try InternetDiscoveryConfigurationBuilder()
                          .setLocationId(
"{{LOCATION_ID}}")
                          .build()
      self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
          if let error = error {
              print("discoverReaders failed: \(error)")
          } else {
              print("discoverReaders succeeded")
          }
      }
  }
}

Per l’individuazione dei lettori intelligenti, il metodo DiscoveryDelegate.didUpdateDiscoveredReaders viene chiamato solo una volta per chiamata a discoverReaders. didUpdateDiscoveredReaders restituisce un elenco vuoto di lettori se non sono presenti lettori registrati o lettori associati alla posizione specificata. Se effettui una successiva chiamata discoverReaders per aggiornare l’elenco, devi prima annullare la chiamata precedente con la chiamata Cancelable restituita da discoverReaders.

InternetDiscoveryConfiguration supporta un valore timeout facoltativo per l’individuazione dei lettori online. In questo modo sarà possibile accedere più rapidamente all’individuazione offline dei lettori nel caso in cui il tentativo online non vada a buon fine.

Per connettere l’applicazione POS a un lettore, chiama connectReader con il lettore selezionato utilizzando InternetConnectionConfiguration.

let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: yourInternetReaderDelegate)
        .build()
} catch {
    // Handle error building the connection configuration
    return
}

Terminal.shared.connectReader(selectedReader, connectionConfig: config) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami connectReader da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo connectReader accetta un oggetto di configurazione con una proprietà failIfInUse, il cui valore predefinito è false. Quando l’applicazione imposta failIfInUse su true, la chiamata connectReader ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata collectPaymentMethod o confirmPaymentIntent avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato collectPaymentMethod), l’impostazione failIfInUse non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione SDK-lettore esistente.

let internetReaderDelegate = yourInternetReaderDelegate // implement your internetReaderDelegate

let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: internetReaderDelegate)
          .setFailIfInUse(true)
          .build()
} catch {
    // Handle error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: config, completion: { reader, error in
    // ...
})

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare failIfInUse su true nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con failIfInUse impostato su false se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

Gestire le disconnessioni

La tua app deve implementare il callback reader(_, didDisconnect:) per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare discoverReaders per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

import StripeTerminal

class ReaderViewController: UIViewController, InternetReaderDelegate {
    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
    }
}

Riconnessione automatica

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 correttamente a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati persistente, ad esempio UserDefaults API (iOS)
2. Quando l’app viene avviata, controlla l’archiviazione 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.
3. 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.