Procés d’ideació i evolució del projecte

El projecte Camina i fes UNLOCK! neix amb la voluntat de transformar una activitat quotidiana com caminar en una experiència lúdica i visualment significativa. A partir de la base desenvolupada a la PR1, l’objectiu de la PR2 ha estat ampliar aquesta proposta mantenint la mecànica principal, però afegint una nova capa de contingut mitjançant la integració d’una API externa. Enfocarem aquesta nova versió com una app específica amb contingut de Tarragona.

Des del punt de vista conceptual, s’ha considerat important no alterar la naturalesa “effort-free” de l’app. L’ usuari continua interactuant mínimament amb el dispositiu, mentre el progrés es produeix de manera natural a mesura que camina. La nova funcionalitat introduïda no substitueix el joc, sinó que l’enriqueix, aportant context cultural i informatiu a les imatges desbloquejades.

Integració d’una API externa

S’ha integrat una API externa pública: la MediaWiki API (Viquipèdia) en llengua catalana.

L’ elecció d’aquesta API respon a diversos criteris:

• és gratuïta i sense necessitat d’autenticació,
• permet consultes dinàmiques en format JSON,
• ofereix contingut rellevant i contextualitzat,
• i disposa de suport CORS, imprescindible per a la seva integració en una aplicació web híbrida amb Capacitor.

Cada imatge desbloquejada a l’ app està associada a un indret real de la ciutat de Tarragona. Quan l’usuari accedeix a la galeria i selecciona el botó Info, l’ aplicació realitza una crida dinàmica a l’API de la Viquipèdia per obtenir informació contextual sobre aquell indret: títol, resum descriptiu i enllaç per ampliar la informació.

Aquesta integració compleix el requisit de “petició personalitzada”, ja que la consulta depèn directament de la imatge seleccionada, i inclou control d’errors per gestionar possibles problemes de xarxa o respostes no disponibles.

Visualització de la informació

La informació retornada per l’API es mostra dins l’ aplicació mitjançant un modal dedicat, evitant així que l’usuari abandoni el flux principal del joc. Aquesta solució permet mantenir la coherència visual de l’app i reforça la idea que la informació forma part de l’ experiència de desbloqueig.

La presentació de les dades s’ha dissenyat de manera clara i jerarquitzada, prioritzant la llegibilitat i l’accessibilitat, i reforçant el valor afegit de l’API sense sobrecarregar la interfície.

Funcionalitats natives i feedback tècnic

L’aplicació continua fent ús de funcionalitats natives del dispositiu, principalment la geolocalització, que és l’eix central del funcionament del joc. El càlcul de la distància recorreguda permet determinar el progrés de desbloqueig de cada imatge.

Arran del feedback rebut a la PR1, es va analitzar la possibilitat d’implementar watchPosition per millorar la precisió del seguiment continu. Tot i reconèixer els avantatges d’aquesta aproximació, en aquesta iteració s’ha prioritzat l’estabilitat del MVP i la integració correcta de l’API externa. Com a solució tècnica per facilitar el desenvolupament i el testeig, es manté el Mode Demo, que permet simular l’avanç de metres sense necessitat de desplaçar-se físicament. Aquest plantejament ha permès continuar iterant sobre el projecte de manera eficient, deixant la millora del seguiment GPS com a possible evolució futura.

Galeria, navegació i estat del joc

Les imatges completades es poden consultar en qualsevol moment i s’obren en un visor amb opcions de zoom. La integració del botó Info dins la galeria reforça la connexió entre el contingut visual i la informació contextual obtinguda de l’API.

S’ha tingut especial cura a separar els estats de “desbloqueig en curs” i “visualització”, evitant animacions o efectes que poguessin generar confusió quan l’usuari navega per contingut ja completat.

Proves i entorn de test

Les proves s’han realitzat principalment amb Android Studio, utilitzant diferents perfils d’emulador per validar el comportament de l’aplicació en diverses resolucions i formats de dispositiu. Aquest procés ha permès detectar i solucionar problemes relacionats amb l’estat persistent, la configuració de l’entorn i la reconstrucció del projecte en entorns nets.

