# Android

A native wrapper for the [JS library](/docs/in-person-payments/pay-in-person/integration-guide/js-library), written in Kotlin, for POS applications that
embed a WebView themselves rather than a browser page. `TyroClient` wraps iClient in an embedded
WebView under the POS's control, exposing the same functions, parameters and callbacks as the JS
library.

Download the Android library:

[Android library](/assets/android-tta.bbfa75f3026705c6d563479697cb9f6a091deb8d7244bb86890b5b69da90af34.fbf1555a.zip)

Before you begin development, check the certification criteria:
[Certification Criteria Document](/assets/certification_criteria_iclient_retail_hospitality.7bf0b2b5462961db882fcba1f1e9ddbec0d942cc7ee96278907994599bebf62a.d564e73d.pdf).

## Usage

The embedded wrapper library is defined as package `com.tyro.androidtta`. Examples of how to
handle receipt callbacks, request context and transaction-complete callbacks can be found in the
library.

## Setting the iClient source

Set where the wrapper finds the iClient JavaScript library (simulator, test or production) via
`com.tyro.androidtta > iclientSource`. Use a multi-endpoint array, as below, or a single value if
you're only using one endpoint.


```java
public enum IclientSource {
  PRODUCTION("https://iclient.tyro.com"),
  TEST("https://iclient.test.tyro.com"),
  SIMULATOR("https://iclientsimulator.test.tyro.com");
  private String url;
  IclientSource(String url) {
  this.url = url;
  }
  public String getUrl() {
  return url;
  }
}
```

## Setting the API key, POS data and iClient URL for transactions


```java
tyroClient = TyroClient(webView,
 "someApiKey", //no API key is needed for test or simulated transactions, a real API key will be needed for production transactions
 PosProductData("DOMENIC’S POS COMPANY", "POS NAME", "1.1.0"),
 IclientSource.TEST
```

## Headless pairing (custom pairing)

Android's WebView component is based on Chromium. Chromium made modifications to the way
third-party cookies are handled in order to increase security and privacy while giving users
greater control and transparency. When apps target Android 12 (API level 31) or higher, these
modifications are also included in WebView as of Android 12. Because of these changes, pairing
details won't be persistent when you process a transaction if the Tyro pairing UI
(`https://iclientsimulator.test.tyro.com/configuration.html#expert`) is loaded in a WebView to
complete the pairing process — so it's mandatory for POS partners to implement pairing using the
pairing API (headless pairing) instead.

#### Example 1


```java
PairingButton.setOnClickListener
{
val parameters = mutableMapOf<String,Any>()
val mid = MID.text.toString()
val tid = TID.text.toString()
parameters["mid"] = "$mid"
parameters["tid"] ="$tid"
tyroClient.performOperation(
"pairTerminal",
 parameters,
{receipt -> },
{data -> println("data = [$data]")})
}
```

**Android Studio Logcat output:**


```console
2024-02-21 11:20:53.688 28181-28437 System.out  com.tyro.tyroclientsample  I  data = [{message=Pairing successful., status=success, integrationKey=b34fe79127d0d70b07563a94622366a8}]
```

#### Example 2


```java
PairingButton.setOnClickListener {
    display.text = "\n\n\tStatus:\n\tinProgress\n\n\tMessage:\n\tPlease perform the \"Authorise POS\" function on your terminal"
    val parameters = mutableMapOf<String, Any>()
    val mid = MID.text.toString()
    val tid = TID.text.toString()
    parameters["mid"] = mid
    parameters["tid"] = tid
    tyroClient.performOperation(
        "pairTerminal",
        parameters,
        { receipt -> },
        { data ->
            if (data["status"] == "success") {
                display.text= "\n\n\tStatus:\n\t" + "${data["status"]}\n\n" + "\tMessage:\n\t" +
                            "${data["message"]}\n\n" + "\tIntegration Key:\n" + "\t${data["integrationKey"]}"
            }
            else
               {display.text= "\n\n\tStatus:\n\t" + "${data["status"]}\n\n" + "\tMessage:\n\t" +
                            "${data["message"]}\n\n" + "\tIntegration Key:\n" + "\t${data["integrationKey"]}"}
        }
    )
}
```

The POS must display the `status` and `message` fields on the POS UI gracefully. The POS must
store the MID, TID and integration key in the POS app's own database, and pass them when
processing a transaction.