push_service_client 0.1.0

Cliente Flutter para o Push Service — regista devices e recebe push notifications (FCM/APNs).

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
• 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. 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
);

4. 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.