Com a millora respecte versions anteriors, l’aplicació arrenca des d’un estat inicial net en el primer llançament, evitant conflictes derivats de dades de proves prèvies guardades en emmagatzematge local.

Les proves finals s’han realitzat amb Android Studio amb els següents perfils:

• Tablet Pixel (API 35)
• Pixel 9 Pro XL (API 36)
• Medium Phone (API 36.1)

Dependències i avisos de seguretat

Durant la instal·lació del projecte mitjançant npm install, el gestor de paquets indica l’existència d’algunes vulnerabilitats en dependències de tercers (2 de nivell moderat i 2 de nivell alt).

Aquests avisos corresponen a llibreries utilitzades internament pel framework i no a codi propi del projecte. En tractar-se d’un MVP amb finalitats educatives i no d’una aplicació destinada a producció, s’ha prioritzat l’estabilitat del projecte i no s’han aplicat actualitzacions forçades (npm audit fix --force), ja que podrien introduir canvis trencadors o incompatibilitats amb Capacitor i Vite. Aquesta decisió reflecteix un criteri habitual en entorns reals, on la gestió de vulnerabilitats es fa de manera controlada i contextualitzada segons l’estat i l’objectiu del producte.

Resultat final i aprenentatges

El resultat final és una aplicació Android funcional, estable i coherent amb el concepte inicial. A nivell d’aprenentatge, la PR2 ha posat de manifest la importància de:

• integrar serveis externs de manera significativa,
• gestionar correctament els estats i errors,
• i prendre decisions tècniques equilibrades entre ambició i estabilitat.

El projecte consolida el potencial de Capacitor com a eina per portar aplicacions web a l’àmbit mòbil i estableix una base sòlida per futures ampliacions.

ENLLAÇ A GITHUB: https://josepmsole.github.io/CaminaifesUnlockTarragona/

Ideació inicial de la nova App

L’objectiu d’aquesta pràctica 2 ha estat donar continuïtat a la feina feta en la pràctica 1 i desenvolupar una app interactiva basada en un puzle de peces mòbils, que permet a l’usuari carregar la imatge amb la qual es jugarà dins del puzle.
A la pràctica 1, l’app permetia escollir entre una imatge feta amb la càmera o una imatge existent a la galeria. A la pràctica 2 mantinc aquestes funcionalitats i n’afegeixo una de nova: obtenir imatges de Picsum per utilitzar-les en el puzle.
També es manté l’opció de mostrar un botó de configuració per escollir la mida del puzle amb què es vol jugar.
Aquests són els esbossos de la pràctica 1 i el resultat final de la pràctica 2.

Consultes i passos seguits a la documentació de Capacitor

Per tal de desenvolupar l’app amb Capacitor i integrar funcionalitats natives, he seguit el procés de consulta i experimentació següent:

• Revisió de la documentació oficial de Capacitor per entendre com funciona la integració amb projectes web.
• Consulta dels plugins oficials i dels seus exemples d’ús.

Especial focus en:

• Camera Plugin: per capturar imatges directament des del dispositiu o carregar-les des de la galeria.
• Haptics Plugin: per afegir feedback tàctil durant la interacció amb el puzle.
• També s’ha considerat com adaptar el codi perquè funcioni correctament dins d’una app híbrida (ús de webPath, càrrega d’imatges amb p5.loadImage, etc.).

Aquestes consultes han permès comprendre com utilitzar les APIs natives des de JavaScript, i com gestionar errors, permisos i diferents comportaments segons el dispositiu.

Proves amb diferents funcionalitats natives del dispositiu

Per a la pràctica, s’han provat funcionalitats natives per donar valor afegit a l’aplicació:

Càmera i galeria (Camera Plugin)

L’usuari pot:

• Fer una foto amb la càmera.
• Seleccionar una imatge de la galeria.

Aquestes imatges es processen i es transformen en un puzle.

Vibració / feedback tàctil (Haptics Plugin)

