Zum Inhalt springen
rdlabo.devdocs

Lebenszyklus des Lesegeräts

Behalten Sie Softwareupdates, Status und Anzeigemeldungen des Lesegeräts unter Kontrolle, damit Terminal-Operationen den Bezahlvorgang nicht unterbrechen.

Auf Softwareupdates hören

Das Lesegerät kann bei Bedarf selbstständig ein Update starten. Hören Sie auf verfügbare Updates, installieren Sie sie oder brechen Sie sie ab und zeigen Sie während einer Installation den Fortschritt an.

Einschränkungen:

  • Rufen Sie setSimulatorConfiguration vor discoverReaders auf, wenn Sie ein simuliertes Update benötigen (SimulateReaderUpdate.UpdateAvailable oder Required). Im Web hat setSimulatorConfiguration keine Wirkung.
  • StartInstallingUpdate, ReaderSoftwareUpdateProgress und FinishInstallingUpdate gelten für Bluetooth- und USB-Lesegeräte. Ein verpflichtendes Update beim ersten Verbinden wird automatisch installiert, vor ConnectedReader und vor der Auflösung von connectReader(). Reihenfolge: StartInstallingUpdate → ReaderSoftwareUpdateProgress (wiederholt) → FinishInstallingUpdate → ConnectedReader → Auflösung von connectReader(). Zeigen Sie den Vorgang in der Oberfläche an, damit eine lange Verbindung nicht für einen Stillstand gehalten wird.
  • ReportAvailableUpdate bedeutet, dass ein optionales Update bereitsteht; rufen Sie installAvailableUpdate auf, wenn der Händler warten kann. Starten Sie während des Bezahlvorgangs keine optionale Installation.
  • progress ist eine Fließkommazahl zwischen 0 und 1.
  • cancelInstallUpdate bricht eine laufende Installation ab, sofern das SDK dies zulässt. Die Webmethoden zum Installieren und Abbrechen haben keine Wirkung.
  • iOS Tap to Pay meldet Start, Fortschritt und Ende der Installation ebenfalls über den Delegaten des Tap-to-Pay-Lesegeräts. Die Android-Tap-to-Pay-Oberfläche ist davon getrennt; siehe Tap to Pay.

method installAvailableUpdate()

Installiert das durch ReportAvailableUpdate gemeldete Softwareupdate.

installAvailableUpdate() => Promise<void>

method cancelInstallUpdate()

Bricht ein laufendes optionales Softwareupdate für das Lesegerät ab.

cancelInstallUpdate() => Promise<void>

method setSimulatorConfiguration(...)

Konfiguriert das im Testmodus verwendete simulierte Lesegerät. Vor dem
Vorgang aufrufen, dessen Verhalten Sie simulieren möchten.

Referenz in der Stripe-Dokumentation

setSimulatorConfiguration(options: SimulatorConfigurationOptions) => Promise<void>

Auf Status und Eingabeaufforderungen hören

Rufen Sie bei Lesegeräten ohne eigenes Display den Akkustand, Ereignisse des Lesegeräts, Anzeigemeldungen und Eingabeaufforderungen über Listener ab und zeigen Sie sie auf dem Mobilgerät an.

BatteryLevel, ReaderEvent, RequestDisplayMessage und RequestReaderInput gelten für Bluetooth- und USB-Lesegeräte. Akkuaktualisierungen werden beim Verbinden und etwa alle 10 Minuten ausgelöst.

Die Anzeige des Lesegeräts festlegen

Zeigen Sie auf Geräten mit eigenem Display den Warenkorbinhalt vor collectPaymentMethod an. Leeren Sie die Anzeige anschließend. Internet-Lesegeräte im Web unterstützen diese Aufrufe.

method setReaderDisplay(...)

Zeigt Warenkorbdaten auf einem Lesegerät mit kundenseitigem Bildschirm an.

setReaderDisplay(options: Cart) => Promise<void>

method clearReaderDisplay()

Löscht die Warenkorbdaten aus der kundenseitigen Anzeige des Lesegeräts.

clearReaderDisplay() => Promise<void>

interface Cart

Cart-Gesamtbeträge, die auf dem kundenseitigen Bildschirm eines Lesegeräts angezeigt werden.

Eigenschaft Typ Beschreibung Seit
currency string Dreibuchstabiger ISO-4217-Währungscode. 6.2.0
tax number Steuerbetrag in der kleinsten Einheit der Währung. 6.2.0
total number Cart-Gesamtbetrag in der kleinsten Einheit der Währung. 6.2.0
lineItems CartLineItem[] Im Warenkorb angezeigte Artikel. 6.2.0

interface CartLineItem

Position, die auf dem kundenseitigen Bildschirm eines Lesegeräts angezeigt wird.

Eigenschaft Typ Beschreibung Seit
displayName string Auf dem Lesegerät angezeigter Artikelname. 6.2.0
quantity number Anzahl der Einheiten im Warenkorb. 6.2.0
amount number Betrag einer Position in der kleinsten Einheit der Währung. 6.2.0

Die Suche abbrechen

