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

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:

  1. Clic en un botón marcado con data-qr-geo. El consentimiento se registra con el método button.
  2. Evento del gestor de consentimiento (CMP). Si el script se incluye con data-auto="consent", escucha el evento qr-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étodo cmp.
  3. 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

A /convert, si el cliente usa el embudo

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:

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:

Dudas técnicas o de cumplimiento: saul.rodrigueznoda@gmail.com.