zebian.

Projeto · em curso

Uma app para o Bola na Rede, sem pagar a ninguém

Fiz uma app mobile para o site Bola na Rede e montei um sistema de push notifications self-hosted. Sem Firebase pago, sem OneSignal, sem mensalidades. Conto como, e o que partiu pelo caminho.

O Bola na Rede é um site de desporto português, em WordPress, com público real. Há meses que andava na conversa transformar aquilo numa app, mas o caminho normal (OneSignal a cobrar acima de X subscritores, Firebase a empurrar para o plano pago) não fazia sentido para o que se queria. Decidi pegar nisso e montar tudo em casa, do zero, sem terceiros pagos.

A regra que me dei foi simples: zero custos mensais para o servidor, zero custos por notificação enviada, zero dependências de empresas que possam mudar os preços amanhã. As únicas contas que paguei são as obrigatórias: 99€/ano à Apple quando chegar a altura do iOS, e 25€ uma vez à Google para publicar na Play Store.

O que eu queria que a app fosse

Não queria reinventar o site. O conteúdo está no WordPress, escrito e atualizado por quem percebe, e o tema (tagDiv Newspaper) já está montado. Fazer uma app nativa que consome a API do WP era trabalho de meses só para chegar ao ponto onde já estávamos.

Decidi por uma WebView com casca à volta. A app carrega o site direto, mas com personalidade própria:

  1. Barra de separadores em baixo, ao estilo das apps nativas, com cinco temas: Atualidade, Nacional, Internacional, Modalidades e Especial. Cada um abre um popup com submenus.
  2. Botão flutuante de notificações, para escolher os clubes e competições que se quer seguir.
  3. Sem o menu hambúrguer nem o cabeçalho do site: a app esconde-os, porque já está a oferecer navegação própria.
  4. Push notifications nativas: quando se publica um artigo, quem subscreveu Sporting recebe; quem subscreveu Benfica recebe; quem só subscreveu Última Hora, só recebe se for marcado como tal.

Para o utilizador, parece uma app. Por dentro, é o site de sempre com uma capa em cima.

A stack

PeçaTecnologia
AppCapacitor 8 (Android primeiro, iOS depois)
WebViewCarrega bolanarede.pt direto
Base de dadosSupabase (PostgreSQL grátis)
Servidor de envioVercel serverless functions
Push AndroidFirebase Cloud Messaging (grátis, ilimitado)
Push iOSAPNs (incluído na conta Apple Developer)
Plugin WordPressPHP custom, escrito de raiz

O servidor de push corre em Vercel, é stateless, e a base de dados está em Supabase. Tudo no plano gratuito.

Como a app sabe que é uma app

Este é o truque que faz tudo encaixar. O Capacitor manda um User-Agent personalizado, com a string BnRApp/1.0 no fim. O WordPress vê isso e, se for BnRApp, faz três coisas:

  1. Acrescenta a classe bnr-app-mode ao <body>.
  2. Injeta CSS que esconde o cabeçalho, o menu hambúrguer, o rodapé, e qualquer header sticky do tema.
  3. Injeta no footer: a tab bar inferior, o botão de notificações, e o modal de subscrições.

Quem visita o site no browser não vê nada disto. Quem visita pela app vê uma “skin” diferente, mas continua a navegar nos mesmos URLs do WordPress.

A escolha foi feita assim porque o JavaScript bridge do Capacitor não funciona bem dentro de um iframe, e tentei essa via primeiro. O site tem o header X-Frame-Options: SAMEORIGIN, que impede o iframe; e mesmo desligando esse header (perigoso, abre o site a clickjacking), o bridge nativo do Capacitor para pedir permissões de notificação não chegava ao iframe. WebView direta + plugin a injetar foi a solução limpa.

O servidor de push

São quatro endpoints serverless em Vercel:

  • POST /api/subscribe: a app envia o token FCM/APNs do dispositivo, mais a lista de tópicos. Guarda em Supabase.
  • POST /api/unsubscribe: para desativar.
  • GET /api/topics: lista os tópicos disponíveis.
  • POST /api/send: o WordPress chama isto quando se quer enviar uma notificação. Recebe {topics, title, body, url, image}, faz SELECT DISTINCT para todos os tokens subscritos a esses tópicos (deduplicação fundamental: se o artigo for sobre Última Hora + Benfica, quem subscreveu os dois recebe uma notificação, não duas), e envia em batch via FCM.

O envio é manual. Decidi não automatizar a partir das categorias do WordPress por uma razão prática: nem todos os artigos merecem push. Quem escreve quer poder decidir caso a caso. Por isso adicionei uma meta box ao editor de posts, com dez checkboxes (os dez tópicos) e um botão “Enviar Push Agora”. Quando se carrega, o WordPress chama o servidor, o servidor envia, e regista no log do plugin.

Os tópicos são: Última Hora, Sporting, Benfica, FC Porto, Primeira Liga, Futebol Internacional, Modalidades, Opinião, Entrevista BnR, Podcasts BnR. Hardcoded, propositadamente. Quis ter controlo absoluto sobre que tópicos existem, em vez de depender das categorias e tags do WordPress mudarem por trás.

