Files
optiqscale-apps/README.md
T

129 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OptiqScale: APKs para Android
Os aplicativos do OptiqScale para instalar **fora da loja**, enquanto o app não está na Play Store.
Cada versão publicada aparece em [Releases](https://gitea.gobyz.com/giovane.barcelos/optiqscale-apps/releases),
com as notas do que mudou e dois arquivos:
| Arquivo | App no celular | Fala com | Para quê |
|---|---|---|---|
| `optiqscale-prd-X.Y.Z.apk` | **OptiqScale** | produção (`api.optiqscale.com`) | o app de verdade, com dados reais |
| `optiqscale-stg-X.Y.Z.apk` | **OptiqScale Staging** | homologação (`stg.api.optiqscale.gobyz.com`) | testar a versão nova sem mexer em dados reais |
Os dois têm identificadores diferentes (`com.optiqscale.app` e `com.optiqscale.app.stg`), então podem ficar
instalados **lado a lado**. Os dados de homologação podem ser apagados e recriados a qualquer momento.
Há dois tipos de release:
- **Versão** (`v0.2.0`, por exemplo): fechada e conferida.
- **Prévia** (`v0.1.0-dev.142`, marcada como *Pre-release*): o estado atual do desenvolvimento, para testar
antes. Pode ter falhas.
Requisito: **Android 7.0 ou mais novo**. Para iPhone, o app sai pelo TestFlight da Apple (convite de quem mantém
o projeto); não há instalação de iPhone por aqui.
> Este repositório só guarda os instaláveis. O código do OptiqScale é privado.
## Jeito 1: com o Obtainium (recomendado, atualiza sozinho)
O [Obtainium](https://github.com/ImranR98/Obtainium) é um app gratuito e de código aberto que faz o papel de
"loja": acompanha esta página, avisa quando sai versão nova, mostra as notas e instala com um toque.
### Instalar o Obtainium
1. No celular, abra a página de releases do Obtainium:
<https://github.com/ImranR98/Obtainium/releases/latest>.
2. Baixe o arquivo `app-arm64-v8a-release.apk` (a maioria dos celulares). Se a instalação falhar, use o
`app-release.apk`, que serve para todos.
- O Obtainium também está no [F-Droid](https://f-droid.org/packages/dev.imranr.obtainium.fdroid/) e no
[IzzyOnDroid](https://apt.izzysoft.de/fdroid/index/apk/dev.imranr.obtainium).
3. Abra o arquivo baixado. Na primeira vez, o Android pede para **permitir instalar apps desta fonte** (o
navegador ou o gerenciador de arquivos): permita e volte.
4. Abra o Obtainium e aceite as notificações (é por elas que chega o aviso de versão nova).
### Adicionar o OptiqScale no Obtainium
Faça uma vez para cada app que quiser (produção, homologação ou os dois).
1. Toque em **Add** (canto de baixo).
2. Em **App source URL**, cole: `https://gitea.gobyz.com/giovane.barcelos/optiqscale-apps/releases`
3. Deixe **Override source** em **None**: o Obtainium reconhece a página sozinho e mostra
"Additional options for HTML".
4. Em **Custom APK link filter by regular expression**, escreva:
| App | Filtro |
|---|---|
| OptiqScale (produção) | `optiqscale-prd-[^/]*\.apk` |
| OptiqScale Staging (homologação) | `optiqscale-stg-[^/]*\.apk` |
5. Para receber também as **prévias**, ligue **Include prereleases**. Desligado, só as versões fechadas.
6. O resto fica como está. Volte ao topo e toque no **+** ao lado da URL.
7. Na tela do app, toque em **Install**:
- na primeira vez, o Android pede para permitir que o **Obtainium** instale apps: ative e volte;
- o **Google Play Protect** avisa que não conhece o app e recomenda uma análise: toque em **Scan app** e,
quando disser que o app parece seguro, em **Install**.
Opcional, para mais segurança: em **Expected signing certificate hashes**, cole a impressão digital da seção
[Assinatura](#assinatura). Assim o Obtainium recusa um APK que não tenha sido assinado pela chave do OptiqScale.
### Atualizar
O Obtainium confere a página de tempos em tempos e manda uma notificação quando sai versão nova. Toque em
**Atualizar**; as notas da versão aparecem antes. Para conferir na hora, puxe a lista para baixo.
## Jeito 2: download direto (sem atualização automática)
1. No celular, abra [Releases](https://gitea.gobyz.com/giovane.barcelos/optiqscale-apps/releases).
2. Na versão mais recente (a primeira da lista), toque no APK que quiser (`prd` ou `stg`).
3. Abra o arquivo baixado e permita **instalar apps desta fonte** quando o Android pedir.
Para atualizar, repita: o Android instala a versão nova por cima e mantém os seus dados (e o login).
## Versões
- O número segue o [Versionamento Semântico](https://semver.org/lang/pt-BR/): `MAJOR.MINOR.PATCH`.
- Prévias levam `-dev.N` no fim, e o `N` só cresce.
- O Android só aceita atualizar para uma versão **mais nova**. Prévias e versões seguem uma única sequência, então
dá para passar de uma para a outra. Para voltar a uma versão anterior, desinstale e instale a antiga (os dados
locais do app se perdem; os da sua conta ficam no servidor).
## Assinatura
Todos os APKs são assinados com a mesma chave. É ela que permite instalar uma versão por cima da outra. A
impressão digital do certificado (SHA-256) é:
```
80:E0:CE:4A:D2:F7:FA:86:FB:FD:E6:CC:48:8F:83:79:F0:46:1B:EE:89:F4:8B:B0:E3:25:7E:86:F8:38:58:4C
```
Para conferir um APK no computador (com o Android SDK): `apksigner verify --print-certs optiqscale-X.Y.Z.apk`.
## Verificação de desenvolvedores do Google
Em **2027**, o Google passa a exigir desenvolvedor registrado para instalar qualquer app em celular Android
certificado. App de desenvolvedor não registrado só instala por um "fluxo avançado" (modo de desenvolvedor, uma
espera de 24 h e um aviso de "desenvolvedor não verificado") ou por ADB. O OptiqScale vai registrar o pacote antes
disso. Detalhes: [Android developer verification](https://developer.android.com/developer-verification).
## Problemas comuns
| Sintoma | O que fazer |
|---|---|
| "App não instalado" ou "conflito com pacote existente" | O app instalado foi assinado com outra chave (uma versão de desenvolvimento, por exemplo). Desinstale o OptiqScale e instale de novo. |
| "Instalação bloqueada" / "fonte desconhecida" | Permita instalar apps da fonte que pediu (navegador, gerenciador de arquivos ou Obtainium) em Configurações › Apps › Acesso especial › Instalar apps desconhecidos. |
| O Obtainium não acha versão nova | Confira a URL e o filtro de APK. Se a versão nova é uma prévia, ligue **Include prereleases**. |
| O app abre, mas não entra | Confira a internet. Se persistir, pode ser manutenção do servidor: tente mais tarde. |
| Instalei a prévia `v0.1.0-dev.53` | Ela saiu antes da homologação, com um arquivo só (`optiqscale-0.1.0-dev.53.apk`, produção). Troque o filtro do Obtainium para o de produção da tabela acima; a atualização instala por cima. |
## Para quem publica
O APK sai do repositório do projeto:
```bash
./scripts/publish-apks.sh X.Y.Z # versão fechada (tag vX.Y.Z)
./scripts/publish-apks.sh --dev # prévia do commit atual (stg e prd)
```
O script compila, assina com a chave de release (que fica fora do Git), confere a assinatura e cria o release
aqui. A chave de assinatura **não pode se perder**: sem ela, nenhuma versão nova atualiza as instaladas, e todo
mundo precisa desinstalar e instalar de novo.