Skip to main content

Migration Guide Legacy APK

PhonePOS started out with two APIs. The TerminalHelperService and the HiddenAppFacadeService.
To give you an overall better experience, we united all features in the TerminalHelperService. The TerminalHelperService is designed as a drop-in replacement for the HiddenAppFacadeService with only minimal changes and is based on the classic Android Services communication. If you prefer a typed Java API for implementation, we can offer you the High-Level PhonePOS API. The feature set of the two APIs is equivalent, the only difference is the implementation. The High-Level PhonePOS API does contain a Configuration and Transaction API. It is possible to use only us one of them, for example: Configuration API and mAPI (leaving out the Transaction API).

API comparison​

To help you decide on what API approach works best for you, we have created a comparison between the two APIs. As mentioned before, the two APIs are functionally equivalent and both fully supported.

TerminalHelperService​

Pros​

  • Simple migration from HiddenAppFacadeService
  • No external library dependencies

Cons​

  • Manual handling of connection
  • Manually typed interface

High-Level PhonePOS API​

Pros​

  • Defined Java API
  • Faster integration speed

Cons​

  • High-Level PhonePOS API needs to be included as a library
  • Automatic upgrade of mAPI library on High-Level PhonePOS API library update (only applies to integrators that directly use mAPI and not Transaction API)

Migration to the TerminalHelperService​

As already described, the APIs of HiddenAppFacadeService and TerminalHelperService are very similar. To make the transition as simple as possible, we have listed here the differences:

Action codes​

The message action codes between HiddenAppFacadeService and TerminalHelperService have changed.

interface HiddenAppFacadeServiceAction {
    int MSG_REGISTER_CLIENT = 1;
    int MSG_UNREGISTER_CLIENT = 2;
    int MSG_GET_STATUS = 3;
    int MSG_START_OPI_INIT_SINGLE_TRY = 5;
    int MSG_RESET_PERSO = 6;
}
interface TerminalHelperServiceAction {
    int REGISTER_CLIENT = 0;
    int UNREGISTER_CLIENT = 1;
    int GET_STATUS = 3;
    int RESET_PERSO = 4;
    int TERMINAL_RECOVERY = 19;
}
TerminalHelperService additional features

Described here are only the equivalent codes from HiddenAppFacadeService to TerminalHelperService. The TerminalHelperService does offer more methods. The additional functionality is described in the TerminalHelperService documentation.

getStatus() function​

The getStatus() function will no longer return the status: STATUS_TERMINAL_STARTING (3).
The logic was changed to only return the status when the state is known in the TerminalHelperService. When you execute the getStatus() function via the TerminalHelperService, you will now only receive the states mentioned in TerminalHelper APIs. If you previously set a timeout for the getStatus() function you might need to increase it as you will now only get one message when the terminal has started.

This specifically applies to the case that the PhonePOS Terminal is not already running in the background. In this case, the getStatus() function call will start the Terminal startup process, wait for the process completion and then answer with

int STATUS_TERMINAL_OPERATIONAL = 0;

START_OPI_INIT_SINGLE_TRY() function​

The HiddenAppFacadeService offered the function START_OPI_INIT_SINGLE_TRY which did attempt an OPI init once and then returned. This HiddenAppFacadeService function with code

int MSG_START_OPI_INIT_SINGLE_TRY = 5;

is replaced by the TerminalHelperService function terminalRecovery() with code

int TERMINAL_RECOVERY = 19;

The new function does execute the same OPI init command but additionally checks for LOW_BATTERY and other states.

Migration to the High-Level PhonePOS API​

The connection setup and handling of the HiddenAppFacadeService compared to the High-Level PhonePOS API is quite different. The HiddenAppFacadeService relies on the classic Android Service communication, while the High-Level PhonePOS API does abstract and simplify the communication handling. For guidance of implementation, please head over to the High-Level PhonePOS API documentation. We can also supply you with an example app implementation of all our APIs to streamline your integration experience.