# Example App

This project contains an example Android app, which demonstrates a simple integration with the
Terminal Library (the library) and with Example Partner Services.

## Overview

The library enables an app to take contactless payments using the built-in NFC reader. The library
is headless and has to be embedded inside a host app.

The responsibilities of the host app include:

- Rendering the UI
- Performing simple network operations

Regarding details of responsibilities please refer to *Responsibilities* page in Partner Integration
Guide.

This example app shows a simple integration of the library with the host app. The intention is NOT
to demonstrate best-practice, but to show a simple, working integration.

## Getting Started

To build the app, the build environment must have:

- JDK 8+ available on the build path, via either:
  - JAVA_HOME environmental variable
  - [org.gradle.java.home=(path to JDK home)](https://docs.gradle.org/current/userguide/build_environment.html)

- Android SDK Platform 13 API Level 33 SDK
  - Installing via Android Studio' SDK Manager is the preferred approach for local build machines

- Authorization Properties
Provide authorization properties in `build.gradle`, either by setting the values directly or by
specifying them in `authorization.properties` file at parent folder of the example app source
code:
```properties
scope=<service supported scopes for authorization grant>
clientId=<client id>
clientSecret=<client secret>
```
Also possible to specify the same properties via global ~/gradle.properties file:
```properties
TERMINALSDK_AUTHORIZATIONSCOPE=<service supported scopes for authorization grant>
TERMINALSDK_AUTHORIZATIONCLIENTID=<client id>
TERMINALSDK_AUTHORIZATIONCLIENTSECRET=<client secret>
```

Or simply using environmental variables, in this case names must be prefixed with `ORG_GRADLE_PROJECT_`.

- Optional configuration by `assets/config.json`
  A `config.json` file can be provided in the `assets` folder. The schema is as follows:
```json
{
  "transaction_parameters": {
    "amount": <amount> (default 100; PIN txns, 20000 is added),
    "amountOther" <amount other> (default null),
    "currency": <iso currency code> (default 554 == NZD),
    "gatewayId": "<uuid>",
    "metadata": "<base64 encoded metadata>"
  }
}
```
  Fields are optional, defaults will be used when not specified.
  
To build the example app run the following command inside the root project folder (depending on your
operating system):

```
./gradlew assemble
```

Or:

```
gradlew assemble
```

The resulting APK can be found in the `./app/build/outputs/` folder.

Dependencies are fetched from standard global Maven repositories and from a local Maven repository
that contains the library and helper libraries for displaying scheme haptics.

## App Design

The app is built using single activity approach, a single screen is transitioning through various
states while the transaction is processed.

The single activity is `MainActivity`. This activity is backed by the `MainViewModel` class. This
view-model is the core of the example and is responsible for processing app and library events.

These events are translated into `ViewData` changes that are applied on the view model.

## App Usage

Before initiating a transaction please make sure the NFC reader is enabled on the device.

Typical life cycle of a successful transaction is:
Terminal activation -> Start transaction -> Card processing -> Authorisation -> Transaction finished

Some of these stages can be triggered using the buttons that are appearing on the screen.

When the app prompts for card then please tap a contactless payment card or device to the back of
the terminal app device and hold it there while the transaction is processed. Vibration gives you
feedback for card communication. NFC reader is positioned differently on each device, please try to
move the card around the back until you notice the communication.

At the end of the card processing standard beep is played and the app instructs you to remove the
card from the RF field.

Emitted logs from library are displayed on the UI for convenience, also forwarded to standard
Android Logcat output.