iTartanas/INSTALLATION_GUIDE.md

Guía de Instalación y Uso - iTartanas

📱 Instalación

Opción 1: Desde Android Studio

1. Abre el proyecto en Android Studio
2. Conecta tu dispositivo Android via USB o usa un emulador con soporte NFC
3. Haz clic en el botón "Run" (▶️) o presiona Shift + F10
4. Selecciona tu dispositivo y espera a que se instale

Opción 2: Compilar APK

# Desde la terminal en la raíz del proyecto
.\gradlew assembleDebug

# El APK se generará en:
# app\build\outputs\apk\debug\app-debug.apk

Luego puedes transferir el APK a tu dispositivo Android e instalarlo manualmente.

✅ Requisitos del Dispositivo

• Android 7.0 (API 24) o superior
• Hardware NFC (obligatorio)
• NFC activado en la configuración del dispositivo

Cómo activar NFC:

1. Ve a Configuración → Conexiones (o Dispositivos conectados)
2. Busca la opción NFC
3. Activa el interruptor NFC
4. También puedes activar Android Beam si está disponible

📖 Cómo usar la aplicación

Paso 1: Abrir la aplicación

Abre iTartanas desde el cajón de aplicaciones. Verás una pantalla con el mensaje:

"Acerca tu Tarjeta Millennium al lector NFC"

Paso 2: Acercar la tarjeta

1. Mantén tu Tarjeta Millennium cerca del lector NFC de tu dispositivo
2. El lector NFC suele estar en la parte trasera del teléfono, cerca de la cámara
3. Mantén la tarjeta estable durante 1-2 segundos

Paso 3: Ver los resultados

La aplicación mostrará automáticamente:

• ✅ Número de Tarjeta: En formato enmascarado (ej: **** **** 1234 5678)
• 💰 Saldo: En euros con dos decimales (ej: 12.50 €)

🔍 Ubicación del lector NFC

La ubicación del lector NFC varía según el dispositivo:

• Samsung: Parte trasera central o superior
• Google Pixel: Parte trasera central
• Xiaomi: Parte trasera central o superior
• OnePlus: Parte trasera cerca de la cámara

💡 Tip: Puedes buscar en Internet "ubicación NFC [modelo de tu teléfono]" para encontrar la posición exacta.

⚠️ Solución de problemas

La aplicación no detecta la tarjeta

Problema: Al acercar la tarjeta no pasa nada.

Soluciones:

1. Verifica que el NFC esté activado en tu dispositivo
2. Asegúrate de acercar la tarjeta a la zona correcta del lector NFC
3. Mantén la tarjeta estable durante al menos 2 segundos
4. Retira cualquier funda metálica o magnética del teléfono
5. Reinicia la aplicación

Error: "Este dispositivo no tiene NFC"

Problema: Tu dispositivo no tiene hardware NFC.

Solución: Lamentablemente, necesitas un dispositivo con NFC para usar esta aplicación. Consulta las especificaciones de tu dispositivo.

Error al leer la tarjeta

Problema: La aplicación detecta la tarjeta pero muestra un error.

Soluciones:

1. Intenta acercar la tarjeta de nuevo
2. Limpia suavemente la tarjeta con un paño seco
3. Asegúrate de que estás usando una Tarjeta Millennium válida
4. Verifica que la tarjeta no esté dañada
5. Intenta en una zona con menos interferencias electromagnéticas

"Por favor, activa el NFC en configuración"

Problema: El NFC está desactivado.

Solución: Ve a Configuración → Conexiones → NFC y actívalo.

📊 Información mostrada

Número de Tarjeta

• Formato: 16 dígitos en grupos de 4
• Los primeros 8 dígitos están enmascarados con asteriscos (*)
• Ejemplo: **** **** 1234 5678

Saldo

• Formato: Euros con 2 decimales
• Ejemplo: 15.75 €
• Se obtiene directamente del chip de la tarjeta

🔒 Privacidad y Seguridad

• ✅ La aplicación NO envía datos a Internet
• ✅ NO guarda información de tu tarjeta
• ✅ Solo lee los datos visibles en el chip NFC
• ✅ No puede modificar el saldo ni los datos de la tarjeta
• ✅ El número de tarjeta se enmascara parcialmente por seguridad

🛠️ Desarrollo

Compilar desde código fuente

# Clonar el repositorio (si aplica)
git clone [URL_del_repositorio]
cd iTartanas

# Compilar
.\gradlew build

# Ejecutar tests
.\gradlew test

# Instalar en dispositivo conectado
.\gradlew installDebug

Dependencias principales

• Kotlin 2.1.0
• Jetpack Compose BOM
• Material 3
• Lifecycle Runtime KTX
• Android NFC API

📞 Soporte

Si encuentras algún problema o tienes sugerencias, por favor:

1. Verifica que tu tarjeta Millennium sea compatible
2. Asegúrate de tener la última versión de la aplicación
3. Revisa la sección de solución de problemas de este documento

📝 Notas adicionales

• La aplicación solo funciona con Tarjetas Millennium del sistema de transporte público
• No funcionará con otras tarjetas NFC (tarjetas bancarias, pases de acceso, etc.)
• La lectura es de solo lectura, no puede modificar el saldo
• Los datos se leen en tiempo real desde el chip de la tarjeta

---

Versión: 1.0
Última actualización: Marzo 2026