Rufen Sie cancelDiscoverReaders auf, wenn der Nutzer den Suchbildschirm verlässt oder ein Timeout eintritt. Bei Erfolg lösen native Plattformen CancelDiscoveredReaders aus. Auch wenn kein Vorgang läuft, wird das Promise aufgelöst.

Die iOS-Bluetooth-Suche kann lange laufen und fortlaufend DiscoveredReaders auslösen. Kombinieren Sie den Abbruch mit bluetoothScanWaitTime oder einem eigenen Timeout. Im Web hat cancelDiscoverReaders keine Wirkung.

method cancelDiscoverReaders()

Bricht die aktive Lesegerätesuche ab.

cancelDiscoverReaders() => Promise<void>

Trennen und Wiederverbinden

disconnectReader trennt das aktuelle Lesegerät. Ist keines verbunden, wird das Promise aufgelöst.

Verhalten von DisconnectedReader:

  • Jeder Lesegerätetyp löst es als Antwort auf disconnectReader() ohne reason aus.
  • Bluetooth und USB lösen es außerdem mit einem reason aus, wenn das Lesegerät vollständig getrennt ist. Eine vom Nutzer veranlasste Trennung führt somit zu zwei Ereignissen: der Bestätigung des Aufrufs und anschließend dem Verbindungsende mit Begründung.

Behandeln Sie ConnectionStatusChange nicht als unerwarteten Verbindungsabbruch. Informieren Sie den Nutzer mit UnexpectedReaderDisconnect. Sie können discoverReaders erneut aufrufen, um die Verbindung wiederherzustellen; bieten Sie immer einen Timeout oder cancelDiscoverReaders an.

Setzen Sie in connectReader für Tap to Pay und Bluetooth autoReconnectOnUnexpectedDisconnect: true, wenn das SDK einen erneuten Versuch unternehmen soll. Hören Sie anschließend auf:

  • ReaderReconnectStarted — enthält reader und reason
  • ReaderReconnectSucceeded
  • ReaderReconnectFailed

cancelReaderReconnection bricht eine laufende Wiederverbindung ab. Im Web haben rebootReader und cancelReaderReconnection keine Wirkung.

method getConnectedReader()

Liefert das aktuell verbundene Lesegerät oder null, wenn keine Verbindung besteht.

getConnectedReader() => Promise<{ reader: ReaderInterface | null; }>

method rebootReader()

Startet das verbundene Lesegerät neu. Welche Lesegerätetypen unterstützt werden, hängt von der Plattform ab.

rebootReader() => Promise<void>

method cancelReaderReconnection()

Bricht einen automatischen Versuch zur Wiederherstellung der Lesegeräteverbindung ab.

cancelReaderReconnection() => Promise<void>

Fehlerbehandlung

Failed wird ausgelöst, wenn Erfassung oder Bestätigung fehlschlägt; das zugehörige Promise wird mit denselben Werten für message / code / declineCode abgewiesen, sofern das native SDK sie bereitstellt.

UnexpectedReaderDisconnect bedeutet, dass Terminal die Verbindung zum Lesegerät außerhalb von disconnectReader() verloren hat. Prüfen Sie bei Bluetooth und USB DisconnectedReader auf den DisconnectReason (POWERED_OFF, BLUETOOTH_DISABLED, CRITICALLY_LOW_BATTERY und weitere).

reader-lifecycle.ts
import { StripeTerminal, TerminalEventsEnum } from '@capacitor-community/stripe-terminal';

await StripeTerminal.addListener(
  TerminalEventsEnum.ReportAvailableUpdate,
  async ({ update }) => {
    if (window.confirm('Will you update the device?')) {
      await StripeTerminal.installAvailableUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.StartInstallingUpdate,
  async ({ update }) => {
    console.log(update);
    if (window.confirm('Will you interrupt the update?')) {
      await StripeTerminal.cancelInstallUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderSoftwareUpdateProgress,
  async ({ progress }) => {
    console.log(progress);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.FinishInstallingUpdate,
  async (args) => {
    console.log(args);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.BatteryLevel,
  async ({ level, charging, status }) => {
    console.log(level, charging, status);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderEvent,
  async ({ event }) => {
    console.log(event);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestDisplayMessage,
  async ({ messageType, message }) => {
    console.log(messageType, message);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestReaderInput,
  async ({ options, message }) => {
    console.log(options, message);
  },
);

await StripeTerminal.setReaderDisplay({
  currency: 'usd',
  tax: 0,
  total: 1000,
  lineItems: [
    {
      displayName: 'winecode',
      quantity: 2,
      amount: 500,
    },
  ],
});

await StripeTerminal.clearReaderDisplay();

await StripeTerminal.cancelDiscoverReaders();

await StripeTerminal.addListener(
  TerminalEventsEnum.UnexpectedReaderDisconnect,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectStarted,
  async ({ reader, reason }) => {
    console.log(reader, reason);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectSucceeded,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectFailed,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.cancelReaderReconnection();

await StripeTerminal.rebootReader();

await StripeTerminal.addListener(
  TerminalEventsEnum.Failed,
  (info) => {
    console.log(info.message, info.code, info.declineCode);
  },
);