npm package: @gabpereira21/capacitor-fcm-custom-sound
Description: Capacitor plugin for FCM with custom notification channel and sound. Zero OutSystems dependencies.
Author: Gabriel Pereira
Latest version: 1.0.3

# @gabpereira21/capacitor-fcm-custom-sound

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

## Instalacion

```bash
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

```typescript
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

```json
{
  "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:

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

## Debug: listar canales

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

## Extensibility Configuration para OutSystems ODC

```json
{
  "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