diff --git a/README.md b/README.md index 3fa7a0a..aba61ec 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ background delivery, automatic retries and a delivery journal. Webhook requests ## Getting started -Guides: [n8n webhook](docs/en/n8n-webhook.md) · [Telegram forwarding](docs/en/n8n-telegram.md). -На русском: [n8n webhook](docs/ru/n8n-webhook.md) · [Пересылка в Telegram](docs/ru/n8n-telegram.md). +Guides: [Install from APK](docs/en/apk-installation.md) · [n8n webhook](docs/en/n8n-webhook.md) · [Telegram forwarding](docs/en/n8n-telegram.md). +На русском: [Установка из APK](docs/ru/apk-installation.md) · [n8n webhook](docs/ru/n8n-webhook.md) · [Пересылка в Telegram](docs/ru/n8n-telegram.md). 1. Save the full published webhook URL and a device code in **Connection**. Send a test event. 2. Check **Journal** and find the same event ID in n8n **Executions**. diff --git a/docs/en/apk-installation.md b/docs/en/apk-installation.md new file mode 100644 index 0000000..df88d79 --- /dev/null +++ b/docs/en/apk-installation.md @@ -0,0 +1,107 @@ +# Install Message487 from an APK + +[English](../en/apk-installation.md) | [Русский](../ru/apk-installation.md) + +## Download and install + +1. Open the project's [GitHub Releases](https://github.com/andre487/AndroidMessage487/releases) + on your phone. Choose a release, read its notes and download `message487-.apk` + from **Assets**. Source-code archives and `mapping.txt` cannot be installed. +2. Open the downloaded APK. If Android asks for permission to install from this source, + open **Settings** from that dialog and enable **Allow from this source** for the + browser or file manager opening the APK. Return and select **Install**. +3. Open Message487 once. You can then revoke the installation permission from that + browser/file manager; it is not needed for forwarding. + +The app requires Android 8.0 or newer. Use the APK attached to the project release, +not a repackaged copy. Release assets include `SHA256SUMS` for checking file integrity. +Menu names vary by Android version and manufacturer. + +## Identify the blocking screen + +| What you see | Next step | +| --- | --- | +| Installation from this source is not allowed | Grant the browser/file manager permission as above | +| Play Protect suggests scanning an unknown app | Run the offered scan and follow its result | +| Play Protect blocks installation because the app requests sensitive data | Read the Play Protect section below | +| The app is installed, but notification access says “Restricted setting” | Allow restricted settings for Message487 as described below | +| A warning specifically mentions an unverified developer | Follow Google's [developer verification instructions](https://support.google.com/android/answer/17588095?hl=en); this is a separate check | +| Installation/settings are controlled by an administrator | Contact the device or work-profile administrator | + +## Play Protect blocks installation + +Message487 receives new SMS (`RECEIVE_SMS`) and can read other apps' notifications +through a notification listener. These capabilities are necessary for forwarding, +but also appear in Google's sensitive-permission installation checks for apps downloaded +from the internet. Such a warning can therefore be related to these permissions; +it does not establish the exact cause of a particular block. Google also distinguishes +this warning from a harmful-app detection. See [Google's warning descriptions](https://developers.google.com/android/play-protect/warning-dev-guidance). + +Expand the warning details and check the exact wording. If Android offers an explicit +option to proceed, review it and use it only for an APK whose source you trust. Some +blocks offer no such option. Granting “Allow from this source” or “Allow restricted +settings” does not resolve every Play Protect block. This guide does not require +turning off Play Protect globally. + +If installation stays blocked, report the release version, phone model, Android version +and exact warning in [Issues](https://github.com/andre487/AndroidMessage487/issues), with +personal information removed. The developer can investigate and, where appropriate, +[appeal the classification](https://developers.google.com/android/play-protect/warning-dev-guidance#appeals). +Installation through ADB is another supported Android installation method for your own +device; it is not a guarantee that device policy or security checks will permit the APK. + +## Installed app: allow restricted settings + +On Android 13 and later, sensitive settings for an app installed from an APK may be +restricted. Only enable this access if you trust the app and intend to forward the data. + +1. Open Android **Settings → Apps → See all apps → Message487**. +2. Open the **⋮** menu and select **Allow restricted settings**. Complete the system confirmation. +3. Return to Message487 **Sources**, enable notification forwarding and open the system + notification-access screen. Select Message487 and allow access, then select source apps + in Message487. + +These steps follow [Google's restricted-settings guide](https://support.google.com/android/answer/12623953?hl=en). +If the menu is absent, first check whether notification access is actually blocked and +whether you are on Message487's app-info page. Availability and names depend on the device; +consult the manufacturer's instructions or the administrator if it remains unavailable. + +**Notification access** lets Message487 receive other apps' notifications. The ordinary +**Notifications / Allow notifications** switch only controls an app's own notifications. +Message487 does not need an Accessibility service or device-administrator access. + +Enable **SMS** separately in Message487 **Sources** and grant SMS permission when prompted. +There is no need to make Message487 the default SMS app. Android can still redact sensitive +notification content; allowing restricted settings does not guarantee access to one-time codes. +See [Privacy](../../PRIVACY.md) for what is stored and forwarded. + +## Install from a computer with ADB + +1. Download the release APK to your own computer and install Google's + [SDK Platform Tools](https://developer.android.com/tools/releases/platform-tools). +2. Enable **Developer options → USB debugging** on your phone, connect it by USB, + unlock it and approve this computer's debugging authorization. +3. In the Platform Tools directory, run the following, replacing the APK path: + +```sh +adb devices +adb install -r /path/to/message487-VERSION.apk +``` + +Use `./adb` if the tool is not on your PATH, or `adb.exe` on Windows. If multiple devices +are listed, add `-s SERIAL` before `install`. The `-r` option updates an existing installation +while keeping its data, provided the package/signature and version are compatible. +Open the app and grant forwarding permissions through its interface. Afterwards, turn off +USB debugging and revoke debugging authorizations if no longer needed. +These steps use [Android's documented ADB installation flow](https://developer.android.com/tools/adb#move). + +## Update and check delivery + +Install a newer signed release APK over the existing app. If Android reports a signature +conflict, check whether you previously installed a debug build or a different APK. +Do not uninstall as the first fix: uninstalling deletes settings, keys and queued events. + +Continue with [n8n setup](n8n-webhook.md), send a test and verify **Journal** and n8n +**Executions**. Then test a new notification or SMS. Granting permissions does not replay +old messages. Release 0.0.1 predates Bearer authentication; follow the release notes and +use a release that includes authentication for a protected webhook. diff --git a/docs/en/n8n-webhook.md b/docs/en/n8n-webhook.md index 1171e1b..131e47d 100644 --- a/docs/en/n8n-webhook.md +++ b/docs/en/n8n-webhook.md @@ -2,6 +2,8 @@ [English](../en/n8n-webhook.md) | [Русский](../ru/n8n-webhook.md) +Installing on a phone? See [APK installation and Android restrictions](apk-installation.md). + This guide targets the development version with Bearer authentication (not release 0.0.1). You need the n8n editor and an HTTPS endpoint reachable from your phone. For a local Android emulator, use the debug build and [DevServer](../../DevServer/README.md). Release APKs reject HTTP endpoints. diff --git a/docs/en/releases.md b/docs/en/releases.md index 54e5d05..b8a991a 100644 --- a/docs/en/releases.md +++ b/docs/en/releases.md @@ -2,6 +2,8 @@ [English](../en/releases.md) | [Русский](../ru/releases.md) +Installing on a phone? See [APK installation and Android restrictions](apk-installation.md). + Run `bundle exec fastlane android release_artifacts` with JDK 21 and Android SDK 36. The lane runs Android JVM/Compose tests, debug/release lint and a signed release build, then checks the certificate, package ID, version and non-debuggable flag. Outputs are `dist/release/message487-.apk`, diff --git a/docs/ru/apk-installation.md b/docs/ru/apk-installation.md new file mode 100644 index 0000000..4f46c72 --- /dev/null +++ b/docs/ru/apk-installation.md @@ -0,0 +1,110 @@ +# Установка Message487 из APK + +[English](../en/apk-installation.md) | [Русский](../ru/apk-installation.md) + +## Скачать и установить + +1. Откройте на телефоне [GitHub Releases проекта](https://github.com/andre487/AndroidMessage487/releases). + Выберите релиз, прочитайте его описание и скачайте `message487-<версия>.apk` из раздела + **Assets**. Архивы исходников и `mapping.txt` устанавливать не нужно. +2. Откройте скачанный APK. Если Android запрещает установку из этого источника, нажмите + **Настройки** в диалоге и включите **Разрешить установку из этого источника** для + браузера или файлового менеджера, которым открыли файл. Вернитесь и нажмите **Установить**. +3. Один раз откройте Message487. После установки разрешение для браузера или файлового + менеджера можно отозвать: для пересылки сообщений оно не требуется. + +Нужен Android 8.0 или новее. Используйте APK из релиза проекта, а не перепакованную копию. +В Assets также есть `SHA256SUMS` для проверки целостности файлов. Названия пунктов меню +зависят от версии Android и производителя телефона. + +## Определить, что именно заблокировано + +| Что показывает Android | Что делать | +| --- | --- | +| Установка из этого источника запрещена | Выдать разрешение браузеру или файловому менеджеру, как описано выше | +| Play Protect предлагает проверить неизвестное приложение | Выполнить предложенную проверку и следовать её результату | +| Play Protect блокирует установку из-за доступа к конфиденциальным данным | Прочитать раздел о Play Protect ниже | +| Приложение установлено, но доступ к уведомлениям недоступен из-за ограниченной настройки | Разрешить доступ к настройкам для Message487 по инструкции ниже | +| Предупреждение прямо говорит о непроверенном разработчике | Следовать [инструкции Google о проверке разработчиков](https://support.google.com/android/answer/17588095?hl=ru); это отдельная проверка | +| Установка или настройки запрещены администратором | Обратиться к администратору устройства или рабочего профиля | + +## Play Protect блокирует установку + +Message487 получает новые SMS (`RECEIVE_SMS`) и может читать уведомления других приложений +через службу прослушивания уведомлений. Эти возможности нужны для пересылки, но также +учитываются проверками Google для приложений, скачанных из интернета и запрашивающих +чувствительные разрешения. Поэтому предупреждение может быть связано с ними; точную +причину конкретной блокировки по одному факту отказа определить нельзя. Google отдельно +описывает такое предупреждение и обнаружение вредоносного приложения. +См. [описания предупреждений Google](https://developers.google.com/android/play-protect/warning-dev-guidance). + +Откройте подробности предупреждения и проверьте его точный текст. Если Android предлагает +явную возможность продолжить установку, изучите её и используйте только для APK, +источнику которого доверяете. Некоторые блокировки не предлагают такого действия. +Разрешение установки из источника или доступа к ограниченным настройкам не снимает +любую блокировку Play Protect. Эта инструкция не требует глобально отключать Play Protect. + +Если установка остаётся заблокированной, сообщите версию релиза, модель телефона, +версию Android и точный текст предупреждения в [Issues](https://github.com/andre487/AndroidMessage487/issues), +убрав личные данные. Разработчик сможет проверить причину и при необходимости +[оспорить классификацию](https://developers.google.com/android/play-protect/warning-dev-guidance#appeals). +Для своего устройства также можно использовать штатную установку через ADB с компьютера; +она не гарантирует, что политика устройства или проверки безопасности разрешат APK. + +## Приложение установлено: разрешить доступ к настройкам + +На Android 13 и новее доступ к чувствительным настройкам приложения, установленного из APK, +может быть ограничен. Разрешайте его, только если доверяете приложению и хотите пересылать данные. + +1. Откройте системные **Настройки → Приложения → Все приложения → Message487**. +2. Нажмите **⋮ → Разрешить доступ к настройкам** (в некоторых переводах — + **Разрешить ограниченные настройки / Allow restricted settings**). Пройдите системное подтверждение. +3. Вернитесь в **Источники** Message487, включите пересылку уведомлений и откройте системный + экран доступа к уведомлениям. Выберите Message487 и разрешите доступ, затем выберите + приложения-источники в Message487. + +Порядок снятия ограничения приведён в [справке Google](https://support.google.com/android/answer/12623953?hl=ru). +Если пункта меню нет, сначала проверьте, действительно ли доступ заблокирован и открыты ли +сведения именно о Message487. Наличие и названия пунктов зависят от устройства; если настройка +недоступна, сверьтесь с инструкцией производителя или обратитесь к администратору. + +**Доступ к уведомлениям** позволяет получать уведомления других приложений. Обычный +переключатель **Уведомления / Разрешить уведомления** управляет показом собственных +уведомлений приложения. Message487 не требует службы специальных возможностей +или прав администратора устройства. + +Для SMS отдельно включите **SMS** в **Источниках** Message487 и выдайте разрешение по запросу. +Назначать Message487 приложением SMS по умолчанию не требуется. Android всё равно может +скрывать чувствительное содержимое уведомлений: снятие ограничения не гарантирует доступ +к одноразовым кодам. О хранении и пересылке данных — в [политике конфиденциальности](../../PRIVACY.md). + +## Установить с компьютера через ADB + +1. Скачайте APK релиза на свой компьютер и установите + [SDK Platform Tools от Google](https://developer.android.com/tools/releases/platform-tools). +2. На телефоне включите **Для разработчиков → Отладка по USB**, подключите его кабелем, + разблокируйте экран и подтвердите разрешение отладки для этого компьютера. +3. В каталоге Platform Tools выполните команды, заменив путь к APK: + +```sh +adb devices +adb install -r /path/to/message487-VERSION.apk +``` + +Если инструмент не добавлен в PATH, используйте `./adb`, а на Windows — `adb.exe`. +При нескольких подключённых устройствах добавьте `-s SERIAL` перед `install`. +Ключ `-r` обновляет установленное приложение с сохранением данных, если совместимы +пакет, подпись и версия. Откройте приложение и выдайте разрешения пересылки через его +интерфейс. После установки отключите отладку по USB и отзовите разрешения отладки, +если больше ими не пользуетесь. Основа шагов — [официальная инструкция ADB](https://developer.android.com/tools/adb#move). + +## Обновить приложение и проверить доставку + +Устанавливайте APK нового подписанного релиза поверх существующего приложения. Если +Android сообщает о конфликте подписи, проверьте, не была ли установлена debug-сборка +или другой APK. Не начинайте с удаления: оно стирает настройки, ключи и события в очереди. + +Продолжите по [инструкции n8n](n8n-webhook.md), отправьте тест и проверьте **Журнал** +и **Executions** в n8n. Затем проверьте новое уведомление или SMS. Выдача разрешений +не пересылает старые сообщения. Релиз 0.0.1 выпущен до добавления Bearer-авторизации; +для защищённого веб-хука нужен релиз с её поддержкой — сверяйтесь с описанием релиза. diff --git a/docs/ru/n8n-webhook.md b/docs/ru/n8n-webhook.md index a5ef0b8..56c0b7b 100644 --- a/docs/ru/n8n-webhook.md +++ b/docs/ru/n8n-webhook.md @@ -2,6 +2,8 @@ [English](../en/n8n-webhook.md) | [Русский](../ru/n8n-webhook.md) +Для установки на телефон см. [инструкцию по APK и ограничениям Android](apk-installation.md). + Инструкция для разрабатываемой версии с Bearer-авторизацией (не для релиза 0.0.1). Нужен доступ к редактору n8n и HTTPS-адрес, доступный с телефона. Для локального Android-эмулятора используйте debug-сборку и [готовый DevServer](../../DevServer/README.md). Релизный APK не принимает HTTP-адреса. diff --git a/docs/ru/releases.md b/docs/ru/releases.md index cb4b5e4..c8099ec 100644 --- a/docs/ru/releases.md +++ b/docs/ru/releases.md @@ -2,6 +2,8 @@ [English](../en/releases.md) | [Русский](../ru/releases.md) +Для установки на телефон см. [инструкцию по APK и ограничениям Android](apk-installation.md). + Запустите `bundle exec fastlane android release_artifacts` с JDK 21 и Android SDK 36. Lane выполняет JVM/Compose-тесты, debug/release lint и подписанную release-сборку, затем проверяет сертификат, package ID, версию и отсутствие debug-флага. Результаты: