fiskaltrust.Middleware demo (Android)

Demo applications written in Java and Xamarin that demonstrate how to call the German fiskaltrust.Middleware on Android devices using gRPC or HTTP/REST*.

*The Android demo for Java does not yet contain an example about how to connect to the HTTP Android Launcher. While we update this, please refer to our regular Java samples.

Getting Started

Prerequisites

In order to use these demo applications, the following prerequisites are required:

• The demo application: Just clone or download this repository. For an optimal experience, we recommend using Android Studio for the Java samples, and Visual Studio for the Xamarin ones. Both can be downloaded for free.
• The fiskaltrust.Middleware for Android installed on your device, which can be configured and downloaded via the fiskaltrust.Portal. Please note that the Android download is only available for cashboxes that only contain supported packages (SQLite, Fiskaly and Swissbit) and supported protocols (gRPC and REST).
• The Cashbox Id and Access Token are visible in the portal, and are needed to start the Middleware on Android.

The Java example in this repository uses the .proto files of the fiskaltrust Middleware interface to automatically generate the client and the contracts at build time via the officially suggested gRPC packages (a comprehensive tutorial and overview can be found here). The latest .proto files are available in our interface-doc repository.

The Xamarin/C# example uses the fiskaltrust.Middleware.Interface.Client.Grpc NuGet package, which doesn't need the .proto files. A more detailed documentation about this package can be found in its repository. HTTP works without any additional required files anyway, and uses the fiskaltrust.Middleware.Interface.Client.Http package.

Running the Demo

Make sure to download the respective Android Launcher (gRPC or HTTP) from the Portal and install the APK on your device first (or get it from Google Play). This App contains a background service that can be started and stopped via intents, and spins up a gRPC server. Thus, the Android App behaves exactly the same as the fiskaltrust.Middleware does on Desktop operating systems.

There are some limitations when configuring an Android Cashbox in the Portal:

• The cashbox must not contain WCF URLs (neither the SCU nor the Queue), as they are not supported on Android.
• Currently, only the following packages are supported:
  • fiskaltrust.Middleware.Queue.SQLite
  • fiskaltrust.Middleware.SCU.Fiskaly
  • fiskaltrust.Middleware.SCU.Swissbit

If you require other Queue or SCU packages on Android, please reach out to our support to help us prioritizing.

Java

We recommend using Android Studio to run the Java Android samples, as we used it to implement them. Just open the java folder and wait until gradle synced everything.

However, it's also possible to directly build the APK from the command line:

# Build APK only
gradlew assembleDebug

# Optionally, to build the APK and install it on your connected device automatically:
gradlew installDebug

Xamarin/C#

To run the Xamarin example, Visual Studio with the Xamarin workload is required. Please follow the official docs to download and install it on your machine.

After this, opening the solution in the xamarin folder of this repository and clicking Debug should be all.

Minimal sample

Starting and stopping the Middleware is fairly easy, as it can be controlled via Intents.

The Middleware can e.g. be started with the following Java code:

// For gRPC
ComponentName componentName = new ComponentName("eu.fiskaltrust.androidlauncher.grpc", "eu.fiskaltrust.androidlauncher.grpc.Start");
// Alternatively, for HTTP/REST
ComponentName componentName = new ComponentName("eu.fiskaltrust.androidlauncher.http", "eu.fiskaltrust.androidlauncher.http.Start");

Intent intent = new Intent(Intent.ACTION_SEND);
intent.setComponent(componentName);
intent.putExtra("cashboxid", "<your-cashbox-id>");
intent.putExtra("accesstoken", "<your-access-token>");
intent.putExtra("sandbox", true);   // or "false" for production Cashboxes
intent.putExtra("enableCloseButton", false);   // or "true" to display a close button in the notification
// Optionally, for development purposes only:
intent.putExtra("loglevel", "Debug");   // default is "Information"

sendBroadcast(intent);

Please note that the Middleware will not be immediately available after this. Intents are processed asynchronously, and initializing most TSEs takes some time (e.g. up to 45 seconds for Swissbit; fiskaly SCUs are faster). We recommend polling our state endpoint until the TSE is intialized (see below).

A stop intent looks similar:

// For gRPC
ComponentName componentName = new ComponentName("eu.fiskaltrust.androidlauncher.grpc", "eu.fiskaltrust.androidlauncher.grpc.Stop");
// Alternatively, for HTTP/REST
ComponentName componentName = new ComponentName("eu.fiskaltrust.androidlauncher.http", "eu.fiskaltrust.androidlauncher.http.Stop");

Intent intent = new Intent(Intent.ACTION_SEND);
intent.setComponent(componentName);

sendBroadcast(intent);

After the Middleware successfully booted (the state is also shown in the Android notification), an echo Request via Java can e.g. be sent like this:

ManagedChannel channel = ManagedChannelBuilder.forTarget(url).usePlaintext().build();
POSGrpc.POSBlockingStub blockingStub = POSGrpc.newBlockingStub(channel);

IPOS.EchoRequest request = IPOS.EchoRequest.newBuilder().setMessage("Hello Android!").build();
IPOS.EchoResponse response = blockingStub.echo(request);

State and log information

The fiskaltrust.Middleware for Android publishes two endpoints to request both the state and the logs under the well-known HTTP address and port http://localhost:4654/:

• GET http://localhost:4654/fiskaltrust/state returns a JSON object with the current state of the Middleware and the reason, which looks like this:

  {
    "CurrentState": "Uninitialized" | "Initializing" | "Running" | "Error",
    "Reason": "CONFIG_NOT_FOUND" | "REMOUNT_REQUIRED" | "<informational reason phrase>"
  }
  

  REMOUNT_REQUIRED is only applicable for Swissbit TSEs, which require a remount when they're used in an Android App for the first time (i.e. they need to be plugged out and in again).
• GET http://localhost:4654/fiskaltrust/logs returns the raw log files written by the Middleware for later usage. The same messages are also written to LogCat, which might be more convenient during development. This endpoint is authenticated via HTTP header values: cashboxid and accesstoken.

Direct log access

For security reasons, log files are stored in the private directory of the Middleware App. In case the log endpoint described above is not reachable (e.g. because the Middleware cannot be started at all), log files can also be accessed via an Android content provider. We've implemented a specific activity that can be queried to return a content:// link to the latest log file. The usage of this provider is e.g. demonstrated here, more details about content providers are available in the Android docs.

Additional information

The fiskaltrust.Middleware is written in C# and uses some language-specific functionalities that a user needs to take care of when connecting via gRPC:

Due to the binary serialization in Protobuf, DateTime and decimal (which are native types in C#) need to be converted when used outside of .NET. Thus, the bcl.proto is referenced in the IPOS.proto file. An example how to deal with these types is shown in ProtoUtil.java.

Documentation

The full documentation for the interface can be found on https://docs.fiskaltrust.cloud. It is activeliy maintained and developed in our interface-doc repository.

More information is also available after logging into the portal with a user that has the PosCreator role assigned.

Contributions

We welcome all kinds of contributions and feedback, e.g. via Issues or Pull Requests.

Related resources

Our latest samples are available for the following programming languages and tools:

                                               

Additionally, other samples (including legacy ones) can be found in our demo repository.