O que correu mal

O Cloudflare a servir cache

Levei demasiado tempo a perceber isto. A primeira versão do plugin estava bem escrita, mas quando abria a app, o menu inferior não aparecia. Pensei que era o User-Agent que não estava a chegar. Pensei que era o tema a comer o footer. Era nenhuma destas: era o Cloudflare a servir uma versão cacheada da página, gerada quando alguém antes tinha visitado em browser normal. A página cacheada não tinha o User-Agent da app, portanto não tinha o shell injetado.

A solução foi adicionar headers no PHP, quando deteta o User-Agent da app:

if (!defined('DONOTCACHEPAGE')) define('DONOTCACHEPAGE', true);
header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
header('CDN-Cache-Control: no-store');

DONOTCACHEPAGE diz ao WP Rocket para não cachear. CDN-Cache-Control: no-store diz ao Cloudflare para nunca servir cache neste pedido. Funcionou ao primeiro.

As Supabase keys

A documentação nova do Supabase mostra as chaves no formato sb_secret_.... Liguei isso ao cliente JavaScript do Supabase (versão 2) e dava sempre erro de autenticação. Demorou a perceber que o cliente v2 ainda espera as chaves legacy em formato JWT (eyJ...). Estão escondidas num separador chamado “Legacy anon, service_role API keys” no dashboard. Não é óbvio.

O Vercel a recusar o módulo

Configurei o TypeScript com "module": "ESNext" (que é o que uso para projetos novos). O Vercel compila os ficheiros para JavaScript, mas trata-os como CommonJS no runtime. Resultado: erro Cannot use import statement outside a module em todas as funções. Mudei para "module": "CommonJS" no tsconfig.json e tudo correu.

O ícone das notificações em cima do menu

A primeira versão tinha o sino no canto superior direito. Funcionava no preview, mas no telemóvel ficava por cima do menu hambúrguer do site (sim, o CSS não estava a esconder o cabeçalho mobile do tagDiv como eu pensava). Mudei a posição para o canto inferior esquerdo, em FAB (Floating Action Button), exatamente onde o CookieYes punha o botão de “rever consentimento” (que escondi na app, porque não fazia sentido). Ficou limpo, vermelho da cor BnR, e ninguém colide com ninguém.

A casa do Java

Build do APK no terminal: o Capacitor 8 quer Java 21, mas o macOS por default não tem nenhum Java. Instalei openjdk@21 via Homebrew, exportei JAVA_HOME, e finalmente o gradlew assembleDebug correu. Coisa simples mas que ninguém te avisa.

O que está feito

O APK está a correr no telemóvel de quem está a testar. A tab bar funciona. Os submenus abrem. O botão de notificações abre o modal, deixa escolher tópicos, e regista o token no Supabase. O plugin do WordPress envia push para o servidor. Tudo encaixa.

O Android está pronto para Play Store quando se decidir publicar.

O que falta

  1. iOS. Espera por uma conta Apple Developer. Quando chegar, gera-se a chave .p8 no Apple Developer Portal e meia hora depois está o APNs ligado.
  2. Polimento visual: splash screen e ícone próprios. Por agora está com placeholders.
  3. Monitorização: ligar alguma coisa simples para saber quando o servidor está em baixo, e limpar tokens inválidos com um cron.
  4. Publicação: Play Store primeiro, App Store depois.

O custo real

Para terem ideia, este é o custo mensal:

  • Servidor de push: 0€ (Vercel free)
  • Base de dados: 0€ (Supabase free)
  • Push Android: 0€ (FCM)
  • Push iOS: 0€ (incluído na conta Apple)

Total mensal: zero. Para um site com público real, a enviar notificações a centenas ou milhares de subscritores. Comparem com OneSignal a partir do tier 10.000 subscritores, ou com qualquer fornecedor que cobra por notificação enviada.

Não é magia. É juntar três serviços gratuitos (Vercel, Supabase, Firebase) e escrever a cola que falta entre eles. A cola é o que dá trabalho, mas é uma vez só.

Aprendi o quê

Que esconder um cabeçalho de um tema WordPress é um exercício de paciência: o tagDiv Newspaper não usa <header>, usa divs com classes geradas (td-header-mobile-sticky-wrap, tdb_header_logo, tdc-zone). Para esconder tudo é preciso varrer com seletores genéricos [class*="td-header"] ou estar disposto a actualizar quando o tema mudar.

Que o User-Agent ainda é uma ferramenta legítima e simples para diferenciar contextos, quando se controla os dois lados (a app e o servidor). Não precisa de cookies, não precisa de query strings, não precisa de fingerprinting.

E que a parte mais difícil destas integrações nunca é a tecnologia em si. É perceber porque é que não está a funcionar quando todos os pedaços individuais funcionam. No caso, foi o Cloudflare. No teu próximo, será outra coisa.