Guia de Push Notifications

Guia unificado para configuração e uso de Push Notifications em todas as plataformas suportadas pelo Dito SDK.

📋 Visão Geral

O Dito SDK suporta Push Notifications via Firebase Cloud Messaging (FCM) em todas as plataformas. Este guia fornece instruções passo a passo para configurar e usar Push Notifications em iOS, Android, Flutter e React Native.

🔥 Configuração Firebase Geral

1. Criar Projeto no Firebase Console

Acesse o Firebase Console
Crie um novo projeto ou selecione um existente
Ative o Cloud Messaging no projeto

2. Obter Credenciais

Cada plataforma requer arquivos de configuração específicos:

iOS: GoogleService-Info.plist
Android: google-services.json
Flutter/React Native: Ambos os arquivos acima

📱 Configuração por Plataforma

iOS

1. Adicionar GoogleService-Info.plist

Baixe o arquivo GoogleService-Info.plist do Firebase Console
Adicione o arquivo ao projeto Xcode
Certifique-se de que está incluído no target do app

2. Configurar Capabilities

No Xcode, selecione o target do app
Vá em Signing & Capabilities
Adicione Push Notifications
Adicione Background Modes e marque Remote notifications

3. Configurar AppDelegate

Veja o exemplo completo em iOS README.

Ordem Importante (iOS 18+):

FirebaseApp.configure()
Messaging.messaging().delegate = self
Dito.configure()

Android

1. Adicionar google-services.json

Baixe o arquivo google-services.json do Firebase Console
Adicione o arquivo ao diretório app/ do projeto
Adicione o plugin no build.gradle.kts:

plugins {
    id("com.google.gms.google-services")
}

2. Configurar FirebaseMessagingService

Veja o exemplo completo em Android README.

Flutter

1. Instalar Dependências

dependencies:
  firebase_messaging: ^14.0.0
  firebase_core: ^2.0.0

2. Configurar Plataformas Nativas

Siga as instruções de iOS e Android.

3. Inicializar Firebase

import 'package:firebase_core/firebase_core.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  runApp(MyApp());
}

React Native

1. Instalar Dependências

npm install @react-native-firebase/app @react-native-firebase/messaging

2. Configurar Plataformas Nativas

Siga as instruções de iOS e Android.

🔔 Interceptação de Notificações

O SDK intercepta automaticamente notificações do canal Dito quando o campo channel nos dados da notificação é igual a "DITO" (case-insensitive).

Como Funciona

Quando uma notificação é recebida, o SDK verifica o campo channel
Se channel == "DITO", o SDK processa a notificação automaticamente
Se channel != "DITO", a notificação é ignorada pelo SDK e deve ser processada normalmente pelo app

Payload Esperado

{
  "channel": "DITO",
  "notification": "notification-id",
  "reference": "user-reference",
  "link": "https://app.example.com/product/123",
  "log_id": "log-id",
  "notification_name": "Nome da Notificação",
  "user_id": "user-id"
}

Notas sobre deeplink:

O campo canônico no payload é link (string).
Os wrappers Flutter e React Native aceitam deeplink como alias quando você precisa montar um userInfo manualmente (por exemplo, vindo de firebase_messaging).

📊 Tracking Automático

O SDK rastreia automaticamente quando uma notificação é recebida:

iOS: Evento receive-ios-notification
Android: Evento receive-android-notification

Os eventos incluem:

Canal: "mobile"
Token do dispositivo
ID do disparo (log_id)
ID da notificação
Nome da notificação
Provedor: "firebase"
Sistema operacional

👆 Handling de Clicks

Quando o usuário clica em uma notificação, o SDK:

Registra o clique no CRM Dito
Extrai o deeplink (link) se disponível
Dispara o evento/callback exposto pela plataforma, para que o app faça navegação (ou abra navegador, etc.)

Fluxo (alto nível)

sequenceDiagram
    participant User as Usuário
    participant OS as Sistema Operacional
    participant Native as SDK Nativo
    participant Bridge as Bridge
    participant App as App

    User->>OS: Clica na notificação
    OS->>Native: Entrega a interação
    Native->>Native: Tracking do clique
    Native->>Native: Extrai link
    alt iOS_AndroidNativo
        Native->>App: Callback com link
    end
    alt Flutter
        Native->>Bridge: EventChannel
        Bridge->>App: Stream emite evento
    end
    alt ReactNative
        Native->>Bridge: EventEmitter
        Bridge->>App: Listener recebe evento
    end

Ciclo de vida (estados)

