Push notifications

Registrar device tokens, manejar notificaciones y deeplinks.

Configuración con PushConfig

Configura los callbacks de push en SouthGamesSDK.init():

await SouthGamesSDK.init(
  apiKey: 'sg_live_xxx',
  orgId: 'mi-empresa',
  pushConfig: PushConfig(
    // Pedir permisos al inicializar (default: true)
    requestPermissionOnInit: true,

    // Mostrar notificaciones en foreground (default: true)
    showForegroundNotifications: true,

    // Callback cuando el usuario toca una notificación
    onNotificationTap: (message) {
      print('Tap: ${message.notification?.title}');
    },

    // Callback en foreground
    onForegroundMessage: (message) {
      print('Recibida: ${message.notification?.title}');
    },

    // Callback automático para deeplinks (ver abajo)
    onDeeplinkReceived: (deeplink, message) {
      navigatorKey.currentState?.pushNamed(deeplink);
    },
  ),
);

El SDK obtiene el token FCM y lo registra automáticamente al llamar identify().

Deeplinks

Las notificaciones push pueden incluir un deeplink que se abre al tocar la notificación. El deeplink se configura desde el dashboard al crear el push.

Manejo automático

Si configuras onDeeplinkReceived en PushConfig, el SDK extrae el deeplink automáticamente y llama al callback:

PushConfig(
  onDeeplinkReceived: (deeplink, message) {
    // deeplink = "myapp://promo/verano"
    // deeplink = "https://miapp.com/oferta"
    // deeplink = "/promo/verano"
    navigatorKey.currentState?.pushNamed(deeplink);
  },
)

El callback se ejecuta después de onNotificationTap, solo si la notificación contiene un deeplink.

Manejo manual

También puedes extraer el deeplink manualmente desde cualquier RemoteMessage:

import 'package:southgames_flutter/southgames_flutter.dart';

final deeplink = SouthGamesPush.getDeeplink(message);
if (deeplink != null) {
  // Navegar a la pantalla correspondiente
}

Payload

El deeplink se envía como data.deeplink en el payload push:

{
  "notification": {
    "title": "¡Oferta especial!",
    "body": "20% de descuento en tu próxima compra"
  },
  "data": {
    "sendId": "abc123",
    "deeplink": "myapp://promo/verano"
  }
}

Background handler

Para rastrear notificaciones recibidas en background, registra el handler en main.dart:

@pragma('vm:entry-point')
Future<void> _firebaseBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  await SouthGamesSDK.handleBackgroundMessage(message);
}

void main() {
  FirebaseMessaging.onBackgroundMessage(_firebaseBackgroundHandler);
  // ...
}

Registro manual de token

Si no usas Firebase Messaging o quieres registrar tokens de otro proveedor:

await SouthGamesSDK.push.registerDeviceToken(
  externalId: 'user_123',
  token: 'fcm_or_apns_token',
);

Proveedores compatibles

El SDK es agnóstico al proveedor de push. Puedes usar cualquiera:

• Firebase Cloud Messaging (FCM)
• Apple Push Notification service (APNs)
• OneSignal
• Cualquier otro que te dé un device token

Logout

Al hacer logout, el SDK desregistra el token automáticamente:

await SouthGamesSDK.logout();
// El token se elimina del servidor y se borra localmente