skdhruv/zombiebox-platform-android-tv

Android-платформа состоит из двух частей: zb-платформа и apk-обёртка, позволяющая запускать zb приложения на Android устройствах.

Обёртка представляет из себя приложение, содержащее видео-объект и WebView (читай браузер без интерфейса) поверх него. WebView открывает html страницу с приложением и проксирует интерфейс управления видео объектом в него.

Для установки приложения требуется adb, для сборки Android SDK.

Если требуется только adb, на большинстве систем его можно поставить отдельно от SDK, например на macOS с помощью brew: brew cask install android-platform-tools

Установка SDK

Сначала необходимо установить Java JDK/JRE версии не менее 8.

Установить можно либо Android Studio, либо только инструменты командной строки (внизу) со страницы SDK: https://developer.android.com/studio/index.html.

Инструменты необходимо распаковать в отдельную директорию, которая и будет корнем SDK.

Далее необходимо принять все лицензионные соглашения компонент: <path-to-sdk>/tools/bin/sdkmanager --licenses.

После установки в переменной окружения ANDROID_HOME нужно указать путь до SDK:

echo 'export ANDROID_HOME=<path-to-sdk>' >> ~/.bashrc && source ~/.bashrc

Сборка приложения

Apk можно собрать с помощью системы сборки zb: zb build android. Параметры сборки указываются в конфиге приложения в объекте android. В первый раз сборка может занимать очень долгое время - система сборки андроида будет выкачивать зависимости.

Также проект можно собрать в Android Studio из папки native. Конфигурировать в таком случаем можно в build.gradle.

Ключевой параметр при сборке — storeRelease. Значение true собирает apk пригодный к загрузке в маркет, false — пригодное для тестирования и отладки. Релизное приложение собирается неподписанным, без подписи оно запускаться не будет. Перед выгрузкой его нужно подписать вендорским ключем, либо передать неподписанным тому, кто его будет выкладывать в маркет.

Подпись неподписанного апк

Для тестирования финальной релизной сборки её можно подписать временным ключем.

Для подписи сначала нужно сгенерировать ключ с помощью keytool:

keytool -genkey -v -keystore key.jks -keyalg RSA -keysize 2048 -validity 10 -alias my-alias

Команда с этими параметрами сгенерирует ключ key.jks, валидный 10 дней. Ключи с долгими сроками валидности лучше не генерировать во избежание проблем.

Если утилиты нет в PATH, она, скорее всего, находится в папке bin/ JDK (/Library/Java/JavaVirtualMachines).

Подпись делается с помощью утилиты apksigner из папки build-tools/<ВЕРСИЯ> Android SDK:

apksigner sign --ks key.jks --out app-release-signed.apk app-unsigned.apk

Установка приложения

Перед началом работы на устройстве нужно включить режим отладки: Settings - Developer Options - USB debugging (или что-нибудь подобное). Если меню Developer Options не отображается, нужно найти в «Информацию об устройстве – Номер сборки» и прокликать на него несколько раз. После этого меню разработчика должно появиться.

У телевизоров обычно по-умолчанию включена отладка по сети и к ним сразу можно подключиться с помощью adb connect <ip-адрес>. Если это не так, нужно подключиться с помощью USB-кабеля, после этого командой adb tcpip 5555 можно включить беспроводную отладку.

После подключения нужно убедиться, что устройство готово к работе командой adb devices. Напротив имени устройства (ip-адрес, либо идентификатор) отображается статус. Желаемый статус — device, либо имя устройства.

В первый раз устройство попросит подтвердить подключение нового компьютера выдав диалог. Если диалога не появилось, можно попробовать в настройках разработчика отключить и снова включить отладку и подключиться снова.

Перед установкой для избежания ошибок установки рекомендуется удалить предыдущую версию с помощью интерфейса системы.

Установка апк: adb install <путь к апк>.

Дополнительная информация

Если подключено больше одного устройства, для всех команд требуется указывать целевое с помощью флага -d.

adb disconnect - отключение от устройств.

adb logcat - логи, см документацию по фильтрации.

adb, похоже, конфликтует с аналогичной утилитой для Tizenа (sdb). Возможно странное поведение, когда запущены сразу обе. Рекомендуется останавливать sdb перед работой с adb (sdb kill-server) и наоборот (adb kill-server).

При проблемах с обнаружением девайса часто помогает включить-выключить отладку в настройках разработчика.

Более подробная иструкция по adb: https://developer.android.com/studio/command-line/adb.html.

Разработка под платформу

API платформы

В глобальном объекте представлены два объекта: Device и Player.

Device предоставляет события и методы платформы, Player — видео-объекта. Достаточно подробное описание их методов есть в extern'ах.

Т.к. Java — строго типизированный язык, в отличие от JavaScript, параметры всех методов также строго типизированы, например Player.setVolume('40') вместо Player.setVolume(40) выбросит исключение.

Параметры конфигурации

• appId — уникальный идентификатор приложения. Принята нотация в виде обратной доменной записи, например ru.interfaced.appName. В релиз-конфигурации параметр (storeRelease) обязателен, в дебаг-режиме сгенерируется автоматически, если не представлен.
• namespace — идентификатор сборки. По-умолчанию основан на name из package.json.
• versionName — отображаемая пользователю версия. По-умолчанию version из package.json.
• versionCode — целочисленный код версии. Использутся Google Play для определения обновлений. Обязательный параметр при storeRelease == true. При каждой сборке предназначенной для маркета должен увеличиваться.
• name — отображаемое имя приложения.
• launcherColor — цвет анимации открытия приложения. По-умолчанию чёрный.
• useBundledHTML — true — интегрирует HTML-приложение в apk, false — загружает приложение по сссылке, переданной в параметре applicationURL. По-умолчанию true.
• applicationURL — ссылка на zb-приложение (см useBundledHTML).
• webViewDebug — включает возможность отладки WebView. По-умолчанию false.
• storeRelease — если true, приложение будет скомпилировано в релизной конфигурации для релиза в Google Play.
• resPath — путь к ресурсам.

Ресурсы

Директория, указанная в поле resPath, должна содержать ресурсы приложения согласно структуре, описанной в документации.

Если какой-то из ресурсов не существует, вместо него будет использоваться ресурс по-умолчанию (лого Interfaced будет использовано вместо иконок).

Основной тип ресурса, про который важно не забыть — иконки для различных разрешения, см документацию.

Дополнительно для Android TV нужен баннер (drawable/banner.png), см требования.

Отладка

Для отладки нужно подключиться к устройству с помощью adb, открыть в Chrome или Chromium адрес chrome://inspect и в списке доступных для отладки страниц нажать Inspect на нужной. Apk должен быть собран с флагом webViewDebug == true.

Инспектор иногда может не сразу находить устройство или страницу, перезагрузка страницы chrome://inspect может помочь.

Для удобства можно задать параметр applicationURL на локальный zb run сервер (и использовать эндпойнт /es6).

Дополнительно logcat может дать информации о работе внутренней платформы, а в Меню Разработчика в настройках есть много полезных инструментов мониторинга.