Non-Keyple Client User Guide

A “non-Keyple client” refers to a client application developed in a language other than Java, Kotlin, or C++, and therefore unable to directly integrate the core libraries of the Keyple ecosystem.

This application is installed on a terminal equipped with a card reader. However, due to its technological environment, it cannot locally use Keyple’s core components to access the card or perform ticketing procedures. It must therefore rely on a remote Keyple-based component (e.g., through a server API) to carry out these operations.

Overview

This guide is designed for developers of non-Keyple client applications embedded in smart card processing terminals, who need to delegate all or part of the management of the smart card ticketing transaction to a Keyple-based server application.

This use case corresponds to the Reader Client Side usage mode of the Keyple Distributed solution.

Operating mode

The client is the initiator of the application processing following a card event (card insertion/removal). He can hand over to the server whenever he wants to perform a remote ticketing service on a card present in one of his local readers.

There are two ways for a non-Keyple client application to communicate with a server based on the Keyple middleware:

Manual implementation of the Keyple JSON specifications
Using the Keyple interop multiplatform libraries

Manual implementation

You can implement the communication logic manually by following the official Keyple JSON specifications:

Specification	Description
Server JSON API	Describes the workflow and the JSON format of data exchanged between terminal and server during a remote card transaction, as well as the corresponding business rules.
Selection JSON Specification	Describes how to implement early card selection on the terminal before requesting the server to continue the card transaction, as well as the JSON format of the involved data.

This approach ensures maximum flexibility and autonomy for integrators. However, it requires full ownership of the implementation, including the business logic defined in the Selection JSON Specification and the Server JSON API. It also involves managing JSON (de)serialization of the corresponding data structures and implementing the card reader access layer.

Keyple interop libraries

To simplify development and ensure compliance with the specifications, you can integrate the following ready-to-use Keyple interop multiplatform libraries into your application:

Keyple Interop Library	Platform	Description
JSON API Client	Windows, Linux, macOS, Android, iOS	A Kotlin multiplatform client library that fully implements the Keyple Server JSON API and Selection JSON Specification. It enables direct interaction with a Keyple-based server over HTTP.
Local Reader NFC Mobile	Android, iOS	A Kotlin multiplatform adapter that provides access to mobile NFC readers. It allows smart card operations to be performed locally and used in conjunction with the JSON API Client library.

This second option greatly reduces implementation effort and ensures compatibility with the evolving Keyple ecosystem.

Workflow overview

The following sequence diagram shows the overall interaction flow between a client application and Keyple’s interop libraries:

Workflow details

Retrieve an export of the card selection scenario from the server using your preferred method. This scenario will be processed when a card is detected. For more details, refer to Keyple’s Import/Export Scenario feature.
Implementing early card selection is strongly recommended for non-Keyple clients as it increases performance by reducing the number of network exchanges, as the selection scenario can be processed autonomously by the terminal as soon as a card is presented.
The scenario should be retrieved by the customer well before a card is presented, for example during installation, updating or application startup.
Build an instance of KeypleTerminal, providing a LocalReader implementation to access the card reader, a SyncEndpointClient implementation to access the server over HTTP, and possibly a card selection scenario export to be processed when a card is detected.
The Keyple Interop Local Reader NFC Mobile Library provides the MultiplatformNfcReader class as a LocalReader implementation for NFC mobiles, but you can provide other implementations depending on your context.
The implementation of the SyncEndpointClient remains your responsibility, as it is specific to the context of the client application.
In a context with several server instances, a mechanism must be implemented to ensure that all messages associated to a functional transaction are routed to the same server instance.
The client network endpoint can use the value of the sessionId field contained in the MessageDto object transmitted by KeypleTerminal to identify transactions. This value is generated for each new execution of a remote service. When the client endpoint detects a new value, it can, for example, transmit the first message without a session cookie in order to be routed to the first available server, then transmit the session cookie returned by the server in subsequent exchanges until a new transaction is detected.
The export of the selection scenario can be provided at a later date using the dedicated setter function if required, for example, after the card has been detected, but before to execute the remote service.
Wait for the card to be detected by calling the associated function provided by KeypleTerminal.
Waiting can be performed synchronously or asynchronously, and can also be cancelled.
Execute the desired remote service by calling the associated function provided by the KeypleTerminal by specifying the identifier of the ticketing service to be executed and transmitting to the server additional information if needed.
The remote service execution is blocking.