# Recolector recurrente de metricas YouTube (v2)

Este modulo separa metricas en dos grupos:

1. Publicas (disponibles con API key)
2. Privadas (requieren OAuth y permisos del canal)

## Datos cubiertos

### Publicos (implementados)
- Numero de seguidores (`subscriberCount`)
- Visitas en tiempo real para transmisiones activas (`concurrentViewers`)
- Ultimos contenidos subidos
- Total historico de visitas del canal (`viewCount`)

El recolector usa un modo de baja cuota: inspecciona el playlist de uploads recientes y consulta esos videos en batch para detectar lives, evitando `search.list` en cada ciclo.

### Privados (implementados, opcional con OAuth)
- Total de visitas en un periodo de tiempo (Analytics API)
- Monetizacion general en un periodo (`estimatedRevenue`, `cpm`, `monetizedPlaybacks`)
- Monetizacion por video para IDs especificos o para uploads recientes automaticamente

## Importante sobre disponibilidad de datos

- API key sola no entrega monetizacion ni vistas por periodo.
- Para esos datos necesitas autenticarte como propietario del canal.
- No existe un endpoint publico oficial de "realtime views" agregadas de todo el canal. Lo mas cercano y soportado es `concurrentViewers` por stream en vivo activo.

## Instalacion

```bash
cd /var/www/html/site13/youtube/v2
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

Edita `.env` con tu API key y canales.

## Uso basico (solo publico)

Ejecuta una vez:

```bash
python youtube_metrics_collector.py
```

Ejecucion recurrente cada 10 minutos en bucle infinito:

```bash
python youtube_metrics_collector.py --runs 0 --interval-seconds 600
```

## Cuota recomendada

- Configuracion actual de baja cuota: alrededor de 3 unidades por canal por corrida publica.
- Frecuencia recomendada para produccion: cada 10 minutos.
- Con 1 canal, eso equivale aproximadamente a 432 unidades al dia, muy por debajo de una cuota tipica de 10.000 unidades diarias.
- Si agregas mas canales, escala casi linealmente: `canales x 432` unidades por dia con cron cada 10 minutos.

## Habilitar datos privados (OAuth)

1. Crea credenciales OAuth en Google Cloud.
2. Guarda el JSON como `client_secret.json` en esta carpeta.
3. Ajusta en `.env`:

```env
YT_OAUTH_CLIENT_SECRETS=./client_secret.json
YT_OAUTH_TOKEN=./oauth_token.json
```

4. Inicializa token segun el tipo de credencial:

Si tu `client_secret.json` es tipo web, abre en el navegador:

```text
https://13.mediabytes.cl/youtube/oauth2start.php
```

Eso redirige a Google, recibe el callback en `oauth2callback.php` y guarda `oauth_token.json` automaticamente.

Si Google muestra `Error 403: access_denied` con el mensaje de que la app esta en pruebas, el problema no es del codigo: debes agregar como usuario de prueba la cuenta Google con la que intentas autorizar.

Ruta habitual en Google Cloud:

```text
Google Cloud Console -> Google Auth Platform / OAuth consent screen -> Audience -> Test users
```

Agrega ahi el correo exacto del propietario del canal o de la cuenta que hara el consentimiento. Mientras la app siga en modo Testing, solo esos usuarios podran completar OAuth.

Si tu `client_secret.json` es tipo Desktop App, puedes usar el init por CLI:

```bash
python youtube_metrics_collector.py --oauth-init
```

5. Consulta privados en un periodo:

```bash
python youtube_metrics_collector.py \
  --include-private \
  --start-date 2026-03-01 \
  --end-date 2026-03-20 \
  --video-ids VIDEO_ID_1,VIDEO_ID_2
```

Si no indicas fechas, el recolector usa una ventana movil definida por `YT_PRIVATE_LOOKBACK_DAYS` o `--private-lookback-days`.

Si no indicas `--video-ids`, el recolector intentara consultar monetizacion para los uploads recientes usando `YT_PRIVATE_RECENT_VIDEOS_LIMIT` o `--private-recent-videos-limit`.

## Archivos de salida

Se crean en `YT_OUTPUT_DIR` (default: `./data`):

- `latest_public_snapshot.json`: ultimo estado publico completo
- `public_channel_metrics.jsonl`: serie temporal de seguidores/views totales/video count
- `realtime_live_views.jsonl`: serie de concurrentes por stream activo
- `latest_uploads.jsonl`: contenidos nuevos detectados
- `private_analytics.jsonl`: historico de vistas/monetizacion privadas
- `latest_private_analytics.json`: ultimo estado privado

## Persistencia MySQL

Si defines `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD` y `MYSQL_DATABASE`, cada corrida tambien guarda el snapshot en MySQL.

Para este servidor, la configuracion valida encontrada en el proyecto usa `127.0.0.1` y la base `canal13`.

Tablas creadas automaticamente:

- `youtube_channel_metrics`: historico por canal
- `youtube_channel_metrics_current`: ultimo estado por canal
- `youtube_live_metrics`: historico de lives activos
- `youtube_live_metrics_current`: ultimo estado por live
- `youtube_uploads`: catalogo de uploads detectados
- `youtube_private_channel_analytics`: historico de vistas e ingresos del canal autenticado por rango de fechas
- `youtube_private_channel_analytics_current`: ultimo valor conocido por canal y rango consultado
- `youtube_private_video_analytics`: historico de ingresos y views por video para el rango consultado
- `youtube_private_video_analytics_current`: ultimo valor conocido por video y rango consultado

## Cadencia recomendada para datos privados

Los datos privados de Analytics y monetizacion no son tiempo real. Para poblar base de datos conviene correrlos aparte del polling publico:

- Publico: cada 10 minutos
- Privado con OAuth: cada 6 o 12 horas, refrescando una ventana de varios dias para capturar ajustes tardios

Archivos operativos incluidos:

- `run_youtube_metrics.sh`: corrida publica
- `run_youtube_private_metrics.sh`: corrida privada con OAuth
- `youtube_metrics.cron`: ejemplo de cron publico cada 10 minutos
- `youtube_private_metrics.cron`: ejemplo de cron privado cada 6 horas

Ejemplo practico para ingresos del canal y monetizacion reciente:

```bash
python youtube_metrics_collector.py \
  --include-private \
  --private-lookback-days 7 \
  --private-recent-videos-limit 5
```

Si quieres dejarlo programado con cron, usa el runner privado:

```bash
/var/www/html/site13/youtube/v2/run_youtube_private_metrics.sh
```

## Recomendacion de produccion

Para correr 24/7 usa `systemd` o `cron`:

- `cron`: ejecutar cada 5 min
- `systemd`: proceso continuo con restart automatico