242 líneas
7.1 KiB
Markdown
242 líneas
7.1 KiB
Markdown
# Guía de Instalación Rápida - Classic Add-ons Archive v3.0
|
|
|
|
## Para Desarrolladores / Testing Local
|
|
|
|
### Firefox
|
|
|
|
**Opción 1: Carga temporal (recomendado para desarrollo)**
|
|
|
|
1. Abre Firefox
|
|
2. Escribe en la barra de direcciones: `about:debugging#/runtime/this-firefox`
|
|
3. Click en "Cargar complemento temporal..."
|
|
4. Navega a la carpeta del proyecto y selecciona el archivo `manifest.json`
|
|
|
|
La extensión se instalará hasta que cierres Firefox.
|
|
|
|
**Opción 2: Instalación sin firma (Firefox Developer/Nightly)**
|
|
|
|
Firefox normal NO permite instalar extensiones sin firma. Usa una de estas versiones:
|
|
|
|
1. **Firefox Developer Edition** o **Firefox Nightly**:
|
|
- Descarga: https://www.mozilla.org/firefox/developer/
|
|
- Descarga: https://www.mozilla.org/firefox/nightly/
|
|
|
|
2. **Deshabilitar verificación de firma:**
|
|
- Escribe en la barra: `about:config`
|
|
- Acepta el riesgo
|
|
- Busca: `xpinstall.signatures.required`
|
|
- Cambia a `false` (doble click)
|
|
|
|
3. **Instalar la extensión:**
|
|
```bash
|
|
# Empaquetar
|
|
cd /home/ale/projects/firefox/ca-archive
|
|
./build.sh
|
|
|
|
# O manualmente:
|
|
zip -r ca-archive-3.0.xpi manifest.json background.js content/ skin/ -x "*.git*" -x "*~"
|
|
```
|
|
|
|
4. Arrastra el archivo `.xpi` a Firefox
|
|
|
|
**⚠️ IMPORTANTE:** Firefox normal (Release) NO acepta `xpinstall.signatures.required=false`. Solo funciona en Developer/Nightly/Unbranded.
|
|
|
|
**Opción 3: Instalación permanente con firma AMO (distribución)**
|
|
|
|
1. Obtener credenciales AMO: https://addons.mozilla.org/developers/addon/api/key/
|
|
2. Configurar en `private-keys/firefox-amo-credentials.json`
|
|
3. Firmar: `./build.sh --sign`
|
|
4. Instalar el `.xpi` firmado resultante
|
|
|
|
### Chrome / Edge / Brave
|
|
|
|
**⚠️ PROBLEMA CONOCIDO: Manifest v2 deprecado en Chrome**
|
|
|
|
Chrome está migrando a Manifest v3. Esta extensión usa Manifest v2 y puede:
|
|
- ✅ Funcionar en Edge/Brave (soporte extendido hasta ~2024-2025)
|
|
- ⚠️ Mostrar advertencias en Chrome
|
|
- ❌ Dejar de funcionar en Chrome 127+ (junio 2024)
|
|
|
|
**Si Chrome rechaza el manifest:**
|
|
|
|
1. Verifica la versión de Chrome: `chrome://settings/help`
|
|
2. Si es Chrome 127+, necesitas Manifest v3 (aún no implementado)
|
|
3. **Alternativa temporal:** Usa Microsoft Edge o Brave (soportan v2 más tiempo)
|
|
|
|
**Modo desarrollador (sin empaquetar) - Solo Chrome <127:**
|
|
|
|
1. Abre el navegador
|
|
2. Ve a: `chrome://extensions/` (o `edge://extensions/`)
|
|
3. Activa el interruptor "Modo de desarrollador" (esquina superior derecha)
|
|
4. Click en "Cargar extensión sin empaquetar"
|
|
5. Selecciona la carpeta: `/home/ale/projects/firefox/ca-archive`
|
|
|
|
La extensión quedará instalada permanentemente en modo desarrollo.
|
|
|
|
**Errores comunes en Chrome:**
|
|
|
|
- **"Manifest version 2 is deprecated":**
|
|
- ⚠️ Solo advertencia (aún funciona)
|
|
- Chrome mostrará recordatorio hasta que migres a v3
|
|
|
|
- **"Manifest version 2 is not supported":**
|
|
- ❌ Chrome 127+ bloquea v2 completamente
|
|
- **Solución:** Usa Firefox, Edge o Brave
|
|
- **O espera:** Implementación de Manifest v3 (pendiente)
|
|
|
|
**Empaquetar para distribución:**
|
|
|
|
```bash
|
|
cd /home/ale/projects/firefox/ca-archive
|
|
|
|
# Construir paquetes sin firmar
|
|
./build.sh
|
|
|
|
# O con firma (requiere configurar claves primero)
|
|
./scripts/generate-keys.sh # Primera vez
|
|
./build.sh --sign # Construir firmado
|
|
```
|
|
|
|
**Para distribución con firma**, ver [SIGNING.md](SIGNING.md).
|
|
|
|
## Verificación de Instalación
|
|
|
|
Después de instalar, deberías ver:
|
|
|
|
1. ✅ Icono de la extensión en la barra de herramientas
|
|
2. ✅ Click en el icono abre la página del catálogo
|
|
3. ✅ Mensaje de carga de base de datos (primera vez)
|
|
4. ✅ Navegación funcionando (categorías, búsqueda, etc.)
|
|
|
|
## Troubleshooting
|
|
|
|
### La base de datos no carga
|
|
|
|
**Error:** "Loading database for the first time. Please wait..."
|
|
|
|
**Solución:**
|
|
1. Asegúrate de tener la carpeta `content/db/` con el archivo SQLite
|
|
2. Verifica que el archivo `ca-archive-19030501.sqlite` exista y no esté corrupto
|
|
3. Revisa la consola del navegador (`F12` > Console) para errores específicos
|
|
|
|
### El icono no aparece
|
|
|
|
**Solución:**
|
|
1. Refresca la página `about:debugging` o `chrome://extensions/`
|
|
2. Verifica que `manifest.json` tiene el campo `browser_action` correctamente
|
|
3. Revisa que las imágenes en `skin/button.png` existan
|
|
|
|
### Errores de carga de scripts
|
|
|
|
**Error:** "Failed to load script: ..."
|
|
|
|
**Solución:**
|
|
1. Verifica que todos los archivos JS estén en `content/`
|
|
2. Revisa la política CSP en `manifest.json`
|
|
3. Asegúrate de que `db-webext.js` se carga antes de `ca-archive.js`
|
|
|
|
### sql.js no carga
|
|
|
|
**Error:** "Could not load SQL engine"
|
|
|
|
**Solución:**
|
|
1. Verifica conexión a internet (se descarga desde CDN)
|
|
2. O descarga sql.js localmente:
|
|
```bash
|
|
cd content/
|
|
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js
|
|
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm
|
|
```
|
|
3. Actualiza las rutas en `content/db-webext.js`
|
|
|
|
### web-ext no disponible (para firma)
|
|
|
|
**Solución:**
|
|
```bash
|
|
# Instalar dependencias locales (recomendado)
|
|
npm install
|
|
|
|
# O instalación global (alternativa)
|
|
npm install -g web-ext
|
|
```
|
|
|
|
El script `build.sh` detecta automáticamente web-ext en `node_modules/.bin/`
|
|
|
|
## Para Usuarios Finales
|
|
|
|
### Instalar desde archivo .xpi/.zip
|
|
|
|
**Firefox:**
|
|
1. Descarga el archivo `.xpi`
|
|
2. Arrastra y suelta en Firefox
|
|
3. Autoriza la instalación
|
|
|
|
**Chrome:**
|
|
1. Descarga el archivo `.zip`
|
|
2. Descomprime en una carpeta
|
|
3. Sigue los pasos de "Modo desarrollador" arriba
|
|
|
|
### Instalar desde stores (cuando esté publicado)
|
|
|
|
**Firefox Add-ons (AMO):**
|
|
- Visita: https://addons.mozilla.org/firefox/addon/ca-archive/
|
|
- Click en "Añadir a Firefox"
|
|
|
|
**Chrome Web Store:**
|
|
- Visita: [URL de Chrome Web Store]
|
|
- Click en "Añadir a Chrome"
|
|
|
|
## Desinstalación
|
|
|
|
### Firefox
|
|
1. `about:addons` > Extensiones
|
|
2. Busca "Classic Add-ons Archive"
|
|
3. Click en "..." > Eliminar
|
|
|
|
### Chrome
|
|
1. `chrome://extensions/`
|
|
2. Busca la extensión
|
|
3. Click en "Eliminar"
|
|
|
|
## Archivos Necesarios
|
|
|
|
Archivos mínimos para que funcione la extensión:
|
|
|
|
```
|
|
ca-archive/
|
|
├── manifest.json ← REQUERIDO
|
|
├── background.js ← REQUERIDO
|
|
├── content/
|
|
│ ├── ca-archive.html ← REQUERIDO
|
|
│ ├── ca-archive.js ← REQUERIDO
|
|
│ ├── db-webext.js ← REQUERIDO
|
|
│ ├── db/
|
|
│ │ └── ca-archive-19030501.sqlite ← REQUERIDO
|
|
│ ├── addon.js
|
|
│ ├── list.js
|
|
│ ├── versions.js
|
|
│ ├── tcloud.js
|
|
│ ├── about.js
|
|
│ └── epl.js
|
|
└── skin/
|
|
├── logo.png ← REQUERIDO
|
|
├── button.png ← REQUERIDO
|
|
├── ca-archive.css ← REQUERIDO
|
|
└── ...
|
|
```
|
|
|
|
## Siguientes Pasos
|
|
|
|
Una vez instalada y funcionando:
|
|
|
|
1. 📖 Lee [MIGRATION.md](MIGRATION.md) para entender los cambios
|
|
2. 🔧 Si eres desarrollador, revisa la arquitectura modernizada
|
|
3. 🐛 Reporta bugs en GitHub Issues
|
|
4. 🌟 Si te gusta, deja una valoración
|
|
|
|
## Soporte
|
|
|
|
- 📝 Documentación completa: [MIGRATION.md](MIGRATION.md)
|
|
- 🐛 Reportar problemas: https://github.com/JustOff/ca-archive/issues
|
|
- 💬 Discusiones: https://github.com/JustOff/ca-archive/discussions
|