@gabpereira21/capacitor-fcm-custom-sound

Plugin de Capacitor para Firebase Cloud Messaging con soporte de canales de notificacion y sonido personalizado.

Instalacion

npm install @gabpereira21/capacitor-fcm-custom-sound
npx cap sync

Configuracion

Android

1. Coloca google-services.json en android/app/
2. Para sonido custom: coloca .wav en android/app/src/main/res/raw/

iOS

1. Coloca GoogleService-Info.plist en ios/App/App/
2. Para sonido custom: incluye .wav en el bundle de la app (max 30s)

Uso basico

import { FCMCustomSound } from '@gabpereira21/capacitor-fcm-custom-sound';

// 1. Registrar dispositivo (pide permiso + obtiene token)
const { token } = await FCMCustomSound.registerDevice();
console.log('FCM Token:', token);

// 2. Crear canal con sonido custom (Android)
await FCMCustomSound.createChannel({
  channelId: 'my_alerts',
  channelName: 'Alertas',
  channelDescription: 'Canal con sonido personalizado',
  soundFileName: 'custom_sound',  // sin extension! archivo: res/raw/custom_sound.wav
  importance: 4,
  enableVibration: true,
  enableLights: true
});

// 3. Escuchar notificaciones en foreground
FCMCustomSound.addListener('notificationReceived', (notification) => {
  console.log('Foreground notification:', notification.title, notification.body);
});

// 4. Escuchar clicks en notificaciones
FCMCustomSound.addListener('notificationClicked', (notification) => {
  console.log('User tapped notification:', notification);
});

// 5. Escuchar refresh de token
FCMCustomSound.addListener('tokenRefreshed', (data) => {
  console.log('New token:', data.token);
});

Enviar notificacion con sonido custom desde Firebase

{
  "message": {
    "token": "DEVICE_FCM_TOKEN",
    "notification": {
      "title": "Alerta!",
      "body": "Tienes un nuevo mensaje"
    },
    "android": {
      "notification": {
        "channel_id": "my_alerts",
        "sound": "custom_sound"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "sound": "custom_sound.wav"
        }
      }
    }
  }
}

Cambiar el sonido de un canal

Android no permite cambiar el sonido de un canal existente. Debes:

await FCMCustomSound.deleteChannel({ channelId: 'my_alerts' });
await FCMCustomSound.createChannel({
  channelId: 'my_alerts_v2',
  channelName: 'Alertas',
  soundFileName: 'new_sound'
});

Debug: listar canales

const { channels } = await FCMCustomSound.listChannels();
channels.forEach(ch => {
  console.log(`${ch.channelId}: sound=${ch.soundFileName}, importance=${ch.importance}`);
});

Extensibility Configuration para OutSystems ODC

{
  "plugin": {
    "url": "https://registry.npmjs.org/@gabpereira21/capacitor-fcm-custom-sound/-/capacitor-fcm-custom-sound-1.0.0.tgz"
  },
  "resource": {
    "android": [
      { "src": "www/resources/google-services.json", "target": "app/google-services.json" },
      { "src": "www/resources/custom_sound.wav", "target": "app/src/main/res/raw/custom_sound.wav" }
    ],
    "ios": [
      { "src": "www/resources/GoogleService-Info.plist", "target": "GoogleService-Info.plist" },
      { "src": "www/resources/custom_sound.wav", "target": "custom_sound.wav" }
    ]
  }
}

Notas importantes

• Android: Una vez creado un canal, su sonido NO puede cambiarse. Usa deleteChannel + createChannel con nuevo ID.
• iOS: No usa canales. El sonido va en el payload APNS.
• Formato sonido: .wav, maximo 30 segundos.
• Android 13+: El plugin pide permiso POST_NOTIFICATIONS automaticamente en registerDevice().

Licencia

MIT