fiskaltrust-instore-app

fiskaltrust InStore App

The InStore App is a plug & play extension for fiskaltrust.Middleware powered POS Systems. It provides a zero-effort way to extend POS systems with processes like digital receipt, payment, printing, and loyalty.

• Business Owner: Stefan Kert

Additional Information (SharePoint)

Additional InStore App documentation and files not stored in GitHub are available in SharePoint:

• InStore App SharePoint

Prerequisites

• .NET SDK 9.x
• Git with Git LFS enabled
• Android SDK (installed via .NET MAUI workload)

Releases and Release Candidates (rc)

Releases and release candidates are done by creating a tag:

• Format for releases: vX.Y.Z (e.g., v1.2.7)
  • X = Major, Y = Minor, Z = Patch
  • with ‘v’ prefix
• Format for release candidates: vX.Y.Z-rcN (e.g., v1.2.7-rc3)
  • N = Release candidate number (increments for each RC)

Trigger the build

To create a tag execute the following commands:

git tag v1.2.6
git push origin --tags

When the tag is pushed github actions workflow for release builds will trigger and create the following:

• build the apk (for stores and manual install) and aab (for Google Play) files using the tag name as the display version
• rename them to include the display version in their filenames
• upload the built artifacts to github artifacts (the signed apk+aab files and the mapping.txt file for crash de-obfuscation) for easy download with every workflow run directly from github
• upload the built artifacts to azure blob storage
• will write the URLs in the github action logging at the end from where the artifacts can be downloaded in azure blob storage (needed later to rewrite the permalink links for the public downloads)

Test the release candidate

The main purpose of a release candidate is to be used for testing (mainly internal but also external if required). See here to get an idea how testing works.

Create a release out of a release candidate

When testing is successful, tag the same commit with the release version:

# Example: Promote rc3 to final release
git tag v1.2.7 v1.2.7-rc3
git push origin v1.2.7

Release a package to the public (release or release candidate)

Independent of the normal tests before making a release public do a smoke test:

Minimum smoke test:

• App installs on physical device
• App starts without crashes
• MQTT connection works
• Receipt request processes successfully

Create release notes

Before releasing a package to the public the release notes should be ready and publicly available so that customers / users can get an idea at any time about the changes in new releases.

To create release notes:

• work through all the issues of the milestone for the current planned release in github and update their title and labels
  • Is the title alone enough to understand the change? (Note: Customers will not have access to the issue description so the title is the only thing they will see)
  • Is the change important to know for customers/users?
    • Does the change actively affect them because it fixes issues, has an impact on their usual handling of our application or provides new features?
    • Should they be aware of the change to strengthen the trust in our products?
    • IF YES –> mark with label Release Notes
    • IF NO –> mark with label INTERNAL
• Filter for all the issues of the milestone marked with the label Release Notes to get a clear list of the changes that must go into the release notes
• Write the release notes (in a feature branch as with every change)
  • Go to the release-notes repository
  • Create file: YYYY-MM-DD-vX.Y.Z.md (e.g., 2025-11-21-v1.2.7.md)
    • ⚠️ Important: Use the same file for all RCs of this version
    • Update the date when promoting to final release
    • Add sections for each RC to show progression
      • Make it clear in the Other Changes section (see below) since which version the change is active so that customers can see in which release / release candidate the change was introduced and do also see what changed from one release candidate to the next or to the final release.
  • check also the previous release notes to get an idea about formating
  • First section - the exiting changes that are explained in more detail (images, text, graphics, …). The goal is to make customers/user want to use this release in this section.
  • Second section - ‘Other Changes’ - list of all the changes which is the list of issues with Type + ID + Title from the milestones with label Release Notes. Note: We also include the changes that we already mentioned in the first seciton.
    • suggestion: make a separate sub section for each release candidate and the final release to clearly see which part was changed in which package.

Make the package available to the public

This is done by updating the preview (for release candidates) or stable (for releases) links in the permalink repository which will automatically make it available via the official links:

• release candidate == preview: https://link.fiskaltrust.eu/downloads/instoreapp/preview
• release == stable: https://link.fiskaltrust.eu/downloads/instoreapp/stable

⚠️ CAUTION:

• Changes are immediately live after pushing to main
• Do not break existing links
• Double-check URLs before committing

Changes to this list are usually done directly in the main branch and will immediately be active after pushing the change!

Architecture

Application Events

Most of the application events are based on MQTT Messages. For managing states and internal communication we are using a few more events that allow us to have a loosley coupled architecture.

• MQTTConnectedMessage
• MQTTDisconnectedMessage
• ReceiptIssueStateUpdatedMessage
• ReceiptIssuedMessage
• ScannerDataReceivedMessage
• CashBoxChangedMessage

MQTT Messages

The InStore App processes several messages from the MQTT Bus and publishes them in the local application

• ReceiptIssueStateUpdatedMessage => topic ending with submittedforprinting
• ReceiptIssuedMessage => topic ending with printed

Filters

• Terminal Filters

Receipts

Delivering receipts is a core mechanism of the InStore App. The InStore App is able to provide the compliant receipt in digital and phyiscal form (printed). While the printed form always depends on the printer (see Printer support section for further info), the digital receipt is usally transmitted via an URL.

Emitting Components

Emitting Components are components that act upon new receipts being available. These components use the data that is being received via the MQTT Bus and emit them in a specific form. Some of the emitters only make the information available but don’t act upon actions that are taken by the users (e.g. receipt received via NFC)

The following section contains a brief overview about the currently availble emitters.

• NFC: The NFC sensor sends the URL for the emitted receipt as part of a Nano Tag. It can be received with a modern smartphone via a Push Notification that can then be opened.
• View: The View emitter visualizes the given receipt in a form that matches the configured parameters and also the local market regulations. Users can use a Phone to scan the visualized QR Code to scan it.