| Puntos clave | Detalles a recordar |
|---|---|
| 📝 Definición | Automatizar la importación de carátulas y descripciones desde Screenscraper |
| 🎮 Beneficios principales | Enriquecer visualmente tu frontend, ganar tiempo valioso |
| 🔧 Funcionamiento | Recuperar vía API, asociar metadatos e imágenes |
| ⚙️ Requisitos | Instalar Python, configurar tu clave API de Screenscraper |
| 🚀 Pasos clave | Ejecutar el script, probar el resultado, validar los archivos |
| 📂 Organización | Estructurar las carpetas para cada sistema |
| 🛠️ Herramientas | Usar un script Python ligero y un cron para la automatización |
Este tutorial te guía paso a paso para configurar Screenscraper e integrar automáticamente carátulas y descripciones en tu interfaz Retrogaming. Con unos pocos comandos y ajustes simples, podrás enriquecer visualmente tu frontend mientras dispones de información precisa sobre cada juego. Al final, un cron ejecutará la operación sin intervención manual.
Somaire
Requisitos e instalación de Screenscraper
Antes que nada, asegúrate de tener una cuenta válida en Screenscraper y una clave API. También necesitarás un entorno Python 3.7+ en tu máquina o servidor.
Para instalar el módulo Python dedicado, ejecuta:
pip install screenscraper-api
Luego verifica que la biblioteca responda correctamente:
python -c "import screenscraper; print(screenscraper.__version__)". Si aparece un error, reinstala o actualiza tu pip.
Configuración del script de importación
El script Python sirve de puente entre la API de Screenscraper y tu frontend Retrogaming. Recupera carátulas y descripciones, y luego las deposita en carpetas dedicadas.
Conexión a la API de Screenscraper
Recupera tu clave en tu espacio personal de Screenscraper y guárdala en una variable de entorno:
export SCREENSCRAPER_KEY="votre_cle"
Luego, en tu script:
from screenscraper import ScreenScraperAPI
api = ScreenScraperAPI(key=os.getenv("SCREENSCRAPER_KEY"))
Ya estás listo para consultar la API.
Personalización de filtros y formatos
Para ajustar el resultado, puedes especificar:
- tamaño de las imágenes (small, medium, large)
- idioma de las descripciones (fr, en, it)
- plataforma objetivo (nes, snes, arc)
- formatos de salida (png, jpg, txt)
Estas opciones se pasan como parámetros:
api.get_game_data(game_id, image_size='medium', language='fr')
Prueba varias configuraciones para encontrar la que mejor se integre con tu tema.
Integración en tu frontend Retrogaming
Una vez recuperados los archivos, hay que organizarlos y llamar a la ruta correcta en tu código front. La idea es estandarizar la ubicación para cada título.
Organización de carátulas y descripciones
Sigue una estructura clara:
| Carpeta | Contenido |
|---|---|
| images/ | Carátulas nombradas por ID de juego (.png) |
| descriptions/ | Archivos de texto por ID de juego (.txt o .md) |
| scripts/ | Código Python de importación |
Esto permite que el frontend itere sobre un mismo ID y muestre al vuelo la carátula y la descripción asociada.
Automatización mediante una tarea cron
Para lanzar la importación periódicamente, cree una entrada cron:
0 3 * * * /usr/bin/python3 /home/user/scripts/import_screenscraper.py >> /var/log/ss_import.log 2>&1
Esta tarea se ejecuta cada noche a las 3 h. Puede adaptar la frecuencia según sus necesidades.
Consejo: supervise los registros para corregir rápidamente un fallo de API o un cambio de esquema en Screenscraper.
Pruebas, depuración y buenas prácticas
Una importación automatizada puede encontrar problemas de claves expiradas, formatos modificados o cuotas superadas. Aquí algunas pistas para mantenerse operativo:
- Verificar regularmente la validez de su clave API
- Implementar un sistema de reintentos con backoff en caso de error 429
- Mantener un historial de versiones para revertir cambios
- Limpiar los archivos antiguos no referenciados
- Validar manualmente algunas carátulas tras cada despliegue
- Establecer una alerta para los códigos de error críticos
- Probar localmente antes de desplegar en producción
- Documentar cada modificación del script
Para recordar
- Crear una cuenta en Screenscraper y obtener su clave API
- Instalar el módulo Python dedicado y probar la conexión
- Personalizar los filtros (tamaño, idioma, plataforma)
- Organizar carátulas y descripciones en una estructura clara
- Automatizar con un cron y supervisar los registros
- Prever estrategias de reintentos y alertas
Preguntas frecuentes
- ¿Cómo obtener mi clave API de Screenscraper?
Inicie sesión en su cuenta en el sitio de Screenscraper, vaya a « Mi cuenta » y luego a « API » para generar o copiar su clave. - ¿Qué sistemas son compatibles con Screenscraper?
La plataforma cubre más de 200 sistemas, desde consolas de 8 bits hasta máquinas arcade, pasando por dispositivos más recientes. - ¿Puedo obtener descripciones en varios idiomas?
Sí: basta con modificar el parámetrolanguageal llamar aget_game_data(por ejemplo « en » o « it »). - ¿Cómo gestionar las cuotas de la API?
Supervise los encabezados de respuesta para conocer su consumo e implemente un sistema de backoff para evitar errores 429. - ¿El script puede reemplazar carátulas existentes?
Por supuesto: puede añadir una opciónoverwrite=Truepara sobrescribir los archivos anteriores. - ¿Qué hacer si faltan carátulas?
Identifique los IDs no devueltos, pruebe manualmente en el sitio de Screenscraper y complete a mano si es necesario.
