| Application Folder Structure
| Merchant Configuration
From the Android Studio welcome window you can choose to work on a new or existing project, or import a project.
New Android Studio Project
Begin developing a standard Android application by selecting Start a new Android Studio project. All standard Android Studio features are available to develop apps. Please refer to Google for published documentation.
New Verifone Commerce Application Project
You can start a new project for developing a Terminal Commerce app, Android app, or Android Commerce app by selecting Start a Verifone Commerce project.
Importing a Terminal Commerce or Android Commerce app
If you want to import an existing application package into development tools, select Import project (Verifone, Eclipse ADT, Gradle etc).
Open Existing Android Studio Project
To continue working on an existing application, select Open an existing Android Studio project and click on your project from the list of projects available in your workspace.
When you begin work on a new application project, start by defining the project name and workspace where the project will be saved. You can also use the default location for the workspace. After that, define the preferred hardware capabilities the target terminal should have to run your application.
Select all the display resolutions your application will support. Note that the Integrated Development Environment (IDE) can be configured to auto-generate Terminal Commerce app UI views for multiple display resolutions. If you set the Terminal Commerce app to support only one or two resolutions, you’re limiting the number of terminal types your application can operate on.
Terminal Commerce apps can utilize the specific hardware capabilities terminals are equipped with. It’s recommended to build applications that utilize hardware capabilities if they’re available, but not to depend on them. If you build dependency on any of the documented capabilities, your app will be functional only on terminals having those specific hardware capabilities. While developing apps, it's best to avoid hard dependencies and target the maximum number of terminal models with the same app code base.
Application Project Folder Structure
When you create a new project, the Commerce Applications SDK automatically creates the required application folder structure in the application project.
Definitions of the main folders and files, from the bottom up:
Storyboard functionality is described in the ‘Hello World" chapter.
In the manifest file (.mft), you can define application parameters as well as triggers.
A temporary app name can be given while developing the app. The final name will be confirmed during the publishing stage. At the same connection, the Developer Central will auto-generate an app ID. During the application publishing phase, the final app name and app ID need to be included in the app manifest file in the Commerce Applications SDK before building the final application package.
A Terminal Commerce Application can be implemented to run as a background service without a UI layer. These apps are called services or headless apps. In the manifest file, you need to specify if the application is a service. This is done in relation to the trigger definition that will launch the application/service. If multiple triggers can launch the application, the manifest file should include the app definition (service/application) for each trigger.
A Terminal Commerce application installed on the terminal desktop is manually launched by clicking the related application icon on the desktop. For these applications, you need to provide the icon file and icon label in the manifest file.
For the used triggers, you must define a start page. The trigger initiates the Terminal Commerce application from the defined HTML page. Please note that one must use a common, shared HTML page that is available for all targeted terminal display resolutions.
confApp.json includes configuration properties with values and can only be modified by the application developer.
confOwner.json includes configuration properties with values that can only be modified by the application buyer. This file is created during the application purchasing stage, not when the application is being developed. If the properties are designed to be modifiable by the
application buyer, the developer must define them as a JSON Schema in a file named confSchema.json.
As a developer, the need to test the designed application from merchant’s perspective is very important. In order to facilitate this, the Commerce Applications SDK provides a feature where in the developer can simulate the merchant configuration for his application and test it on both the simulator and the DevKit.
The merchant configuration is nothing but the confOwner.Json file which is generated when the merchant downloads the application from the Merchant Marketplace. The file includes parameters like timeout, priority and silence periods that merchant sets on the Marketplace when downloading the application.
In the SDK, the developer can define a schema as per the requirement of the application in the confSchema.json file. This defined schema can have various parameters depending upon the requirement of the application. The default values of the parameters from this schema file are stored in the confOwner.json file. The application refers to the confOwner.json file for the values of timeout, priority and silence periods used in the application.
Earlier the developer could do the configuration by hardcoding the values and parameters in the confOwner.json file that was generated during the project creation. Now the developer has a new Json view to set different values depending upon the need of the application. The Json view would include all the parameters that are defined by the developer in the confSchema file. This helps the developer to verify if the application complies with the parameters defined in the schema and function correctly. The values for the parameters that are entered in this view are validated with the threshold values that are defined in the confSchema.json. This helps the developer to correctly configure the application and test the same.
The Triggers folder includes the JSON code for the triggers selected for the application. You can use this information to understand trigger payload data available for your application, as well as the response data your application must send to the payment application. Note: The parameter values in the JSON code are the ones the simulator will use when you run the application in the simulator. You can adjust these parameters either directly in the Triggers folder, or when you start the simulator.
The Images folder includes the imported image files available to be included in the application. Please note that for desktop apps, the Images folder includes a default icon that can be used until you have designed an icon for your app.
The Default folder includes the default CSS file used for all terminal display resolutions.
You can design your application to support multiple terminal display resolutions; the SDK will package source code for all display options into one application package. On the application package file structure, you will see a dedicated folder for each supported terminal resolution. While running the app on a payment terminal, the Commerce Platform Runtime will pick and choose the correct set of HTML pages to be rendered, according to the display type of the terminal. As a developer, you don’t need to build a decision tree in the application logic to verify terminal display resolution and to select the right set of HTML pages from the application package.
In addition to HTML pages, the folders also include display resolution specific CSS files. You can edit the CSS for each display resolution separately by modifying the related app.css file. It’s important to note that you shall not change the file name or the extension.
The file folders for HTML pages and related CSS files are named according to terminal display resolutions. Character “C’’ on the folder name refers to color display while numbers 13 or 15; as an example, refer to the count of mechanical keys the terminal has.
Manifest File Content:
The tool automatically gives your application a temporary App Name and App ID in order to enable the simulator. You will need to update the file name during the application publishing phase. Publishing tools will verify the proposed name is not already used, and will auto-generate an app ID for you. You need to copy the app ID into the app manifest file in the Commerce Applications SDK and then package and export your application for publishing.
Services, also called headless apps, do not have a UI layer. If your app includes a UI layer, select App under Type. Note that this setting between Application and Service can be defined separately for each trigger and related HTML pages the app includes.
Label allows you to define the text associated with the icon shown in the desktop view, for launching the application manually.
In the Icon field, add the icon file your application will show in the desktop view.
In Triggers, select the trigger(s) used to invoke your application. In the File field, define the HTML file the trigger(s) will launch as a start page for running your application.
You don’t need to input all information at this phase; you can come back to Manifest and Triggers settings at any time while implementing your application.
The preferred method to build the application UI flow and define triggers to wake up the Terminal Commerce Application is Storyboard.
To implement application logic and to define parameters and values that will be transferred from one page to another, as well as to polish the application UI, you must work with individual HTML pages. Individual pages can be opened by clicking the corresponding HTML file in related file folder. You can also click the View Source button in the Storyboard to access individual pages. When you have the individual page open, you can add/edit UI elements using the drag and drop functionality. You can also toggle between the UI designer view and the source code view by clicking related buttons labeled as Design and Text.
In the Properties fields, you can define the background color for the pages or the properties of each UI element. Refer to the standard HTML documentation for properties details.