` is the LAN IP address or hostname of the
machine running Open OSCAR Server, and `8081` is the default Web API port (`WEBAPI_LISTENERS`). Do not use
`127.0.0.1`, which refers to the emulator itself.
- **SSL-enabled:** `https://ras.dev/`, where `ras.dev` is the hostname you passed to `make docker-run`. The
emulator must be able to resolve this hostname, either through DNS or its hosts file (step 8).
| Constant | Value |
|---------------------|---------------------------|
| `CLIENT_LOGIN_URL` | `{BASE}auth/clientLogin` |
| `START_SESSION_URL` | `{BASE}aim/startSession` |
| `RENEW_TOKEN_URL` | `{BASE}auth/getInfo` |
For example, an unencrypted server at `192.168.1.10:8081` gives `START_SESSION_URL` the value
`http://192.168.1.10:8081/aim/startSession`.
6. **Build the APK**
Run the following from the `mandarin-android-legacy` directory to build with JDK 8:
**Linux:**
```shell
JAVA_HOME=$(echo /usr/lib/jvm/java-8-openjdk-*) ./gradlew assembleDebug
```
On distributions other than Ubuntu, replace the path with your JDK 8 install directory.
**macOS:**
```shell
JAVA_HOME=$(/usr/libexec/java_home -v 1.8) ./gradlew assembleDebug
```
**Windows (PowerShell):**
```powershell
$env:JAVA_HOME = (Get-ChildItem "C:\Program Files\Amazon Corretto" -Directory -Filter "jdk1.8*").FullName
.\gradlew.bat assembleDebug
```
The APK is written to `app/build/outputs/apk/debug/app-debug.apk`.
7. **Start the Emulator**
```shell
emulator -avd mandarin_api22 -writable-system -no-snapshot-save -no-boot-anim
```
For an SSL-enabled setup, always start the emulator with `-writable-system`. If the emulator fails to boot, add
`-gpu swiftshader_indirect` or `-gpu off`.
8. **Redirect the Server Hostname (SSL only)**
In a second terminal, map `ras.dev` to the host machine in the emulator's hosts file. If the server runs on a
different machine, use that machine's IP address instead of `10.0.2.2`.
**macOS / Linux:**
```shell
adb root
adb remount
adb pull /system/etc/hosts .
echo "10.0.2.2 ras.dev" >> hosts
adb push hosts /system/etc/hosts
```
**Windows (PowerShell):**
```powershell
adb root
adb remount
adb pull /system/etc/hosts .
[IO.File]::AppendAllText("$PWD\hosts", "`n10.0.2.2 ras.dev`n")
adb push hosts /system/etc/hosts
```
9. **Install the Root CA Certificate (SSL only)**
Download your server's root CA certificate from `http://ras.dev/certs/ca.crt`, or copy it from `certs/ca.crt` in
your Open OSCAR Server directory.
> On Windows, use `curl.exe` instead of `curl`.
```shell
curl -O http://ras.dev/certs/ca.crt
```
Run the following from the directory containing `ca.crt`. On Windows, `openssl` is included with
[Git for Windows](https://gitforwindows.org/) under `C:\Program Files\Git\usr\bin`.
**macOS / Linux:**
```shell
HASH=$(openssl x509 -inform PEM -subject_hash_old -in ca.crt -noout)
adb root
adb remount
adb push ca.crt "/system/etc/security/cacerts/$HASH.0"
adb shell chmod 644 "/system/etc/security/cacerts/$HASH.0"
adb reboot
```
**Windows (PowerShell):**
```powershell
$hash = openssl x509 -inform PEM -subject_hash_old -in ca.crt -noout
adb root
adb remount
adb push ca.crt "/system/etc/security/cacerts/$hash.0"
adb shell chmod 644 "/system/etc/security/cacerts/$hash.0"
adb reboot
```
10. **Install and Launch the Client**
```shell
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.tomclaw.mandarin/.main.MainActivity
```
If you rebuild the app with a different base URL, run `adb uninstall com.tomclaw.mandarin` before installing it.
Otherwise, the app keeps its session with the previous server.
Tap **I already have login and password**, then sign in with your Open OSCAR Server UIN or screen name and
password.
## Troubleshooting
**`sdkmanager` or `avdmanager` reports that it requires JDK 17 or later**
The error may also appear as `UnsupportedClassVersionError ... class file version 61.0`. Point `JAVA_HOME` at JDK 17 or
later. Only the build in step 6 uses JDK 8.
**The emulator exits with `x86 emulation currently requires hardware acceleration!`**
The host has no usable hypervisor. On Windows, enable Windows Hypervisor Platform as described in the prerequisites,
then confirm with `emulator -accel-check`. On Linux, confirm that KVM is available (`/dev/kvm` exists).
**The build fails before compiling**
If the build reports `Could not determine java version from ''`, Gradle is running on a JDK other than JDK 8.
Confirm that JDK 8 is installed and that `"$JAVA_HOME/bin/java" -version` reports version 1.8 when run with the
`JAVA_HOME` value from step 6. On macOS, `/usr/libexec/java_home -v 1.8` must print a path; if it doesn't, install the
`corretto@8` cask.
**The client can't connect**
Open `https://ras.dev/` in the emulator's browser. If you're running an unencrypted setup or a different hostname,
adjust the URL to match the base URL you configured in step 5 (for example, `http://192.168.1.10:8081/`). If
successful, you should see the following payload:
```json
{"response":{"statusCode":200,"statusText":"Ok","data":{}}}
```
If the page fails to load, the emulator can't reach the server: check the URL, confirm the server is running, and for
an SSL-enabled setup, check the hosts file entry from step 8 and the certificate from step 9.