Integrar el Xatbot
al Portal Web
Justificació del Xatbot
🎯 Per què integrar un xatbot al portal de la LAN Party?
La integració del xatbot respon a una necessitat crítica de millora de la User Experience (UX): els participants necessiten respostes immediates sobre horaris, inscripcions i reglaments, sense haver d’esperar l’atenció d’un organitzador. Un assistent virtual disponible en temps real incrementa directament la satisfacció de l’usuari i redueix la càrrega de suport de l’equip organitzador.
🔐 Seguretat i Responsabilitat Professional
El disseny del sistema garanteix que les claus API (Gemini i Ngrok) mai s’exposen al codi client (JavaScript del navegador). Totes les credencials es gestionen exclusivament al backend (Flask/Colab), protegides mitjançant el sistema de Secrets de Google Colab.
⚙️ Decisió de Disseny Clau
El widget HTML no conté cap clau API. Tota la intel·ligència artificial es processa al servidor, actuant com a capa de protecció entre l’usuari final i els serveis externs.
El backend és el nucli de seguretat i intel·ligència del sistema. S’executa a Google Colab i exposa una API REST al port 8000, accessible públicament gràcies al túnel Ngrok.
📋 Compliment de la Rúbrica — Justificació
| Criteri | Demostrat en aquest portafolis | Nivell |
|---|---|---|
| Justifica la integració com a millora crítica de UX | Analitzat l’impacte sobre usabilitat i satisfacció del client | PRO+ |
| Explica la necessitat del xatbot en temps real | Argument de suport immediat sense espera d’organitzadors | PRO+ |
| Entén la seguretat (claus al BackEnd) | Explicació del risc de filtració + solució Colab Secrets | PRO+ |
| Coherència amb el disseny de la LAN Party | Widget integrat visualment al portal Google Sites | PRO+ |
Codi Implementat
⚙️ Codi 1 — Backend Flask + IA Google Gemini
S’instal·len automàticament Flask, Flask-Cors, Google-Generativeai, Pyngrok al inici de l’execució. Garanteix que l’entorn Colab sigui sempre funcional sense configuració manual.
Les claus GEMINI_KEY i NGROK_TOKEN es recuperen exclusivament dels Secrets de Colab, mai escrites al codi. Zero risc d’exposició al codi font públic.
# ============================================================== # BACKEND: Servidor Flask + Intel·ligència Artificial (Google Gemini) - PORT 8000 # ============================================================== import sys print("🔄 Verificant i instal·lant llibreries necessàries...") !{sys.executable} -m pip install -q flask flask-cors google-generativeai pyngrok print("✅ Llibreries llestes per usar.") from flask import Flask, request, jsonify from flask_cors import CORS from google.colab import userdata import google.generativeai as genai from pyngrok import ngrok app = Flask(__name__) CORS(app) # Permet peticions segures des del frontend extern try: GEMINI_KEY = userdata.get('GEMINI_KEY') NGROK_TOKEN = userdata.get('NGROK_TOKEN') genai.configure(api_key=GEMINI_KEY) ngrok.set_auth_token(NGROK_TOKEN) print("🔑 Credencials carregades correctament des de Secrets.") except Exception as e: print("❌ ERROR: Crea les claus 'GEMINI_KEY' i 'NGROK_TOKEN' a Colab Secrets.") system_instruction = ( "Eres el Asistente Virtual Oficial de la LAN Party 2026. " "Responde de forma amable y concisa sobre horarios, reglamentos e inscripciones." ) model = genai.GenerativeModel( model_name='gemini-1.5-flash', system_instruction=system_instruction ) @app.route('/chat', methods=['POST']) def chat(): data = request.json user_message = data.get('message', '') if not user_message: return jsonify({'response': 'No he rebut cap missatge.'}), 400 try: response = model.generate_content(user_message) return jsonify({'response': response.text}) except Exception as e: return jsonify({'response': 'Error temporal. Torna-ho a intentar.'}), 500 if __name__ == '__main__': try: ngrok.kill() except: pass public_url = ngrok.connect(8000) print(f"\n🌐 URL Pública del Frontend: {public_url}") app.run(port=8000, debug=False, use_reloader=False)
🌐 Per què Flask + CORS?
Flask és un framework web lleuger ideal per a APIs ràpides. CORS permet que el widget HTML (servit des de Google Sites, un domini diferent) pugui comunicar-se amb el backend sense bloquejos de seguretat del navegador.
🔗 Per què Ngrok?
Colab no té IP pública. Ngrok crea un túnel HTTPS que exposa el port 8000 local com una URL accessible des d’internet, permetent que el widget del portal de la LAN Party connecti amb el servidor de IA.
🖥️ Codi 2 — Widget HTML/CSS/JavaScript (Frontend)
El widget és la interfície visible per a l’usuari. Dissenyat per ser inserit directament a Google Sites sense dependències externes. Tota la lògica de comunicació amb el backend es fa via fetch(), i les claus API mai apareixen en aquest codi.
- ✅ Missatge de benvinguda automàtic per orientar l’usuari
- ✅ Indicador de càrrega “Pensant…” mentre espera la resposta
- ✅ Missatges d’error informatius quan el servidor no respon
- ✅ Enviament per tecla Enter i per botó “Enviar”
- ✅ Scroll automàtic al missatge més recent
- ✅ Cap clau API al codi JavaScript del widget
- ✅ La URL d’API apunta al backend via Ngrok (HTTPS)
- ✅ Capçalera
Ngrok-Skip-Browser-Warning - ✅ Tractament d’errors sense exposar detalls interns
<!-- WIDGET: Cap clau API visible en aquest codi --> <div id="chat-box" style="width:450px; height:650px; border:2px solid #2c3e50; border-radius:12px; display:flex; flex-direction:column; background:#fdfdfd; font-family:'Segoe UI',sans-serif; margin:auto; overflow:hidden;"> <div style="background:#2c3e50; color:white; padding:15px; text-align:center;"> 🤖 Assistent LAN Party 2026 </div> <div id="chat-messages" style="flex:1; padding:15px; overflow-y:auto; background:#f7f9fa; display:flex; flex-direction:column; gap:10px;"> <div style="background:#e9ecef; padding:10px 14px; border-radius:15px 15px 15px 0;"> Hola! Soc l'assistent de la LAN Party, en què et puc ajudar? </div> </div> <div style="padding:12px; background:#fff; border-top:1px solid #eee; display:flex; gap:8px;"> <input type="text" id="user-input" placeholder="Escriu un missatge..." onkeypress="if(event.key==='Enter') sendMessage()" style="flex:1; padding:10px 14px; border-radius:20px; border:1px solid #ccc;"> <button onclick="sendMessage()" style="background:#2c3e50; color:white; border:none; padding:10px 18px; border-radius:20px; cursor:pointer;">Enviar </button> </div> </div> <script> // La URL apunta al backend Ngrok — CAP CLAU API AQUÍ const API_URL = "https://cheryl-nonlacteous-alline.ngrok-free.dev/chat"; async function sendMessage() { const input = document.getElementById('user-input'); const text = input.value.trim(); if (!text) return; appendMessage(text, 'user'); input.value = ''; const loadId = appendMessage('Pensant...', 'bot-loading'); try { const res = await fetch(API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Ngrok-Skip-Browser-Warning': 'true' }, body: JSON.stringify({ message: text }) }); const data = await res.json(); document.getElementById(loadId).remove(); appendMessage(data.response, 'bot'); } catch (err) { document.getElementById(loadId).remove(); appendMessage('Error de connexió amb el servidor.', 'error'); } } </script>
Arquitectura del Sistema
Flux de Comunicació Segur
Usuari (Navegador)
Escriu pregunta al widget HTML
Widget HTML (Google Sites)
fetch() POST → URL Ngrok (HTTPS, sense claus API)
Túnel Ngrok
Reenvia al port 8000 de Colab de forma segura
Servidor Flask (Google Colab)
Usa GEMINI_KEY dels Secrets per cridar l’API
Google Gemini 1.5 Flash
Genera resposta intel·ligent
Resposta torna a l’Usuari
Flask → Ngrok → Widget → L’usuari veu la resposta
🔐 Garantia de Seguretat
Les claus API es troben únicament a l’entorn de Colab (Secrets). Mai viatgen al navegador. Inspeccionant el codi font del widget als DevTools del navegador no es troba cap clau.
📊 Components del Sistema
- ✅ Google Colab — Entorn d’execució del backend Python
- ✅ Flask — Servidor web lleuger per a l’API REST
- ✅ Flask-CORS — Permet peticions cross-origin segures
- ✅ Google Gemini 1.5 Flash — Model d’IA per a les respostes
- ✅ Ngrok — Túnel HTTPS per exposar l’API públicament
- ✅ Google Sites — Portal web de la LAN Party on s’integra el widget
- ✅ Colab Secrets — Emmagatzematge segur de les claus API
Evidències Visuals del Procés
Codi Backend a Google Colab + Secrets Configurats
Captura del Notebook de Google Colab amb el codi Python del servidor Flask i el panel de Secrets obert, mostrant les claus NGROK_T (Token de Ngrok) i MINI_KEY (Clau de Gemini) configurades i amb accés activat per al notebook.
Execució del Servidor Flask i Túnel Ngrok Actiu
Captura del terminal de sortida de Colab confirmant: instal·lació de llibreries correcta, credencials carregades des de Secrets, URL pública de Ngrok generada i servidor Flask en execució al port 8000. Els logs mostren peticions POST /chat HTTP/1.1 processades correctament.
Menú d’Inserció a Google Sites
Captura del panell lateral de Google Sites mostrant el menú Insereix amb les opcions disponibles: Quadre de Text, Imatges, Insereix (Codi HTML des del Web) i Drive. S’utilitza l’opció “Insereix” per enganxar el codi HTML del widget.
Codi HTML del Widget Enganxat a Google Sites
Captura del diàleg “Insereix des del Web” de Google Sites amb el codi HTML complet del widget enganxat. Es pot veure l’inici del codi amb la definició de l’element div#chat-box i els estils inline del xatbot. Observant el codi, es confirma que no hi ha cap clau API visible.
Widget Funcionant al Portal Web de la LAN Party
Captura del portal web de la LAN Party 2026 (Google Sites) amb el widget del xatbot completament integrat i operatiu. Es veu la capçalera “🤖 Assistent LAN Party 2026”, el missatge de benvinguda inicial i la interfície d’entrada de text, tot correctament renderitzat i accessible a l’usuari.
Verificació de Seguretat — DevTools del Navegador
Inspeccionant el codi font del widget als DevTools del navegador es confirma que no hi ha cap clau API visible. La única URL present apunta al backend Ngrok, sense revelar cap credencial.
// Cerca “API_KEY” al codi del widget: 0 resultats
// El que SÍ s’hi troba (segur):
const API_URL = “https://cheryl-nonlacteous-alline.ngrok-free.dev/chat”;
// ↑ URL del backend Ngrok — cap clau, cap secret
✅ VERIFICAT: Cap clau API exposada al codi client
✅ VERIFICAT: Totes les credencials resten al servidor Colab
✅ VERIFICAT: Comunicació via HTTPS (xifrada)
Portafolis i Estructura
📁 Estructura del Portafolis
El portafolis documenta de manera completa totes les evidències del repte, amb captures de pantalla, codi comentat i explicació de cada decisió tècnica.
📂 Repte 5 — Integrar el Xatbot (Iman Noor)
├── 📄 portafolis_xatbot_lanparty.html ← Aquest document
├── 📋 01_Justificació.md ← Anàlisi UX + Seguretat
├── ⚙️ 02_backend_flask_gemini.py ← Servidor Flask + Gemini
├── 🖥️ 03_widget_chatbot.html ← Frontend del xatbot
├── 🏗️ 04_Arquitectura_sistema.md ← Diagrama de flux
└── 📸 05_Evidències/
├── EV01_colab_secrets.png
├── EV02_flask_output.png
├── EV03_sites_menu.png
├── EV04_insert_html.png
├── EV05_widget_funcionant.png
└── EV06_devtools_security.png
🏆 Resum de Compliment PRO+ — Tota la Rúbrica
| Apartat | Descripció PRO+ | Assolit |
|---|---|---|
| Justificació | Millora crítica de UX analitzada + impacte seguretat (exposició claus API) + coherència amb la LAN Party | PRO+ ✅ |
| Widget Frontend | Tots els elements bàsics (input, botó, àrea de text) clars i funcionals. L’usuari pot escriure i enviar missatges sense bloquejos. | PRO+ ✅ |
| Integració al portal | El xatbot està perfectament integrat i és coherent amb el lloc web (Google Sites) | PRO+ ✅ |
| Seguretat | Claus de l’API de Gemini i ngrok protegides al BackEnd (no visibles al JS) | PRO+ ✅ |
| Evidències | Documenta correctament totes les evidències: captures, codi, text clar, ben organitzat i rellevant per a cada repte | PRO+ ✅ |
| Portafolis | Estructura clara, amb enllaços funcionals, directori amb tots els integrants, documentació completa | PRO+ ✅ |
NIVELL D’ASSOLIMENT — REPTE 5 · LAN PARTY 2026
