push_service_client

Cliente Flutter completo para o Push Service — a plataforma de push notifications. O pacote trata de tudo: inicializa o Firebase, pede permissões, obtém o token FCM/APNs, regista o device no serviço e liga os listeners para receber notificações.

Funcionalidades

  • initialize() — tudo num passo: Firebase + permissões + token + registo do device + listeners
  • Registo de device (upsert por player_id) com metadados e tags
  • Associar o device ao utilizador (setExternalId/clearExternalId) — login/logout estilo OneSignal
  • Subscribe / Unsubscribe — ativar ou desativar notificações no device
  • Envio de pushes — imediato ou agendado, com segmentos (plataforma, país, idioma, tags)
  • Listar e consultar pushes — estado e estatísticas de envio
  • Re-registo automático quando o token FCM é atualizado
  • Handlers de notificação — callbacks para push aberto/recebido

Instalação

Distribuição privada: este pacote é distribuído por ti aos teus clientes (download no site ou partilha direta). Não está em registos públicos.

1. Adiciona o pacote

Se o cliente tem acesso à pasta do pacote (extraída do zip disponibilizado):

dependencies:
  push_service_client:
    path: lib/push_service_client

Ou aponta diretamente para a pasta do projeto (se partilhada):

dependencies:
  push_service_client:
    path: ../push_service_client

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/.
  • Web: configura o Firebase no ficheiro firebase_options.dart (ou passa as opções ao initialize).

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

Utilização

1. Configura

Cria um token da API no painel do Push Service (Aplicações → API → Criar token) e obtém o slug da app.

A URL do servidor (https://push.michelmelo.pt/api/v1) está fixa no pacote — só precisas do token e do slug da app.

final push = PushService(
  apiToken: 'SEU_TOKEN_DA_API',
  appId: 'slug-da-tua-app',
);

2. Inicializa (faz tudo)

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

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

  final push = PushService(
    apiToken: 'SEU_TOKEN_DA_API',
    appId: 'slug-da-tua-app',
  );

  await push.initialize(
    externalId: 'user-42',            // opcional
    country: 'PT',                    // opcional
    language: 'pt',                   // opcional
    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
    },
  );

  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. Regista o device no Push Service.
  5. Liga os listeners (foreground, background, aberta, token atualizado).

Quando o token FCM for atualizado, o pacote re-regista automaticamente o device.

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, para poderes enviar pushes a um utilizador específico (em todos os devices dele) e manter a identidade entre reinstalações.

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

No logout (ou para desassociar), chama clearExternalId — o device volta a ser anónimo mas mantém o resto dos dados (país, modelo, tags, etc.).

await push.clearExternalId();          // após o logout

Estas chamadas são idempotentes e seguras para repetir. Se a app abrir com uma sessão restaurada, passa o mesmo ID no initialize(externalId: ...).

4. Envia um push (opcional)

await push.sendPush(
  title: 'Olá!',
  body: 'Mensagem de teste',
  segment: {'platforms': ['android']},
  sendAt: DateTime.now().add(const Duration(hours: 1)), // agenda — opcional
);

5. Desativa notificações

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

Tratamento de erros

Todas as chamadas lançam PushServiceException em caso de erro (token inválido, app não encontrada, validação, rate limit, permissão negada, Firebase):

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.