stateDiagram-v2
    [*] --> Recebida
    Recebida --> Exibida
    Exibida --> Clicada
    Exibida --> Descartada
    Clicada --> Processada
    Processada --> EventoDisparado
    EventoDisparado --> [*]
    Descartada --> [*]

Versão detalhada (com responsabilidades do SDK):

stateDiagram-v2
    [*] --> Enviada: Plataforma Dito envia
    Enviada --> Recebida: FCM entrega ao dispositivo
    Recebida --> Exibida: Sistema exibe notificação
    Exibida --> Clicada: Usuário clica
    Exibida --> Descartada: Usuário descarta
    Clicada --> Processada: SDK processa clique
    Processada --> CallbackExecutado: Callback com link
    CallbackExecutado --> Navegação: App navega
    Navegação --> [*]
    Descartada --> [*]

    note right of Recebida
        SDK rastreia evento
        receive-*-notification
    end note

    note right of Processada
        SDK extrai link
        e chama callback/evento
    end note

Decisão de processamento (payload)

flowchart TD
    Start[Notificação recebida] --> CheckChannel{channel == DITO?}
    CheckChannel -->|Não| Ignore[Ignorar no SDK]
    CheckChannel -->|Sim| Process[Processar no SDK]
    Process --> TrackReceive[Tracking de recebimento]
    TrackReceive --> TrackClick[Tracking de clique]
    TrackClick --> Emit[Disparar evento/callback]
    Ignore --> End[Fim]
    Emit --> End

Estrutura do payload (diagrama)

graph LR
    subgraph Payload[Payload FCM]
        Channel[channel: DITO]
        Notification[notification: ID]
        Reference[reference: User Ref]
        Deeplink[link: deeplink URL]
        LogID[log_id: Log ID]
        NotifName[notification_name: Nome]
        UserID[user_id: User ID]
    end

    subgraph Extracted[Dados extraídos]
        SDK[SDK processa]
    end

    subgraph Callback[Callback/evento retorna]
        DeeplinkStr[deeplink: string]
        NotifObj[notification: object]
    end

    Channel --> SDK
    Notification --> SDK
    Reference --> SDK
    Deeplink --> SDK
    LogID --> SDK
    NotifName --> SDK
    UserID --> SDK

    SDK --> DeeplinkStr
    SDK --> NotifObj

Troubleshooting (fluxo)

flowchart TD
    Start[Callback não funciona?] --> Q1{Notificação chega?}

    Q1 -->|Não| CheckFCM[Verificar configuração FCM]
    Q1 -->|Sim| Q2{SDK processa?}

    Q2 -->|Não| CheckChannel{channel == DITO?}
    Q2 -->|Sim| Q3{Callback/evento executado?}

    CheckChannel -->|Não| FixPayload[Corrigir payload da notificação]
    CheckChannel -->|Sim| CheckInit[Verificar inicialização do SDK]

    Q3 -->|Não| Q4{Plataforma?}
    Q3 -->|Sim| Q5{Link existe?}

    Q4 -->|Android| CheckListener[Verificar notificationClickListener]
    Q4 -->|iOS| CheckDelegate[Verificar callback no AppDelegate]
    Q4 -->|Flutter| CheckStream[Verificar Stream listener]
    Q4 -->|React Native| CheckSubscribe[Verificar subscription do listener]

    Q5 -->|Não| CheckPayloadDeeplink[Verificar campo link no payload]
    Q5 -->|Sim| Q6{Navegação funciona?}

    Q6 -->|Não| CheckNavigation[Verificar implementação de navegação]
    Q6 -->|Sim| Success[Tudo funcionando]

    CheckFCM --> End[Fim]
    FixPayload --> End
    CheckInit --> End
    CheckListener --> End
    CheckDelegate --> End
    CheckStream --> End
    CheckSubscribe --> End
    CheckPayloadDeeplink --> End
    CheckNavigation --> End
    Success --> End

Exemplo iOS

Dito.notificationClick(userInfo: userInfo) { deeplink in
    if let url = URL(string: deeplink) {
        UIApplication.shared.open(url)
    }
}

Exemplo Android

Dito.notificationClick(userInfo) { deeplink ->
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse(deeplink))
    startActivity(intent)
}

Exemplo Flutter

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:dito_sdk/dito_sdk.dart';

final ditoSdk = DitoSdk();

void setupPushClickHandling() {
  DitoSdk.onNotificationClick.listen((event) {
    final deeplink = event.deeplink;
    if (deeplink.isEmpty) return;
    // Navegação do seu app aqui
  });

  FirebaseMessaging.onMessageOpenedApp.listen((message) async {
    await ditoSdk.handleNotificationClick(message.data);
  });
}

