push_service_client

Cliente Flutter para o Push Service — plataforma de push notifications estilo OneSignal. O pacote trata de tudo: inicializa o Firebase, pede permissões, obtém o token FCM/APNs, captura sozinho os dados do device (modelo, versões de app/SO, idioma, fuso horário), regista-o no serviço e liga os listeners para receber notificações.

O developer não precisa de saber qual é o token correto nem de embutir segredos na app. Só precisa do App ID público e de guardar o subscriptionId devolvido — é esse o id que o backend dele usa para enviar pushes.

Funcionalidades

  • initialize() — faz tudo: Firebase + permissões + token + captura automática + registo + listeners
  • Captura automática: modelo, versão do SO, versão da app, idioma e fuso horário (IANA)
  • subscriptionId (UUID estável) — o identificador público para enviar pushes
  • Associar o device ao utilizador (setExternalId/clearExternalId) — login/logout estilo OneSignal
  • Subscribe / Unsubscribe / trackActivity — endpoints públicos, sem token
  • Envio de pushes — para devices: concretos ou segmentos (requer REST key)
  • Re-registo automático quando o token FCM é atualizado
  • Handlers de notificação — callbacks para push aberto/recebido

Instalação

O pacote está publicado no pub.dev.

1. Adiciona o pacote

No pubspec.yaml do teu projeto:

dependencies:
  push_service_client: ^1.0.0

Depois corre:

flutter pub get

2. Configura o Firebase

O pacote usa firebase_core e firebase_messaging (já incluídos como dependências).

  • Android: adiciona o ficheiro google-services.json (da consola Firebase) em android/app/ e o plugin com.google.gms.google-services no android/build.gradle.
  • iOS: adiciona o ficheiro GoogleService-Info.plist em ios/Runner/.

Consulta o guia oficial do Firebase Flutter para os passos detalhados.

Utilização

1. Configura

Obtém o App ID público da app no painel do Push Service (Aplicações → API → App ID). É um UUID não secreto — pode ir dentro da app. O servidor (https://push.michelmelo.pt) está fixo no pacote.

final push = PushService(
  appId: 'uuid-publico-da-tua-app',   // NÃO é um token — é público
);

2. Inicializa (faz tudo)

No main() (antes do runApp) ou no initState do widget raiz:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final push = PushService(appId: 'uuid-publico-da-tua-app');

  final device = await push.initialize(
    externalId: 'user-42',            // opcional — id do user na tua app
    tags: {'tier': 'vip'},            // opcional
    onOpened: (notification) {
      // utilizador tocou na notificação
      final url = notification.data['url'];
    },
    onReceived: (notification) {
      // notificação chegou com a app em primeiro plano
    },
  );

  // ⬇ IMPORTANTE — guarda no teu backend:
  // device.subscriptionId é o id estável deste device. É o que o teu servidor
  // envia na REST API para lhe mandar pushes. Nunca uses o token FCM/APNs.
  await meuBackend.guardarSubscriptionId(device.subscriptionId);

  runApp(MyApp(push: push));
}

O initialize:

  1. Inicializa o Firebase.
  2. Pede permissão de notificações.
  3. Obtém o token FCM/APNs.
  4. Captura sozinho: modelo, versão do SO, versão da app, idioma e fuso horário.
  5. Regista o device no Push Service (endpoint público).
  6. Liga os listeners (foreground, background, aberta, token atualizado).

Quando o token FCM for atualizado, o pacote re-regista automaticamente o device (o subscriptionId mantém-se o mesmo).

3. Liga o device ao utilizador (login)

Chama setExternalId depois do login/registo na tua app, com o ID do utilizador. O servidor associa o device à conta.

await push.setExternalId('user-42');   // após o login
await push.clearExternalId();          // após o logout

4. Envia pushes — do teu backend (REST API)

O envio é feito pelo teu servidor, com um token REST (secreto) criado no painel:

curl -X POST https://push.michelmelo.pt/api/v1/apps/{slug}/pushes \
  -H "Authorization: Bearer {REST_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Olá!",
    "body": "Mensagem",
    "devices": ["subscription-id-guardado-no-passo-2"]
  }'

O servidor resolve o token FCM/APNs real a partir do subscriptionId e entrega. Também podes enviar por segment (plataforma, país, idioma, tags) — mas devices e segment são mutuamente exclusivos.

5. (Opcional) Enviar a partir da app

Se quiseres que a app consiga enviar pushes diretamente, passa também o token REST (atenção: token secreto numa app móvel é um risco — para testes apenas):

final push = PushService(
  appId: 'uuid-publico-da-tua-app',
  apiToken: 'REST_KEY_OPCIONAL',   // só se a app for enviar pushes
);
await push.sendPush(
  title: 'Olá!',
  body: 'Mensagem',
  devices: ['subscription-id-1', 'subscription-id-2'],  // OU segment
);

6. Desativa notificações no device

await push.unsubscribe();   // deixa de receber pushes
await push.subscribe();     // volta a receber

Tratamento de erros

Todas as chamadas lançam PushServiceException em caso de erro:

try {
  await push.initialize();
} on PushServiceException catch (e) {
  print('${e.statusCode}: ${e.message}');
}

Exemplo completo

Vê a app de exemplo em example/.

Documentação da API

A API v1 do Push Service está documentada em https://push.michelmelo.pt/docs.

Libraries

push_service_client
Cliente Flutter para o Push Service.