Cómo Generar e Incrustar Códigos QR
Necesitas añadir un código QR a tu aplicación web. Tal vez sea para un flujo de pago, un enlace compartible o entradas para eventos. La pregunta no es si usar un código QR, sino cómo generar uno de manera confiable en el navegador sin introducir problemas de escaneo o de seguridad.
Este artículo cubre la generación de códigos QR del lado del cliente en JavaScript, explica cuándo usar salida SVG versus Canvas, y aborda las restricciones prácticas que afectan la confiabilidad del escaneo.
Puntos Clave
- Genera códigos QR en JavaScript usando bibliotecas establecidas—no construyas la lógica de codificación desde cero
- Elige SVG para incrustación web escalable, Canvas para manipulación programática de imágenes
- Respeta las zonas de silencio, mantén el contraste y prueba con dispositivos de escaneo reales
- Proporciona alternativas visibles para accesibilidad y seguridad
Entendiendo la Generación vs. el Escaneo de Códigos QR
Antes de escribir cualquier código, distingue entre dos problemas separados: generación y escaneo.
La generación ocurre completamente bajo tu control. Codificas datos en una imagen de código QR usando bibliotecas de JavaScript. Esto funciona de manera confiable en todos los navegadores modernos.
El escaneo es diferente. Las APIs nativas del navegador para leer códigos QR (como la Barcode Detection API) siguen siendo experimentales y carecen de soporte universal. Si tu aplicación necesita escaneo, planifica alternativas—típicamente una biblioteca JavaScript basada en cámara o campos de entrada manual.
Este artículo se enfoca en la generación. No confundas ambos al planificar tu implementación.
Cómo Generar Códigos QR en JavaScript
Varias bibliotecas de JavaScript manejan la generación de códigos QR para trabajo frontend. Las opciones comunes incluyen qrcode, que soporta generación tanto del lado del cliente como del servidor, qrcode-generator, un codificador ligero en JavaScript puro, y la más antigua pero aún ampliamente usada QRCode.js para salida simple en Canvas o DOM. Ninguna de estas es “el estándar”—cada una tiene compensaciones en tamaño de bundle, formatos de salida y opciones de personalización.
El patrón general se ve así:
- Importa la biblioteca elegida
- Pasa los datos que deseas codificar (URL, texto, datos vCard)
- Especifica el formato de salida y dimensiones
- Renderiza a un elemento DOM o extrae como data URL
La mayoría de las bibliotecas aceptan configuración para niveles de corrección de errores (L, M, Q, H). Los niveles más altos permiten que más parte del código se dañe mientras permanece escaneable—útil si planeas superponer logos o imprimir en superficies texturizadas.
Códigos QR: SVG vs Canvas
Cuando incrustas códigos QR en la web, típicamente elegirás entre tres formatos de salida: SVG, Canvas o PNG/data URLs.
Salida SVG
SVG es usualmente la mejor opción para incrustación web. El formato vectorial escala infinitamente sin pixelación, haciéndolo ideal para diseños responsivos y aplicaciones de impresión. Los tamaños de archivo permanecen pequeños independientemente de las dimensiones de visualización. El estilo CSS funciona naturalmente.
Usa SVG cuando:
- El código QR aparece en tamaños variables
- La calidad de impresión importa
- Necesitas estilo o animación basados en CSS
Salida Canvas
Canvas renderiza a un mapa de bits en una resolución específica. Esto funciona bien cuando necesitas control a nivel de píxel o planeas componer el código QR con otros gráficos programáticamente.
Usa Canvas cuando:
- Estás generando imágenes para descarga
- Necesitas manipular píxeles directamente
- Estás integrando con otros gráficos basados en Canvas
PNG/Data URLs
Los data URLs te permiten incrustar el código QR como una cadena de imagen codificada en base64. Esto elimina solicitudes HTTP adicionales pero aumenta el tamaño del payload HTML. Útil para plantillas de correo electrónico o contextos donde los recursos externos no son confiables.
Discover how at OpenReplay.com.
Restricciones Prácticas que Afectan la Confiabilidad del Escaneo
Un código QR que se ve correcto aún podría fallar al escanearse. Presta atención a estos problemas:
Zonas de silencio: Los códigos QR requieren espacio vacío alrededor de sus bordes—típicamente cuatro módulos de ancho. Recortar este margen rompe el escaneo.
Contraste: La especificación asume módulos oscuros sobre un fondo claro. Los colores invertidos o combinaciones de bajo contraste reducen la confiabilidad. Apunta a una relación de contraste de al menos 4:1.
Dimensionamiento: El tamaño mínimo escaneable depende de la distancia de visualización y la calidad de la cámara. Para visualización en pantalla, los tamaños más pequeños pueden funcionar en dispositivos modernos, pero los resultados dependen de la distancia de visualización y la calidad de la cámara. Para impresión, calcula basándote en la distancia de escaneo esperada.
Superposición de logos y estilizado pesado: Añadir logos al centro explota la corrección de errores—el escáner trata el logo como daño y reconstruye los datos. Esto solo funciona con niveles de corrección de errores más altos (Q o H), y el estilizado agresivo puede superar los límites recuperables. Prueba exhaustivamente.
Consideraciones de Seguridad y UX
Los códigos QR que codifican URLs crean oportunidades de phishing. Los usuarios no pueden inspeccionar el destino antes de escanear. Si tu aplicación genera códigos QR a partir de entrada del usuario, valida y sanea esa entrada. Considera mostrar la URL codificada como texto visible junto al código.
Para accesibilidad, siempre proporciona la información codificada en un formato alternativo. Un enlace visible junto al código QR sirve a usuarios que no pueden o no quieren escanear.
Generación del Lado del Servidor
Aunque este artículo se enfoca en enfoques del lado del cliente, la generación del lado del servidor tiene usos legítimos: reducir el tamaño del bundle del cliente, cachear códigos generados, o generar códigos en entornos sin JavaScript. Existen bibliotecas para Node.js, Python, Go y la mayoría de otros lenguajes backend. Las consideraciones de formato de salida permanecen iguales.
Conclusión
La implementación técnica de la generación de códigos QR es directa. Usa bibliotecas de JavaScript establecidas en lugar de construir lógica de codificación desde cero. Elige SVG para incrustación web escalable y Canvas para manipulación programática de imágenes. La confiabilidad de tus códigos QR proviene de respetar las restricciones: mantén las zonas de silencio, asegura el contraste adecuado y prueba con dispositivos de escaneo reales. Siempre proporciona alternativas visibles tanto para propósitos de accesibilidad como de seguridad.
Preguntas Frecuentes
Los niveles de corrección de errores determinan cuánto daño puede soportar un código QR mientras permanece escaneable. L recupera aproximadamente 7% de daño, M recupera 15%, Q recupera 25% y H recupera 30%. Usa niveles más altos (Q o H) al añadir superposiciones de logos o imprimir en superficies texturizadas, ya que el escáner trata estas modificaciones como daño y reconstruye los datos faltantes.
Las causas comunes incluyen zonas de silencio recortadas (el borde vacío alrededor del código), contraste insuficiente entre módulos oscuros y claros, o dimensionamiento demasiado pequeño para la distancia de escaneo. Asegura al menos cuatro módulos de espacio vacío alrededor del borde, mantén una relación de contraste mínima de 4:1 y prueba a la distancia de visualización real con dispositivos reales.
La generación del lado del cliente funciona bien para la mayoría de aplicaciones web y reduce la carga del servidor. La generación del lado del servidor tiene sentido cuando necesitas reducir el tamaño del bundle del cliente, cachear códigos generados para reutilización, o generar códigos en entornos sin JavaScript. Ambos enfoques producen salida idéntica—elige según las necesidades de tu arquitectura.
Sí, pero solo con niveles de corrección de errores más altos (Q o H). El escáner trata el logo como daño y usa la corrección de errores para reconstruir los datos. Mantén los logos pequeños, centrados y prueba exhaustivamente con múltiples aplicaciones de escaneo. El estilizado agresivo o logos sobredimensionados pueden exceder los límites recuperables y romper el escaneo por completo.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
