Qué hace el SDK
Descripción transparente del fragmento sdk.js que un cliente de QR Location puede incluir en su página de destino. Está escrita para los equipos técnicos del cliente y para cualquier persona que quiera saber qué hace exactamente ese código en su navegador.
En una frase: el SDK lee un token de un solo uso que llega en la dirección de la página, lo borra de la barra de direcciones y, únicamente si la persona hace clic en un botón (o si el gestor de consentimiento del sitio confirma un consentimiento específico de ubicación), pide al navegador una ubicación aproximada una sola vez y la envía junto con la evidencia del consentimiento. No usa cookies ni almacenamiento, no identifica a nadie y no envía nada si no hay token.
1. Cómo se carga y qué expone
El cliente añade <script src="https://qr.saulnoda.com/sdk.js"></script> antes de </body> en su página de destino. El script define un único objeto global, window.qrGeo, con las funciones request(), convert(), hasToken() y la propiedad version. No carga otros scripts, no modifica el contenido de la página y no observa la navegación.
2. Qué no hace
- No escribe ni lee cookies,
localStorage,sessionStorage, IndexedDB ni ninguna otra forma de almacenamiento en el dispositivo. - No genera identificadores ni calcula huellas digitales del navegador o del dispositivo.
- No lee formularios, campos, títulos, texto ni otros datos de la página en la que se incluye.
- No registra páginas vistas, clics ni tiempo de permanencia. No es una herramienta de analítica web.
- No pide la ubicación al cargar, con temporizadores, al hacer scroll ni por ningún evento automático. La versión 2 eliminó los modos automáticos de la versión 1 y no los admite.
- No usa
watchPosition: nunca sigue la ubicación de forma continua ni en segundo plano. - Si la dirección no contiene el token, el SDK no envía absolutamente nada al servidor.
3. Qué lee: el token ?qg=
Cuando un QR está configurado con el disparador de ubicación «botón en la landing» o con el embudo de conversión activado, la redirección del escaneo añade a la URL de destino un parámetro ?qg=… (el nombre puede cambiarse con data-param). Es un token opaco: una referencia firmada a ese escaneo concreto, sin ningún dato de la persona. Caduca a los 20 minutos y solo se acepta una vez para la ubicación.
Lo primero que hace el SDK es eliminar ese parámetro de la barra de direcciones mediante history.replaceState, para que no quede en marcadores, en el historial compartido, en la cabecera Referer hacia otros sitios ni en las herramientas de analítica del propio cliente. El token se conserva únicamente en la memoria de la página hasta que se cierra.
4. Cuándo puede pedir la ubicación
Solo hay tres caminos, y los tres requieren una acción humana o un consentimiento específico previo:
- Clic en un botón marcado con
data-qr-geo. El consentimiento se registra con el métodobutton. - Evento del gestor de consentimiento (CMP). Si el script se incluye con
data-auto="consent", escucha el eventoqr-consent, que el sitio del cliente debe disparar únicamente cuando su banner haya recogido el consentimiento para la finalidad específica de ubicación. Se registra con el métodocmp. - Llamada explícita a
window.qrGeo.request({ noticeVersion: '…' })desde el código del cliente, tras mostrar su propio aviso.
En los tres casos el navegador muestra además su propio permiso de ubicación, que la persona puede denegar. La petición se hace una sola vez por página (la segunda llamada se ignora), con enableHighAccuracy:false (sin GPS de alta precisión) y un tiempo máximo de 10 segundos. Si la persona deniega el permiso, no se envía nada.
5. Qué envía
A /geo, tras el consentimiento
- El token del escaneo.
- Latitud y longitud tal como las entrega el navegador. El servidor las redondea inmediatamente a tres decimales (unos 100 metros) y descarta el valor original; nunca se guarda la coordenada exacta.
- La precisión estimada en metros que informa el navegador, redondeada a metros enteros en el servidor.
- Evidencia del consentimiento: método (
buttonocmp), versión del aviso (data-noticeo el valor pasado arequest()) y versión del SDK. Se guarda junto al escaneo para poder demostrar cómo se obtuvo el consentimiento, sin identificar a la persona.
A /convert, si el cliente usa el embudo
- El token del escaneo, el nombre del evento de conversión (máximo 60 caracteres) y, opcionalmente, un valor numérico. Se dispara con un clic en un elemento
data-qr-convert="nombre"o conwindow.qrGeo.convert('nombre', valor). - El cliente no debe incluir datos personales en el nombre del evento ni en el valor (por ejemplo, correos, teléfonos o referencias de pedido que identifiquen a alguien). QR Location solo conserva la conversión como dato agregado por QR.
Los envíos se hacen con navigator.sendBeacon (o fetch como alternativa) en formato text/plain, sin credenciales y sin cookies. El servidor siempre responde con un código 204 vacío, de modo que la página del cliente no recibe ningún dato de vuelta.
6. El aviso que debe mostrar la página del cliente
El SDK no muestra ningún texto: la información previa es responsabilidad del cliente, que es el responsable del tratamiento. Antes del botón o del evento del CMP, la página debe indicar como mínimo:
- quién pide la ubicación (nombre del cliente) y para qué (medir desde qué zona se usa la campaña);
- que la precisión es aproximada (unos 100 m) y que no se guarda ningún dato que identifique a la persona;
- durante cuánto tiempo se conserva (según el plan: 30 días, 12 o 24 meses);
- que es voluntario y que puede continuar sin compartir, con un botón de igual peso;
- que no se dirige a menores de 14 años;
- un enlace a su política de privacidad y a la página Información para quien escanea un QR.
Recomendamos declarar la versión de ese aviso con data-notice="AAAA-MM" en la etiqueta del script y actualizarla cada vez que cambie el texto; así la evidencia almacenada indica bajo qué aviso se consintió.
7. Ejemplos de integración
<!-- Botón: la persona decide con un clic -->
<script src="https://qr.saulnoda.com/sdk.js" data-notice="2026-10"></script>
<button data-qr-geo>Compartir mi ubicación aproximada</button>
<!-- Gestor de consentimiento: solo tras la finalidad específica "ubicación" -->
<script src="https://qr.saulnoda.com/sdk.js" data-auto="consent" data-notice="2026-10"></script>
<script>
miCMP.on('consent:location', function () {
window.dispatchEvent(new Event('qr-consent'))
})
</script>
<!-- Conversión: un clic de compra o de reserva -->
<button data-qr-convert="compra">Comprar</button>
<!-- o desde código, tras confirmar el pedido: -->
<script>window.qrGeo.convert('compra', 29.9)</script>
8. Versionado
La versión actual del SDK es la 2.0.0 y se expone en window.qrGeo.version. Se sirve siempre la última versión desde /sdk.js. Los cambios que modifiquen qué datos se envían o cuándo puede pedirse la ubicación se publican en esta página con antelación y suponen un nuevo número de versión mayor; los cambios compatibles (correcciones, mejoras internas) incrementan la versión menor o de parche. Historial relevante:
- 2.0.0 — eliminados los modos automáticos (
data-auto="load"y"delayed") y las peticiones por temporizador; se añade la evidencia de consentimiento (método, versión del aviso, versión del SDK); el token pasa a ser opaco y se elimina de la URL; conversiones agregadas. - 1.x — versión inicial, retirada.
Dudas técnicas o de cumplimiento: saul.rodrigueznoda@gmail.com.