• Quan el jugador fa un moviment vàlid, l’app fa una vibració lleugera.
• Quan el puzle queda resolt, es mostra un efecte extra (vibració més forta o més llarga).

Aquestes funcionalitats fan que l’experiència sigui més “game-like” i milloren la resposta al tacte.

Proves realitzades:

• Verificar la càrrega correcta de la imatge a p5.js.
• Comprovar el comportament quan l’usuari cancel·la la selecció (sense perdre la partida actual).
• Detectar problemes amb l’orientació/simetria de la foto (amb càmera frontal). Aquest punt queda pendent de resoldre per falta de temps per buscar una solució.

Decisions preses i aprenentatges adquirits

Durant el desenvolupament de l’MVP, he pres diverses decisions tècniques i de disseny:

Decisió 1: API externa → Picsum

S’ha triat Picsum com a API externa per:

• Poder obtenir imatges aleatòries per jugar sense necessitat de tenir fotos personals.
• Tenir una resposta en format JSON amb dades útils (com l’autor).
• Evitar complicacions com l’autenticació o l’ús d’API keys.
• Facilitar la idea d’un joc “rejugable”.

Decisió 2: Mostrar l’autor de la imatge

Quan s’utilitza una imatge de Picsum, es mostra un text sota el puzle amb l’autor. Això aporta:

• Transparència.
• Un toc de “crèdit” visual.
• Millor integració amb el requisit de mostrar dades de l’API dins l’app.

Decisió 3: Afegir una previsualització de la imatge original

Com que el puzle pot ser difícil, s’ha afegit:

• Una icona que permet veure la imatge sencera com a referència. No es tracta de la imatge original completa, sinó d’una secció quadrada de la imatge original. Aquesta imatge retallada és la que utilitzarà el puzle.
• Aquesta funcionalitat millora el gameplay i permet resoldre el puzle amb més facilitat.

Aprenentatges principals

• Les funcionalitats natives en apps híbrides poden tenir comportaments diferents segons el dispositiu (càmera frontal invertida, cancel·lacions, permisos…).
• La UI afecta molt l’experiència: cal ajustar espais, alineacions, overlays i coherència visual.

Esbossos, captures i iteracions que mostrin l’evolució del projecte

Iteració 1: MVP funcional (PR1): puzzle amb imatge local i funcionament bàsic:

Iteració 2: Integració de l’API

• Afegir el botó de Picsum per arregar una imatge aleatòria des del JSON.
• Mostrar l’autor de la imatges
• Afegir un HUD amb:
  • Comptador de moviments.
  • Comptador de temps.
  • Icona de previsualització i overlay per mostrar la imatge utilitzada en el puzzle itenir-la de referència.

Justificació breu: problemes trobats, solucions i conclusions

• Problema 1: l’autor desapareix quan es cancel·la galeria/càmera
  Causa: el text de l’autor s’esborrava abans de confirmar que s’havia carregat una nova imatge.
  Solució: netejar l’autor només quan la càrrega de la nova imatge sigui exitosa.
• Problema 2: puzles que començaven ja resolts
  Causa: el shuffle podia deixar el mateix estat final que el puzle resolt.
  Solució: aplicar una comprovació després del shuffle i repetir-lo fins que el puzle no estigui resolt.
• Problema 3: el temps no s’aturava en resoldre el puzle
  Causa: el valor puzzle.solved no s’actualitzava just en el mateix moment del touchStarted.
  Solució: aturar el cronòmetre des del draw() quan el puzle està resolt.

Citació de totes les fonts utilitzades

Documentació oficial / fonts tècniques:

• Capacitor (documentació oficial): Camera Plugin i Haptics Plugin.
• Recursos sobre CORS i consum d’APIs en aplicacions web.

API externa:

• Lorem Picsum API (endpoint /v2/list i càrrega d’imatges per ID).

He utilitzat ChatGPT com a suport per:

• Depurar errors de l’app.
• Proposar estructures de codi.
• Millorar el CSS i la UX.
• Resoldre conflictes d’overlays i layout.

Vídeo

Per realitzar aquest vídeo he utilitzat un ZTE Blade A51, Android versió 11.