Guia de Migração — Provider
Este guia cobre a atualização de qualquer versão da série 4.18.x para 4.20.16.
Guia de Migração
Este guia cobre a atualização de qualquer versão da série 4.20.x para 4.20.15, e também traz
o diff real de build/infra em relação à 4.18.0 (última tag anterior à série 4.20.x disponível
para comparação de arquivos — lembrando que 4.18.x segue como linha de release paralela, não como
predecessora estrita).
1. Como atualizar
1.1 Bump de dependência
dependencies {
implementation "com.stone.pos:sdk:4.20.16" // ajuste o group/artifact conforme seu setup atual
}
Sincronize o Gradle e recompile.
2. Breaking changes / pontos de atenção obrigatórios
2.1 Evento de "cartão removido" (fix da 4.20.11)
Antes da 4.20.11, em determinados fluxos o evento de remoção de cartão não era emitido pelo SDK
(o entry mode era setado depois do ponto em que a checagem de remoção ocorria).
Ação recomendada: se sua UI tinha algum workaround (timeout manual, polling, tela que nunca saía do estado "aguardando remoção do cartão") para compensar esse bug, remova esse workaround após migrar, e revalide o fluxo de "aguardar remoção do cartão" em testes manuais com cartão físico — o comportamento correto agora vem nativamente do SDK.
2.2 Validação de "stone code" na ativação (fix da 4.20.7)
A validação de tamanho do "stone code" durante a ativação do POS foi removida por estar incorreta/ bloqueando ativações válidas.
Ação recomendada: se seu app tinha validação própria e redundante do tamanho do stone code antes de chamar a ativação do SDK, revise-a — ela pode estar reproduzindo a mesma regra incorreta e bloqueando casos válidos que agora o SDK aceita.
3. Pontos que não exigem mudança de código, mas merecem teste manual
| Item | Versão | O que testar |
|---|---|---|
Recibo/voucher com valores decimais (Bal/Amt) | 4.20.1 | Emitir recibo de voucher com valores fracionados e conferir formatação. |
| Layout das informações do recibo | 4.20.5 | Conferir visualmente o recibo impresso/exibido em tela após transações comuns. |
| Crash em transação de voucher | 4.20.4 | Rodar fluxo completo de voucher (aprovação e reversão). |
| Abort/reversão não desfaz transação aprovada | 4.20.1 | Testar abort após aprovação online — a transação deve permanecer aprovada. |
| PIX / Instant Payment | 4.20.1 | Confirmar que não há mais persistência indevida de authorize. |
| Número de série no recibo | 4.20.1 | Verificar se o serial number aparece corretamente (não mais UNKNOWN). |
| Suporte a novos hardwares (Transire Series S / T2, D400) | 4.20.1 / 4.20.6 | Se o seu parque de terminais inclui esses modelos, validar pareamento e transação nesses devices. |
| HALs atualizados (Gertec, Positivo, Ingenico, Tectoy, Sunmi, PAL) | várias | Smoke test de transação (venda + cancelamento) nos modelos de terminal usados em produção, priorizando os fabricantes cujo HAL mudou. |
| Suporte a páginas de memória de 16KB | 4.20.1 | Relevante apenas se o app/dispositivo já roda em Android com essa configuração; validar instalação/execução normal. |
4. Checklist de migração
- Atualizar a versão do SDK para
4.20.15nobuild.gradle. - Se vier de fora da série
4.20.x(ex.:4.18.x) ou de uma versão4.20.1–4.20.11, conferir a tabela da seção 1.2 (targetSdk, AGP, Kotlin, Koin, NDK) e rodar./gradlew :app:dependenciespara checar conflitos de resolução, especialmente em Koin e Kotlin. Se seu pipeline usa apenas mirrors públicos do Android SDK, valide especificamente a resolução dondkVersion 35.0.0. - Se importa módulos do SDK individualmente, verificar necessidade de declarar
auth-gateway. - Remover workarounds relacionados a "cartão não removido"/evento de remoção não disparado.
- Remover validações duplicadas/redundantes de tamanho do "stone code" na ativação, se houver.
- Rodar smoke tests de venda, cancelamento, voucher e PIX nos modelos de terminal usados em produção (priorizando os fabricantes com HAL atualizado: Gertec, Positivo, Ingenico, Tectoy, Sunmi).
- Validar impressão/exibição de recibo (layout e valores decimais em voucher).
- Rodar regressão completa de ativação do POS.
- Publicar em ambiente de homologação antes de produção, dado o volume acumulado de fixes
(12 releases) entre a versão anterior e a 4.20.15.
5. Rollback
Como não há mudanças de schema/persistência reportadas além do timestamp (item 2.1), o rollback
para uma versão 4.20.x anterior é seguro na maioria dos casos — apenas revalide se algum dado
gerado com timestamp em milissegundos foi persistido e precisa ser lido por uma versão anterior
que espera segundos. Evite fazer rollback especificamente para 4.20.1–4.20.11, já que essas
versões contêm a regressão de libs corrigida na 4.20.15 (seção 1.2).
Jornada: Entender a SDK Android
Etapa 10 de 10