Exemplo React Native

import DitoSdk, { addNotificationClickListener } from '@ditointernet/dito-sdk';

const unsubscribe = addNotificationClickListener((event) => {
  if (!event.deeplink) return;
  // Navegação do seu app aqui
});

// Quando o clique for detectado no JS (ex.: firebase messaging), delegue para o SDK:
await DitoSdk.handleNotificationClick(message.data);

🔗 Deeplinks e Navegação

O SDK extrai automaticamente o link do payload da notificação e fornece através do callback/evento.

Formato de Deeplink

O deeplink deve estar no formato de URL:

https://app.example.com/product/123
myapp://product/123
dito://action/123

Navegação

Cada plataforma tem sua própria forma de processar deeplinks:

iOS: Usar UIApplication.shared.open(url)
Android: Usar Intent com ACTION_VIEW
Flutter: Usar plugins de navegação/deeplink
React Native: Usar bibliotecas de navegação/deeplink

🐛 Troubleshooting Unificado

Notificações não são recebidas

Checklist Geral:

✅ Firebase configurado corretamente
✅ Arquivos de configuração adicionados (GoogleService-Info.plist / google-services.json)
✅ Permissões solicitadas
✅ Token FCM registrado no SDK (Dito.registerDevice(token) / DitoSdk.registerDeviceToken(token))
✅ Campo channel igual a "DITO" no payload

Notificações não são interceptadas pelo SDK

Causa: Campo channel não é "DITO" ou não está presente.

Solução: Certifique-se de que o payload da notificação inclui "channel": "DITO".

Deeplinks não funcionam

Causa: Deeplink não está no formato correto ou não está sendo processado.

Solução:

Verifique se o deeplink está no payload como "link"
Implemente o callback corretamente
Configure o tratamento de deeplinks no app

iOS: Erro "APNS device token not set"

Causa: Ordem incorreta de inicialização no iOS 18+.

Solução: Siga a ordem exata:

FirebaseApp.configure()
Messaging.messaging().delegate = self
Dito.configure()
No didRegisterForRemoteNotificationsWithDeviceToken, defina Messaging.messaging().apnsToken = deviceToken ANTES de solicitar o token FCM

📝 Exemplos de Payload

Payload Completo

{
  "channel": "DITO",
  "notification": "notif-123",
  "reference": "user-456",
  "link": "https://app.example.com/product/789",
  "log_id": "log-abc",
  "notification_name": "Promoção Especial",
  "user_id": "user-456",
  "data": {
    "custom_field": "custom_value"
  }
}

Payload Mínimo

{
  "channel": "DITO",
  "notification": "notif-123",
  "reference": "user-456"
}

🔗 Links Úteis

🔥 Firebase Cloud Messaging Documentation
📱 iOS Push Notifications Guide
🤖 Android Push Notifications Guide
🎯 Flutter Push Notifications Guide
⚛️ React Native Push Notifications Guide

FilesExpand file tree

push-notifications.md

Latest commit

History

push-notifications.md

File metadata and controls

Guia de Push Notifications

📋 Visão Geral

🔥 Configuração Firebase Geral

1. Criar Projeto no Firebase Console

2. Obter Credenciais

📱 Configuração por Plataforma

iOS

1. Adicionar GoogleService-Info.plist

2. Configurar Capabilities

3. Configurar AppDelegate

Android

1. Adicionar google-services.json

2. Configurar FirebaseMessagingService

Flutter

1. Instalar Dependências

2. Configurar Plataformas Nativas

3. Inicializar Firebase

React Native

1. Instalar Dependências

2. Configurar Plataformas Nativas

🔔 Interceptação de Notificações

Como Funciona

Payload Esperado

📊 Tracking Automático

👆 Handling de Clicks

Fluxo (alto nível)

Ciclo de vida (estados)

Decisão de processamento (payload)

Estrutura do payload (diagrama)

Troubleshooting (fluxo)

Exemplo iOS

Exemplo Android

Exemplo Flutter

Exemplo React Native

🔗 Deeplinks e Navegação

Formato de Deeplink

Navegação

🐛 Troubleshooting Unificado

Notificações não são recebidas

Notificações não são interceptadas pelo SDK

Deeplinks não funcionam

iOS: Erro "APNS device token not set"

📝 Exemplos de Payload

Payload Completo

Payload Mínimo

🔗 Links Úteis