Documentación para desarrolladores

Todo lo que necesitas para integrar seeonwall.com en tu tienda online.

¿Estás configurando una tienda? Las guías de instalación y las guías paso a paso están en las páginas de ayuda. Ayuda →

Inicio rápido

Pon todo en marcha en menos de 5 minutos.

1

Crea una cuenta

Crea una cuenta gratuita en seeonwall.com.

Regístrate gratis →
2

Añade la etiqueta de script

Después de iniciar sesión, copia el snippet de tu panel y pégalo en la sección <head> de tu tienda.

<script async
  src="https://seeonwall.com/seeonwall.js"
  data-shop-id="YOUR_SHOP_ID"
></script>
3

Añade botones a las páginas de producto

Coloca un elemento .seeonwall-button donde quieras que aparezca un botón de vista previa. El snippet inyecta automáticamente un botón estilizado "Ver en la pared" dentro de él.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"></div>

Instalación

Pega este snippet en el <head> de cada página donde deba aparecer el botón de vista previa.

<script async
  src="https://seeonwall.com/seeonwall.js"
  data-shop-id="YOUR_SHOP_ID"
  data-lang="en"
></script>

Atributos de la etiqueta de script

AtributoObligatorioDescripción
data-shop-idSíTu ID de tienda del panel de administración. Obligatorio.
data-langNoIdioma para el botón y la interfaz del visualizador. Valores aceptados: en, pl, de, es, fr, it, pt, nl, sv, nb, da, fi, cs, sk, uk, ru. Si se omite, el snippet lee el atributo <html lang> de la página y se actualiza automáticamente al cambiar — no se necesita configuración adicional para los cambiadores de idioma en SPA.

Marcado del botón

Cualquier elemento con la clase seeonwall-button se convierte en un punto de montaje. El snippet inyecta un botón estilizado "Ver en la pared" dentro de él.

Ejemplo mínimo

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"></div>

Con múltiples tamaños

Cuando data-poster-sizes contiene más de un tamaño, el visualizador muestra una fila de botones de tamaño en la vista previa final: tanto en el escritorio como en el móvil. Cuando data-poster-width y data-poster-height también están presentes, determinan el tamaño seleccionado inicialmente (coincidencia más cercana por área). Si se omiten, se selecciona el tamaño del medio por defecto (con un número par, el menor de los dos del medio).

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-title="Abstract Mountains"
     data-poster-width="50"
     data-poster-height="70"
     data-poster-sizes="30x40,50x70,70x100"
     data-product-page-url="https://example.com/products/abstract-mountains"></div>

Unidades y formatos de papel

Cualquier dimensión puede indicar su propia unidad — "24cm", "10in", '11"' — o nombrar un formato ISO: "a4" en data-poster-width son 21cm y en data-poster-height 29,7cm, así que escribirlo en ambos declara un póster A4. Las listas de tamaños admiten las mismas formas por entrada, de modo que una lista puede mezclarlas. Los compradores ven cada tamaño etiquetado tal y como lo escribiste.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="18in"
     data-poster-height="24in"
     data-poster-sizes="12x16in,18x24in,a3"></div>

Una unidad por defecto para toda la tienda

data-size-unit fija la unidad de los valores que no indican ninguna. También puede ir en la etiqueta <script> para cubrir toda la tienda. Nunca sobrescribe un valor que ya indicó su unidad.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-size-unit="in"
     data-poster-width="18"
     data-poster-height="24"
     data-poster-sizes="12x16,18x24,24x36"></div>

Láminas enmarcadas

Las vistas previas se muestran sin marco de forma predeterminada, igual que la lámina suelta que vende la mayoría de las tiendas, salvo que un marco de tu panel esté configurado para abrir las vistas previas. Si el precio de tu página incluye un marco, define data-frame-default-cm para que la vista previa se abra enmarcada.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-frame-default-cm="2"
     data-frame-default-color="#3E2723"></div>

Tus propios marcos

Si has creado un catálogo de marcos en tu panel de seeonwall.com, nombra uno aquí y la vista previa se abrirá con él: tu nombre, tu anchura, tu color. Tiene prioridad sobre data-frame-default-cm y data-frame-default-color.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-frame-preset="Oak"></div>

El nombre es la clave. Debe coincidir exactamente con un marco de tu catálogo, salvo mayúsculas y minúsculas. Si renombras un marco en el panel, este código deja de coincidir: cambia ambos a la vez. Si un comprador elige otra variante de marco en tu página, reescribe este atributo y una vista previa abierta lo seguirá, hasta que el comprador elija su propio marco, que siempre gana.

→ Guía paso a paso: Muestra los marcos que vendes

Limitar los marcos que puede elegir el cliente

Añade data-frame-options para ofrecer solo los marcos que vendes con este producto. La vista previa muestra un botón para cada marco y ningún control de ancho, color o paspartú. Usa null para una lámina sin marco. Una lista con una entrada fija el marco: ["Roble"] siempre muestra Roble, [null] siempre muestra sin marco. Sin el atributo, se aplica el ajuste de Marcos en tu panel.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="54"
     data-poster-height="74"
     data-frame-options='["Oak", "Black"]'
     data-frame-size-included="true"></div>

Si el tamaño que indicas es el tamaño exterior del producto enmarcado, añade data-frame-size-included="true". La vista previa dibuja entonces la obra más pequeña en dos anchos de marco, así el póster enmarcado tiene el tamaño indicado sea cual sea el marco que elija el cliente. Con «Sin marco», la obra tiene el tamaño indicado. Un producto con data-poster-mat ignora este atributo.

Añadir al carrito desde la vista previa

Dile al snippet qué vendes de este póster. Cuando el tamaño y el marco que ve el comprador coinciden con una oferta comprable, la vista previa terminada muestra un icono compacto de carrito con un signo más junto a pantalla completa, etiquetado Añadir al carrito. Cada oferta es un tamaño vendido en un marco de tu catálogo de marcos de seeonwall.com, o sin marco, escrito como null. La clave es tuya: nunca la leemos, solo la devolvemos. La purchaseUrl es una página que añade exactamente esa oferta cuando un navegador la abre; es lo que hace que el control diga Añadir al carrito y no necesita JavaScript por tu parte. La productUrl muestra la oferta, idealmente preseleccionada. Las URL relativas valen.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-sizes="30x40cm,50x70cm"
     data-product-page-url="/products/aurora"
     data-poster-offers='[
       {"key": "print-30x40", "width": "30cm", "height": "40cm", "framePreset": null,
        "productUrl": "/products/aurora?offer=print-30x40",
        "purchaseUrl": "/cart/add/print-30x40"},
       {"key": "oak-50x70", "width": "50cm", "height": "70cm", "framePreset": "Oak",
        "label": "Large", "image": "https://example.com/aurora-oak-50x70.jpg",
        "drawFrame": "forbidden",
        "productUrl": "/products/aurora?offer=oak-50x70",
        "purchaseUrl": "/cart/add/oak-50x70"}
     ]'></div>

El snippet coincide exactamente o no coincide. Una selección que no coincide con ninguna oferta, o con dos, abre la página del producto en su lugar: eso incluye un paspartú en un marco de tu catálogo y un tamaño que no listes. Un marco que el comprador combinó por su cuenta, con o sin paspartú, coincide con tu oferta sin marco de ese tamaño: el comprador enmarca la lámina, así que solo la lámina va al carrito. Cuando ninguna de tus ofertas indica un marco, el producto se vende solo como lámina: entonces un marco de tu catálogo también coincide con tu oferta sin marco de ese tamaño, y el comprador añade el marco por separado. El marco de data-frame-default-cm es tuyo, no del comprador, así que no coincide con ninguna oferta hasta que el comprador lo cambie. Las claves, productUrl y purchaseUrl se quedan en tu página, y el snippet hace la coincidencia allí. La vista previa solo recibe el label de cada oferta, en su lista de tamaños, y el tamaño, framePreset, image y drawFrame de cada oferta con imagen: el snippet los guarda en seeonwall.com y la vista previa los lee mediante un ID. Hasta 250 ofertas por botón; una lista más larga se ignora entera, y una oferta sin tamaño, con una URL no válida o con una clave repetida se omite. Hasta 200 de las ofertas pueden tener imagen, y la lista que guarda el snippet puede tener hasta 54.000 caracteres; si se supera cualquiera de los dos límites, la vista previa no usa ninguna imagen de oferta para ese botón. Una oferta no lleva precio a propósito: tus páginas de producto y de carrito siguen siendo la autoridad del precio.

Tres campos opcionales muestran cada variante en la vista previa. image es una URL https absoluta de una imagen de esta variante: este tamaño en este marco. drawFrame es "inherit", el valor por defecto, o "forbidden". Con inherit, la vista previa dibuja el marco elegido sobre la imagen. Usa forbidden cuando la imagen ya muestra el marco o cuando la obra no debe llevar marco: la vista previa muestra la imagen tal cual, con el tamaño declarado de la oferta como tamaño exterior, y no dibuja marco ni paspartú. En un tamaño que tiene una imagen forbidden, cada opción de marco sin imagen propia en ese tamaño queda desactivada, también sin marco y un marco que el comprador combinó por su cuenta. label es el nombre del tamaño, como máximo 32 caracteres, que se muestra en el selector de tamaño. Las ofertas no cambian qué tamaños y marcos puede elegir el comprador: eso lo siguen decidiendo data-poster-sizes y los ajustes de marcos. Un tamaño o un marco sin imagen propia usa la imagen sin marco de ese tamaño y, si no la hay, data-poster-url. Si tu lista de Dominios permitidos no está vacía, el dominio de cada imagen debe estar en ella; si no, se rechaza la lista entera y la vista previa muestra data-poster-url. La consola del navegador muestra un aviso cuando las ofertas y los tamaños del botón no coinciden.

En escritorio, el snippet lanza un evento cancelable seeonwall:purchase-request en window (SeeOnWall.on('purchase-request') se suscribe a él) antes de navegar a la purchaseUrl. Escúchalo para añadir con tu propia API de carrito en su lugar, por ejemplo para un carrito lateral o un carrito Ajax. Llama a preventDefault() de forma síncrona, añade la oferta que nombra selectionKey y navega después a tu carrito. Si añadir falla, llama a navigateFallback(): abre la página del producto y nunca la URL de compra, que podría añadir dos veces. En el móvil la vista previa navega por sí misma a la purchaseUrl, así que el evento es una mejora para escritorio, no un requisito. Las tiendas Shopify y WooCommerce reciben las ofertas y el adaptador de la app y del plugin.

// Optional: add with your own cart API instead of the purchaseUrl
// onSeeOnWall() waits for the async script tag. See JavaScript API.
onSeeOnWall(() => {
  const unsubscribe = SeeOnWall.on('purchase-request', (event) => {
    event.preventDefault()                       // take the request over
    const { selectionKey, navigateFallback } = event.detail
    addToCart(selectionKey)                      // your cart call, keyed by your offer key
      .then(() => location.assign('/cart'))
      .catch(() => navigateFallback())           // the product page, never the purchase URL
  })
})

Imágenes de producto tipo mockup

Si la foto de tu producto es un mockup — la lámina sobre un fondo de color, o dentro de un marco — la vista previa muestra esa foto entera al tamaño del póster, así que la lámina parece más pequeña de lo que será en la pared. Configura data-poster-inset con el rectángulo que ocupa realmente la lámina, como porcentajes izquierda,arriba,ancho,alto (p. ej. 14.07,23.6,70.07,50.2). Como los mockups suelen generarse a partir de una plantilla, un solo valor normalmente cubre todo tu catálogo. Omítelo si tus imágenes son la obra en sí. Los comercios de Shopify lo configuran por producto en el metacampo «Poster artwork inset»; los de WooCommerce lo dibujan en la pestaña «seeonwall.com» del producto, en «Área de la obra». En Shopify el recorte solo se aplica si está configurado el metacampo «Poster image», y en WooCommerce si en esa pestaña se ha elegido una imagen del póster: el rectángulo se mide sobre esa imagen concreta, y la imagen de producto de la tienda puede cambiar (Shopify la sustituye según la variante seleccionada).

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster-mockup.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-poster-inset="14.07,23.6,70.07,50.2"></div>

Paspartús que forman parte del producto

Si la lámina que vendes incluye un paspartú, decláralo para que la vista previa lo muestre y mantenga el tamaño real de la lámina. data-poster-mat indica, para cada tamaño, cómo es el paspartú, y data-poster-mat-color su color. Hay dos casos, y cuál se aplica depende de lo que describen tus tamaños.

El tamaño es la lámina y el paspartú va alrededor. Escribe el tamaño de la lámina, dos puntos y el tamaño exterior del paspartú: 21x30:30x40 es una lámina de 21 × 30 cm en un paspartú de 30 × 40 cm. La lámina conserva su tamaño, el objeto en la pared mide 30 × 40 cm y el paspartú tiene 4,5 cm en los laterales y 5 cm arriba y abajo.

<!-- A 21x30 or 30x40 print; on the 21x30 the mat adds 4.5 cm at the sides and 5 cm at the top and bottom, on the 30x40 5 cm on every side -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-sizes="21x30,30x40"
     data-poster-mat="21x30:30x40, 30x40:40x50"
     data-poster-mat-color="#FFFFFF"></div>

El tamaño incluye el paspartú y la obra es más pequeña. Escribe el tamaño, dos puntos y la ventana del paspartú: 30x40:21x30 es un producto de 30 × 40 cm con una ventana de 21 × 30 cm. O escribe un ancho para los cuatro lados: 50x70:5 es un paspartú de 5 cm dentro de un producto de 50 × 70 cm. Un ancho sin tamaño delante (3 en este ejemplo) se aplica a todos los tamaños que no nombra otra entrada.

<!-- A 30x40 or 50x70 print whose outer size includes the mat -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-sizes="30x40,50x70"
     data-poster-mat="3, 30x40:21x30"
     data-poster-mat-color="#F5F0E8"></div>

Los tamaños y anchos usan la misma notación que data-poster-sizes, y un número sin unidad está en data-size-unit. Un tamaño mayor que el tamaño antes de los dos puntos es el tamaño exterior del paspartú; uno menor es la ventana. Los tamaños coinciden en cualquier orientación y el paspartú gira con la lámina. Un tamaño sin entrada, y una entrada que no deja ventana, no muestran paspartú. Las comas separan las entradas, así que usa un punto para los decimales. data-poster-mat-color admite un color #RRGGBB y es blanco si se omite.

Si los compradores eligen el paspartú en tu página de producto, actualiza los dos atributos cuando lo hagan: pon en data-poster-mat-color el color elegido y quita data-poster-mat cuando elijan sin paspartú. El botón lee ambos al hacer clic. Los mismos valores se pasan a SeeOnWall.open() y SeeOnWall.openCataloguePreview() como posterMat y posterMatColor. Sin editar el código, marca «Se vende con paspartú»: en Shopify al editar un producto en la página «Tus pósteres» de la app seeonwall.com (o rellena los metacampos Poster mat y Poster mat colour), en WooCommerce en la pestaña seeonwall.com del producto y, para los enlaces de vista previa, en el formulario de creación. Así se define un paspartú por producto; un paspartú que el comprador elige por variante aún no es compatible.

En la vista previa el paspartú no necesita marco. Un marco que añada el comprador va alrededor del paspartú, y la opción de paspartú propia del comprador se oculta mientras el producto tenga uno. Las imágenes descargadas, los enlaces compartidos, los favoritos y los pósteres vistos recientemente también muestran el paspartú.

Idioma por botón

Añade data-lang a un elemento de botón individual para fijarlo a un idioma específico, independientemente del idioma global del snippet. Tanto la etiqueta del botón como el visualizador abierto desde él usarán ese idioma.

<div class="seeonwall-button"
     data-lang="pl"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"></div>

Forma del botón

De forma predeterminada, el botón está relleno con nuestros colores. data-button-variant cambia su forma: «outline» mantiene la misma caja sin relleno, «glyph» es un icono con texto sin caja alguna, e «icon» es solo el icono. Las formas sin relleno toman el color del texto que las rodea, por lo que siguen tu tema, también en modo oscuro. Con «icon», el texto del botón se sigue usando como información sobre herramientas y como etiqueta para lectores de pantalla. Los atributos de color siguen aplicándose donde la forma puede usarlos: data-text-color pinta la etiqueta y el icono —y el borde de la forma de contorno, salvo que data-border-color diga otra cosa—, mientras que data-bg-color solo llega al botón sólido.

sin atributo: el valor por defecto
data-button-variant="outline"
data-button-variant="glyph"
data-button-variant="icon"

Esos cuatro botones son reales: los inserta el mismo script que describe esta página. Haz clic en cualquiera para abrir la vista previa con una lámina de nuestra tienda de demostración.

<!-- An icon and a label, with no box around them -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-button-variant="glyph"></div>

<!-- The icon on its own, beside your Add to cart button -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-button-variant="icon"></div>

<!-- The mark and the label in your own colour -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-button-variant="glyph"
     data-text-color="#2f5d50"></div>

Igualar el botón de tu tema

En lugar de fijar a mano la tipografía, el tamaño, las esquinas y el espaciado, apunta al botón que tu tema ya tiene. data-match-button="auto" encuentra tu botón «Añadir al carrito» y copia su forma y su tipografía. Pasa un selector CSS en lugar de "auto" para indicar un botón concreto.

<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-match-button="auto"></div>

<!-- Or name the button to copy, when "auto" picks the wrong one -->
<div class="seeonwall-button"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"
     data-match-button=".my-theme-add-to-cart"
     data-match-colors="true"></div>

Los colores no se copian salvo que añadas data-match-colors="true". Por defecto el botón conserva tus propios ajustes de color, de modo que se lee como una acción secundaria y no como un segundo «Añadir al carrito».

Atributos del elemento de botón

AtributoObligatorioDescripción
data-poster-urlSíURL absoluta de la imagen del póster. Obligatorio.
data-poster-titleNoTítulo del póster que se muestra en la cabecera del visualizador.
data-poster-widthSíAncho del póster en data-size-unit (centímetros por defecto). Obligatorio a menos que se use data-poster-sizes. Junto con data-poster-sizes determina el tamaño seleccionado inicialmente.
data-poster-heightSíAlto del póster en data-size-unit (centímetros por defecto). Obligatorio a menos que se use data-poster-sizes. Junto con data-poster-sizes determina el tamaño seleccionado inicialmente.
data-size-unitNoUnidad para data-poster-width, data-poster-height y data-poster-sizes: "cm" (por defecto) o "in".
data-poster-sizesNoTamaños separados por comas, cada uno un par AnchoxAlto o un nombre de formato: 30x40cm, 18x24in, a4. Activa el selector de tamaño. Para dar nombre a un tamaño, escribe el nombre y = delante: Grande=50x70cm. El botón del tamaño muestra el nombre con el tamaño al lado. Un nombre puede tener como máximo 32 caracteres y no puede contener comas ni =. Las comas separan entradas, así que usa un punto decimal: 21x29.7cm, no 21x29,7cm. La lista completa puede tener como máximo 1000 caracteres. Con una lista más larga, la vista previa no muestra el selector de tamaño.
data-sizes-fromNoLee los tamaños de un campo de tamaño ya presente en la página en lugar de este elemento. "auto" busca el campo dentro del formulario del producto; también admite un selector CSS como select[name="size"]. Las opciones cuentan como tamaño cuando se leen como 60x40cm, 18x24in o A4. Cumple por sí solo el requisito de tamaño, prevalece sobre data-poster-sizes y sobre el ancho y el alto cuando se lee un campo, y sigue la selección del comprador.
data-frame-default-cmNoAncho en centímetros del marco con el que empieza la vista previa, por ejemplo 2. Si se omite o es 0, el póster se muestra sin marco, salvo que un marco de tu panel esté configurado para abrir las vistas previas: ese marco tiene prioridad sobre este atributo. Defínelo solo si el precio indicado incluye un marco.
data-frame-default-colorNoColor de ese marco predeterminado como valor hexadecimal de 6 dígitos, por ejemplo #3E2723. Se ignora salvo que data-frame-default-cm sea mayor que 0. El valor predeterminado es negro.
data-frame-presetNoNombre de un marco de tu catálogo de marcos de seeonwall.com, p. ej. Roble. La vista previa se abre con ese marco. Tiene prioridad sobre los dos atributos anteriores. Un nombre desconocido se ignora.
data-frame-optionsNoArray JSON de nombres de marcos de tu catálogo de marcos, y null para sin marco, p. ej. ["Roble", null]. El cliente solo puede elegir estos marcos. Con una entrada, la vista previa siempre la muestra y no tiene controles de marco. Un nombre que no está en tu catálogo se elimina.
data-frame-size-includedNoPonlo en true cuando el tamaño del póster incluye el marco. La vista previa dibuja la obra más pequeña en dos anchos de marco. Solo funciona con un data-frame-options que nombra al menos un marco.
data-poster-insetNoDónde está la obra dentro de la imagen del producto, como porcentajes izquierda,arriba,ancho,alto, p. ej. 14.07,23.6,70.07,50.2. Úsalo cuando la imagen sea un mockup con margen o marco para que la lámina se previsualice a su tamaño real. Si se omite —o si el valor es inválido— se usa la imagen completa.
data-poster-matNoUn paspartú que forma parte del producto, para cada tamaño. 21x30:30x40 pone una lámina de 21×30 en un paspartú de 30×40; 30x40:21x30 da a un producto de 30×40 una ventana de 21×30; 50x70:5 es un paspartú de 5 cm dentro del 50×70; un ancho solo se aplica a todos los tamaños no nombrados. Si se omite, o para un tamaño sin entrada, no se muestra paspartú.
data-poster-mat-colorNoColor del paspartú como #RRGGBB, p. ej. #F5F0E8. Blanco si se omite.
data-poster-fitNoCómo entra la imagen en un tamaño de otras proporciones. auto (predeterminado) estira la imagen hasta un 8 % y recorta de los bordes solo el resto, así que el texto cerca de los bordes suele seguir visible. cover recorta el centro de la imagen al tamaño, como CSS object-fit: cover. stretch llena el tamaño con la imagen completa, como object-fit: fill, y deforma la obra. Cualquier otro valor se lee como auto.
data-product-page-urlNoURL explícita de la página del producto. Cuando se establece, los enlaces de marcador apuntan aquí en lugar de la página donde se hizo clic en el botón. Útil en páginas de listado o búsqueda.
data-poster-offersNoArray JSON con lo que vendes de este póster: key, width, height, framePreset (un marco de tu catálogo o null para sin marco), productUrl, purchaseUrl y, opcionalmente, image, drawFrame y label. Da a la vista previa terminada un icono compacto de carrito con un signo más, etiquetado Añadir al carrito, o la acción Ver producto. Consulta Añadir al carrito desde la vista previa.
data-gallery-wallNo"off" deja este póster solo en su pared: los clientes no pueden colgar otros pósteres a su lado. Omítelo para que el póster pueda compartir pared. Solo se aplica si las paredes de galería están activadas en los ajustes de la tienda.
data-langNoFija este botón a un idioma específico (en, pl, de, es, fr, it, pt, nl, sv, nb, da, fi, cs, sk, uk o ru). Anula el idioma global del snippet solo para este botón — tanto la etiqueta como la interfaz del visualizador usarán este idioma. Los botones con data-lang no se ven afectados por las llamadas a SeeOnWall.setLanguage() ni por los cambios en <html lang>.
data-button-text-{lang}NoOpcional. Etiqueta propia del botón para un idioma: sustituye {lang} por en, pl, de, es, fr, it, pt, nl, sv, nb, da, fi, cs o sk. Se usa cuando ese es el idioma efectivo del botón (definido por data-lang en el elemento o el idioma global del snippet). Sin ella, el botón muestra la etiqueta integrada para ese idioma.
data-button-variantNoLa forma del botón: solid (predeterminada), outline, glyph (icono y texto) o icon (solo icono). Las formas sin relleno ignoran data-bg-color y toman el color de la página.
data-bg-colorNoColor de fondo del botón. Acepta cualquier color CSS o degradado, p. ej. #1a1a2e o linear-gradient(135deg, #c05a33, #9f441f). Sobreescribe la variable CSS --seeonwall-btn-bg solo para este botón. Solo la forma sólida tiene un fondo que pintar; consulta data-button-variant.
data-text-colorNoColor del texto de la etiqueta del botón, p. ej. #ffffff. Sobreescribe --seeonwall-btn-color solo para este botón.
data-border-radiusNoRadio de esquinas del botón, p. ej. 8px o 50%. Sobreescribe --seeonwall-btn-radius solo para este botón.
data-border-colorNoColor del borde del botón, p. ej. #333333. Sobreescribe el color de borde predeterminado solo para este botón.
data-button-widthNoPonlo en «full» para estirar el botón a todo el ancho de su contenedor. Cualquier otro valor, o ninguno, lo deja con su ancho natural.
data-match-buttonNoCopia la apariencia de otro botón de la página. "auto" encuentra tu botón «Añadir al carrito»; cualquier otro valor se trata como un selector CSS.
data-match-colorsNoJunto con data-match-button, copia también los colores de ese botón. Desactivado por defecto.

El botón lee sus atributos data-poster-* al hacer clic, así que puedes actualizarlos en vivo (p. ej. cuando un comprador elige un tamaño) y el siguiente clic abrirá la vista previa con los nuevos valores. La app de Shopify usa esto para seguir automáticamente la variante de tamaño seleccionada.


Paquete npm

Para tiendas que construyen sus propias páginas de producto: Hydrogen, Next.js, Nuxt. Si tu tienda es un tema de Shopify o un sitio WooCommerce, instala la aplicación o el plugin; no necesitas este paquete.

npm install seeonwall

React

import { useSeeOnWall, SeeOnWallButton } from 'seeonwall/react'

function ProductPage({ product }) {
  useSeeOnWall({ shopId: 'YOUR_SHOP_ID' })

  return (
    <SeeOnWallButton
      posterUrl={product.image}
      posterTitle={product.title}
      posterWidth={50}
      posterHeight={70}
      posterSizes={['30x40', '50x70', '70x100']}
    />
  )
}

useSeeOnWall carga el widget y lo detiene cuando se desmonta el último componente que lo usa. Cuenta a quienes lo llaman, así que puedes usarlo en varios componentes sin problema.

SeeOnWallButton renderiza el contenedor y deja que el widget coloque el botón dentro. Así la marca, los dominios permitidos, la coincidencia con el tema y el texto del botón funcionan igual que con la etiqueta script. Sus props reflejan los atributos data anteriores y posterSizes también acepta un array.

Sin React

import { load } from 'seeonwall'

await load({ shopId: 'YOUR_SHOP_ID' })

Carga el widget tú mismo y escribe el marcado del botón exactamente como se muestra arriba.

El renderizado en servidor es seguro. Cada función retorna sin hacer nada cuando no existe document, por lo que importar el paquete en el servidor no lanza errores.

Código fuente, API completa y tipos de TypeScript: github.com/seeonwall/seeonwall-npm


API JavaScript

Después de cargar el snippet, hay un objeto global SeeOnWall disponible en la página.

// The script tag is async, so window.SeeOnWall can be missing when your code runs.
// Run your code through this helper:
function onSeeOnWall(fn) {
  if (window.SeeOnWall) fn()
  // Before the tag is parsed there is no element yet. The page load waits for an async script.
  else (document.querySelector('script[data-shop-id]') ?? window).addEventListener('load', fn)
}

onSeeOnWall(async () => {
  // Open the visualizer for a poster
  SeeOnWall.open({
    posterUrl: 'https://example.com/poster.jpg',
    posterTitle: 'Abstract Mountains',    // optional
    posterWidth: '50cm',                  // optional — number, "24cm"/"10in", or "a4"
    posterHeight: '70cm',                 // optional — same forms; "a4" here is 29.7cm
    posterSizes: '30x40,50x70,70x100',   // optional — enables size selector
    posterInset: '14.07,23.6,70.07,50.2', // optional — artwork rect in a mockup image
    posterMat: '21x30:30x40',             // optional — mat of the product, per size
    posterMatColor: '#FFFFFF',            // optional — colour of that mat
    posterFit: 'auto',                    // optional — 'auto' (default) stretches ≤8% then crops, 'cover' crops, 'stretch' distorts
    productPageUrl: 'https://example.com/products/abstract-mountains', // optional — bookmark target
    sizeUnit: 'cm',                       // optional — fallback unit for values that state none
    frameDefaultCm: 2,                    // optional — preview starts framed (default: unframed)
    frameDefaultColor: '#3E2723',         // optional — colour of that default frame
    frameOptions: ['Oak', 'Black', null], // optional — the only frames a shopper can pick; null is no frame
    frameSizeIncluded: false              // optional — true when the poster size includes the frame
  })

  // Close the visualizer modal (desktop only)
  SeeOnWall.close()

  // Change the snippet language at runtime (SPA use case)
  SeeOnWall.setLanguage('pl')

  // Current snippet version
  console.log(SeeOnWall.version)

  // Storefront catalogue-preview readiness (a cached hint; refresh before acting)
  await SeeOnWall.ready()   // start-up is deferred to DOMContentLoaded
  console.log(SeeOnWall.isSessionReady())
  await SeeOnWall.refreshSessionState()
  const unsubscribe = SeeOnWall.on('session-change', () => {
    // Update catalogue-preview controls in this tab. Also runs when the shopper
    // returns after setting up their wall on a phone.
  })
  // Call unsubscribe() when your page/component is disposed
})
SeeOnWall.open(params)

Abre el visualizador para el póster dado. En el escritorio aparece en una superposición modal. En móvil se abre en una nueva pestaña.

SeeOnWall.close()

Cierra el modal del visualizador, incluida una vista previa rápida en la pared en un móvil. No tiene efecto sobre un visualizador completo que se abrió en una pestaña nueva en el móvil.

SeeOnWall.openCataloguePreview(params)

Abre la vista previa rápida en la pared para un producto, sobre la pared que el comprador ya configuró. Acepta los mismos parámetros de póster que SeeOnWall.open() y devuelve { opened: true }, o { opened: false, reason } si no se abrió nada. Requiere un plan de pago. → Vista previa rápida

SeeOnWall.setLanguage(lang)

Cambia el idioma activo del snippet en tiempo de ejecución. Actualiza inmediatamente todas las etiquetas de botones ya inyectadas y se aplica a cada modal abierto posteriormente. Útil en SPAs cuando quieres controlar explícitamente el idioma desde tu propia lógica en lugar de depender del observador automático de <html lang>.

SeeOnWall.version

Cadena de solo lectura con la versión del snippet cargado.

SeeOnWall.ready()

Se resuelve cuando el snippet se ha inicializado y el resto de esta API se puede llamar con seguridad: el escaneo de botones espera a DOMContentLoaded, así que el objeto global puede existir antes de estar listo. Espéralo antes de leer el estado de la sesión. La etiqueta script es async, así que llama a la API desde su evento load o desde código que se ejecute después: window.SeeOnWall no existe hasta que el script se evalúa.

SeeOnWall.isSessionReady()

Devuelve la pista de preparación almacenada para la sesión actual de la tienda. Úsala solo para decidir si mostrar controles opcionales de vista previa rápida en la pared; nunca es autorización. También es false mientras el snippet aún se está inicializando: espera a SeeOnWall.ready() antes de leer un false como «sin pared».

SeeOnWall.refreshSessionState()

Comprueba la sesión actual con seeonwall.com y devuelve none, creating, ready o expired. Una sesión ausente o caducada se elimina del almacenamiento de la tienda.

SeeOnWall.on('session-change', listener)

Ejecuta el listener cuando el estado de la sesión cambia en esta pestaña, en otra pestaña del mismo origen de tienda, o cuando el comprador vuelve a la página tras configurar su pared en el móvil: el snippet vuelve a comprobar una sesión pendiente al regresar. Devuelve una función para cancelar la suscripción.

SeeOnWall.on('purchase-request', listener)

Ejecuta el listener cuando un comprador pulsa Añadir al carrito en una vista previa de escritorio. El evento es cancelable: llama a preventDefault() para añadir la oferta con tu propia API de carrito y navegar tú mismo a tu carrito; si no, el snippet navega a la purchaseUrl de la oferta. event.detail lleva selectionKey, el tamaño y el marco, y navigateFallback(). Devuelve una función para cancelar la suscripción.

SeeOnWall.setConsent(granted)

Indica al snippet si el cliente aceptó la analítica en tu banner de consentimiento. Llámalo en cada carga de página. El valor solo se guarda en memoria. Sin setConsent(true), track() no envía nada. → Análisis de pedidos

SeeOnWall.track(event, data)

Informa de un añadido al carrito ('add_to_cart', { posterUrl }) o de un pedido ('purchase', { orderId, items: [{ posterUrl, quantity }] }) para el análisis de pedidos. No hace nada hasta que actives el análisis de pedidos y el cliente dé su consentimiento. Espera como máximo 3 segundos los ajustes de la tienda y no espera la respuesta, así que puedes esperarlo antes de enviar un formulario. Nunca se rechaza. → Análisis de pedidos


Vista previa rápida en la pared

Cuando un comprador ha configurado su pared, puede ver cualquier otro póster en ella con un solo toque — desde un listado de productos, una cuadrícula de categoría o una fila de recomendaciones, sin volver a pasar por el visualizador. Incluida en Basic, Premium y Ultra.

Las dos integraciones de plataforma lo ofrecen sin código. En la aplicación de Shopify, activa las ubicaciones que quieras en «Vista previa rápida en la pared» y la extensión del tema pone el control en esos listados. En el plugin de WooCommerce, haz lo mismo en Botón → Listados de productos → Vista rápida en la pared; el plugin marca por sí mismo cada ficha de producto apta, así que no hace falta ningún selector del tema. En cualquier otro sitio es para tiendas que cargan la etiqueta de script por su cuenta y llaman a la función desde sus propias plantillas de listados.

Cómo funciona

  1. 1El comprador abre el visualizador una vez, desde cualquier producto, y configura su pared. Esa pared pertenece a la sesión y dura siete días.
  2. 2En tus páginas de listado preguntas al snippet si hay una pared lista y, cuando la hay, muestras un pequeño control de vista previa en cada tarjeta de producto.
  3. 3El comprador toca el control y el póster aparece sobre su propia pared allí mismo — un producto, sin cámara, sin configuración.
  4. 4La salida de la vista previa es «Ajustar vista previa», que abre el visualizador completo para ese póster.
// Show your preview controls only while the shopper has a wall
// onSeeOnWall() waits for the async script tag. See JavaScript API.
onSeeOnWall(async () => {
  await SeeOnWall.ready()

  function refreshControls() {
    const ready = SeeOnWall.isSessionReady()
    document.querySelectorAll('.my-preview-icon')
      .forEach(el => { el.hidden = !ready })
  }

  refreshControls()
  SeeOnWall.on('session-change', refreshControls)

  // Launch one product — the same poster parameters as SeeOnWall.open()
  icon.addEventListener('click', async () => {
    const result = await SeeOnWall.openCataloguePreview({
      posterUrl: 'https://example.com/poster.jpg',
      posterTitle: 'Abstract Mountains',                                 // optional
      posterWidth: '50cm',
      posterHeight: '70cm',
      posterSizes: '30x40,50x70,70x100',                                 // optional
      posterInset: '14.07,23.6,70.07,50.2',                              // optional
      posterMat: '21x30:30x40',                                          // optional
      posterMatColor: '#FFFFFF',                                         // optional
      posterFit: 'auto',                                                 // optional
      productPageUrl: 'https://example.com/products/abstract-mountains'  // optional
    })

    if (!result.opened) {
      // Nothing opened. result.reason says why — see the list below.
      console.log(result.reason)
    }
  })
})

Cuándo puede abrirse

  • El comprador tiene una pared configurada para tu tienda y esa sesión no ha caducado.
  • Tu plan es Basic, Premium o Ultra.
  • La llamada incluye la URL de la imagen del póster y un ancho y un alto legibles — los mismos valores que usan tus botones.
  • La página que la llama está en tu lista de dominios permitidos.
  • El comprador no ha solicitado demasiadas vistas previas rápidas en la pared desde la misma red en la última hora.

Qué devuelve

openCataloguePreview() devuelve { opened: true } cuando se abrió una vista previa, o { opened: false, reason } cuando no se abrió nada. El motivo le dice a tu página qué hacer en su lugar:

  • no-ready-session — El comprador aún no tiene una pared para tu tienda. Muestra tu botón habitual «Ver en la pared», que crea una.
  • session-expired — La pared superó sus siete días y se ha eliminado. La siguiente vista previa completa crea una nueva.
  • not-entitled — El plan de esta tienda no incluye la vista previa rápida en la pared, o la página o la imagen del póster no está en tu lista de dominios permitidos.
  • rate-limited — Se han solicitado demasiadas vistas previas rápidas en la pared desde la red de este comprador en la última hora. Inténtalo de nuevo más tarde.
  • invalid-poster-data — La llamada no tenía URL de imagen del póster, ni un ancho y un alto que se pudieran leer.
  • poster-unavailable — No se pudo preparar la vista previa para este producto.
  • network-error — La petición no llegó a seeonwall.com, o el snippet aún no se había inicializado — espera primero a SeeOnWall.ready().

Qué hace la vista previa

Un producto, solo lectura

La vista previa muestra el póster que le pasaste y nada más: sin historial de pósters, sin búsqueda, sin forma de cambiar a otro producto. Su acción principal, «Ajustar vista previa», abre el visualizador completo para el mismo póster.

Se abre en el sitio

Una ventana sobre tu página en el escritorio y un panel casi a pantalla completa en el móvil. Nunca abre una pestaña nueva, porque la pared ya está configurada y no hay paso de cámara que traspasar.

Tamaños y mockups se mantienen

La lista de tamaños y el área de la obra dentro de una imagen mockup se leen igual que en tus botones, así que el comprador también puede comparar tamaños dentro de la vista previa.

Cuenta como una vista de póster

Cada vista previa rápida es una vista de póster de tu límite por hora y por mes. Un comprador viendo un póster cuenta una vez al día, por muchas veces que lo abra ese día.

Se cuenta aparte en tu panel

Las estadísticas de la tienda muestran las vistas previas rápidas junto a tus vistas de pósters, con un gráfico de 30 días, y la tabla de pósters más vistos indica cuántas vistas previas de cada póster vinieron de un listado.


Análisis de pedidos

Mira cuántas veces los clientes añaden un póster al carrito y lo piden, agrupado según hasta dónde llegaron en la vista previa: el póster estuvo en su pared, prepararon una pared y vieron otros pósters, empezaron una vista previa o no usaron la vista previa. El último grupo es la comparación.

Para tiendas que cargan la etiqueta del script por su cuenta, y en el plugin de WooCommerce: actívalo en la pestaña Analítica del plugin. El plugin informa desde tu servidor y también cuenta los reembolsos; tu banner de consentimiento debe ser compatible con la WP Consent API. En la app de Shopify: actívalo en la pestaña Analítica y permite que la app lea tus pedidos cuando Shopify lo pida. La app lee tus pedidos una vez al día y también cuenta los reembolsos; el navegador del cliente informa de cada añadido al carrito desde los dominios de tu tienda, que la app lee de Shopify. El consentimiento viene de la configuración de privacidad de clientes de Shopify.

Cómo configurarlo

  1. 1En el panel, abre Ajustes de la tienda, añade el dominio de tu tienda en Dominios permitidos y activa el Análisis de pedidos. Los eventos de una página que no está en la lista no se cuentan.
  2. 2En cada página, llama a SeeOnWall.setConsent(true) cuando el cliente haya aceptado la analítica en tu banner de consentimiento. Antes de esa llamada, el snippet no envía ni guarda nada para el análisis de pedidos.
  3. 3En la página del producto, llama a SeeOnWall.track('add_to_cart', { posterUrl }) cuando el póster entra en el carrito. Solo cuenta si la página muestra el botón de ese póster.
  4. 4En la página de confirmación del pedido, llama a SeeOnWall.track('purchase', { orderId, items }) con los pósters del pedido que muestran el botón. Un segundo informe del mismo número de pedido no se cuenta.
// On every page, after your consent banner knows the choice of the shopper
onSeeOnWall(() => {
  SeeOnWall.setConsent(shopperAcceptedAnalytics)
})

// On the product page, when the poster goes into the cart
onSeeOnWall(() => {
  SeeOnWall.track('add_to_cart', { posterUrl: 'https://example.com/poster.jpg' })
})

// On the order confirmation page. Pass only the posters that show the button.
onSeeOnWall(() => {
  SeeOnWall.track('purchase', {
    orderId: '1042',
    items: [{ posterUrl: 'https://example.com/poster.jpg', quantity: 2 }],
  })
})

Qué se guarda

  • Recuentos diarios por póster y por grupo: líneas añadidas al carrito, líneas pedidas y la cantidad pedida. Ningún pedido, cliente, dirección ni precio. Una tienda WooCommerce y una tienda Shopify también informan de los reembolsos, y la cantidad reembolsada se cuenta igual.
  • Un código unidireccional de cada número de pedido, durante 30 días, para contar cada pedido una sola vez. El número de pedido en sí no se guarda. Lo mismo se guarda para cada número de reembolso que informa una tienda WooCommerce o la app de Shopify.
  • En la entrada de localStorage de la tienda, los pósters que estuvieron en la pared del cliente en esta sesión. Solo después de setConsent(true) y solo mientras el análisis de pedidos está activado. Se eliminan cuando el cliente retira su consentimiento (setConsent(false)) o cuando desactivas el análisis de pedidos. En una tienda WooCommerce, con consentimiento, la tienda también guarda el paso de la vista previa de cada póster del carrito en la cookie de sesión seeonwall_labels, y la elimina cuando se retira el consentimiento. En una tienda Shopify, con consentimiento, el paso de la vista previa va en la línea del carrito como la propiedad oculta _sow_state, y la app lo lee del pedido.
  • Si desactivas el análisis de pedidos, el recuento se detiene y los códigos de pedido se eliminan. Los recuentos hasta ahora se mantienen en tu panel. En una tienda WooCommerce o en la app de Shopify, los códigos de pedido se mantienen hasta que terminan sus 30 días, para que un reembolso después de volver a activarlo siga correspondiendo a su pedido.

Endpoint del catálogo

Con las paredes de galería activadas, los clientes pueden añadir a su pared más pósteres de tu tienda, desde la pestaña Más obras de la vista previa. En una tienda que carga la etiqueta de script, seeonwall.com lee estos pósteres de un endpoint de tu servidor.

Esta sección es para tiendas que cargan la etiqueta de script. La app de Shopify y el plugin de WooCommerce leen tu catálogo de tu tienda, sin un endpoint propio. Una tienda WooCommerce debe usar https.

Cómo configurarlo

  1. 1Crea en tu servidor un endpoint GET que devuelva tus pósteres con el formato de abajo. Su URL debe usar https y su host debe estar en tus dominios permitidos.
  2. 2En el panel, abre Ajustes de la tienda. En Paredes de galería, introduce la URL del endpoint, elige Solicitud firmada o Clave de API y haz clic en Guardar.
  3. 3Haz clic en Generar secreto y guarda el secreto en tu servidor. El panel lo muestra solo una vez.
  4. 4Haz clic en Probar endpoint. La prueba llama a tu endpoint una vez y muestra el tiempo de respuesta y la causa de cada póster que no puede usar.
  5. 5Activa Permitir a los clientes colgar varias obras en una pared. Hasta entonces, los clientes no ven tu catálogo.

La solicitud

seeonwall.com envía una solicitud GET con la cabecera X-SeeOnWall-Catalogue-Version: 1. Los parámetros van después de la query de tu URL, en el orden de la tabla, con codificación porcentual RFC 3986 (un espacio es %20). Ignora los parámetros que no conozcas: una versión posterior puede añadir uno.

GET /seeonwall-catalogue?q=aurora&locale=de&cursor=page-2&limit=24 HTTP/1.1
Host: shop.example
X-SeeOnWall-Catalogue-Version: 1
X-SeeOnWall-Signature: t=1700000000,v1=…
AtributoObligatorioDescripción
qNoEl texto de búsqueda del cliente, sin espacios en los extremos y en minúsculas. No se envía si el cliente no busca.
localeNoEl idioma del cliente, por ejemplo de. No se envía si no se conoce.
collectionNoEl ID de una colección. No se envía si no hay ninguna.
cursorNoEl nextCursor de tu respuesta anterior. No se envía para la primera página.
limitSíEl número máximo de pósteres que devolver. Es 24.

La respuesta

Responde con el estado 200 y el tipo de contenido application/json. No redirijas. La respuesta debe llegar en 3 segundos como máximo y ocupar 1 MiB como máximo.

{
  "items": [
    {
      "productPageUrl": "https://shop.example/products/aurora",
      "posterTitle": "Aurora",
      "posterUrl": "https://cdn.shop.example/aurora-2000.jpg",
      "thumbnailUrl": "https://cdn.shop.example/aurora-400.jpg",
      "sizeUnit": "cm",
      "posterSizes": "30x40,50x70",
      "posterWidth": 50,
      "posterHeight": 70,
      "frameOptions": ["black", "oak", null],
      "galleryWall": true,
      "productId": "1042"
    }
  ],
  "nextCursor": "page-3"
}
AtributoObligatorioDescripción
productPageUrlSíComo data-product-page-url en el botón.
posterTitleSíComo data-poster-title en el botón.
posterUrlSíComo data-poster-url en el botón.
posterSizesNoComo data-poster-sizes en el botón. Indica posterSizes, o posterWidth y posterHeight.
posterWidthNoComo data-poster-width en el botón. Indica posterSizes, o posterWidth y posterHeight.
posterHeightNoComo data-poster-height en el botón. Indica posterSizes, o posterWidth y posterHeight.
sizeUnitNoComo data-size-unit en el botón.
thumbnailUrlNoUna imagen más pequeña para la miniatura de la vista previa. Si no es válida, la miniatura usa posterUrl.
frameOptionsNoLos nombres de plantillas de marco de data-frame-options: de 1 a 21 nombres, y null para sin marco. Si una entrada no es válida, la lista no se usa.
posterInsetNoComo data-poster-inset en el botón.
posterMatNoComo data-poster-mat en el botón.
posterMatColorNoComo data-poster-mat-color en el botón.
galleryWallNofalse deja el póster fuera de la lista, como data-gallery-wall="off" en el botón. Por defecto es true.
productIdNoTu ID del producto. Opcional.
  • El host de productPageUrl, posterUrl y thumbnailUrl debe estar en tus dominios permitidos.
  • Un póster que no supera una comprobación no se muestra. Los demás pósteres se siguen mostrando. Probar endpoint lista cada póster descartado con la causa.
  • Un póster con la misma productPageUrl que un póster anterior de la misma página no se vuelve a mostrar.
  • nextCursor es un texto de 1 a 512 caracteres, o null en la última página. seeonwall.com lo devuelve tal cual.
  • Devuelve como máximo 24 pósteres. Los pósteres después del 24.º se pierden.
  • seeonwall.com guarda cada página 5 minutos, así que un cambio en tu catálogo puede tardar 5 minutos en verse.

Autenticación

Solicitud firmada: cada solicitud tiene la cabecera X-SeeOnWall-Signature: t=<unix seconds>,v1=<hex>. hex es HMAC-SHA256 en hexadecimal en minúsculas, con tu secreto como clave, sobre este texto (un salto de línea entre las líneas):

v1
{t}
GET
{host}
{request-target}

host es el host de la URL de tu endpoint en minúsculas, con el puerto si no es 443. request-target es la ruta y la query tal como llegan en la línea de la solicitud: no las decodifiques. Rechaza una solicitud cuyo t se aleje más de 300 segundos de tu reloj. El secreto es la clave como texto: no lo decodifiques.

Clave de API: cada solicitud tiene la cabecera Authorization: Bearer <secret>. Compárala con tu secreto en tiempo constante.

Generar secreto crea un secreto nuevo, y seeonwall.com lo usa al momento. Acepta también el secreto anterior mientras lo cambias en tu servidor: el panel muestra cuándo terminan esas 24 horas. Un segundo secreto nuevo dentro de esas 24 horas anula el más antiguo al momento.

Comprobar la firma

La misma comprobación en Node, PHP y Python. Cada una devuelve true solo para una solicitud que seeonwall.com firmó en los últimos 5 minutos. Responde 401 cuando devuelva false.

import crypto from 'node:crypto'

// host: the host of your endpoint URL, in lower case, with the port when it is not 443.
// requestTarget: the path and the query as they arrive, not decoded (req.url in Node).
// secrets: the current secret, and during a change also the previous one.
export function isSignedBySeeOnWall(signatureHeader, host, requestTarget, secrets) {
  const t = /(?:^|,)t=(\d+)/.exec(signatureHeader ?? '')?.[1]
  const v1 = /(?:^|,)v1=([0-9a-f]{64})/.exec(signatureHeader ?? '')?.[1]
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const text = `v1\n${t}\nGET\n${host}\n${requestTarget}`
  return secrets.some(secret =>
    crypto.timingSafeEqual(crypto.createHmac('sha256', secret).update(text).digest(), Buffer.from(v1, 'hex')))
}
<?php
// $host: the host of your endpoint URL. $requestTarget: $_SERVER['REQUEST_URI'], not decoded.
function is_signed_by_seeonwall(string $signatureHeader, string $host, string $requestTarget, array $secrets): bool
{
    if (!preg_match('/(?:^|,)t=(\d+)/', $signatureHeader, $t)
        || !preg_match('/(?:^|,)v1=([0-9a-f]{64})/', $signatureHeader, $v1)
        || abs(time() - (int) $t[1]) > 300) {
        return false;
    }
    $text = "v1\n{$t[1]}\nGET\n{$host}\n{$requestTarget}";
    foreach ($secrets as $secret) {
        if (hash_equals(hash_hmac('sha256', $text, $secret), $v1[1])) {
            return true;
        }
    }
    return false;
}
import hashlib
import hmac
import re
import time


def is_signed_by_seeonwall(signature_header, host, request_target, secrets):
    """host: the host of your endpoint URL. request_target: the path and the query as they arrive, not decoded."""
    t = re.search(r'(?:^|,)t=(\d+)', signature_header or '')
    v1 = re.search(r'(?:^|,)v1=([0-9a-f]{64})', signature_header or '')
    if not t or not v1 or abs(time.time() - int(t.group(1))) > 300:
        return False
    text = f'v1\n{t.group(1)}\nGET\n{host}\n{request_target}'.encode()
    return any(
        hmac.compare_digest(hmac.new(secret.encode(), text, hashlib.sha256).hexdigest(), v1.group(1))
        for secret in secrets
    )

Vector de prueba

Usa estos valores para probar tu código. La comprobación de tiempo rechaza este t, así que prueba solo el HMAC.

secret          s3cret
t               1700000000
host            shop.example
request target  /c?q=a&limit=24
v1              f457e6f747e4543623541e94f26eea0a14414c68fe3054b4dd9bf194acdbfae1

Idioma y localización

El snippet adapta las etiquetas de sus botones y la interfaz del visualizador al idioma del visitante. Tres mecanismos complementarios se encargan de esto, en orden de prioridad.

Automático: observador de <html lang>

Cuando data-lang no está establecido en la etiqueta <script>, el snippet lee document.documentElement.lang al inicio y lo observa mediante un MutationObserver. La mayoría de las bibliotecas i18n (incluida react-i18next) actualizan <html lang> automáticamente — si la tuya lo hace, no se necesita configuración adicional.

// Keep <html lang> in sync with your i18n library (e.g. react-i18next)
import i18n from './i18n'

i18n.on('languageChanged', (lang) => {
  document.documentElement.lang = lang
})

// The snippet detects the change automatically — no SeeOnWall calls needed.

Una vez que se llama a SeeOnWall.setLanguage(), el observador de <html lang> se desactiva para el resto de la carga de la página. La llamada explícita se convierte en autoritativa.

Explícito: SeeOnWall.setLanguage(lang)

Llama a setLanguage(lang) para cambiar el idioma de forma imperativa en cualquier momento después de que el snippet se cargue. Todas las etiquetas de botones ya inyectadas se actualizan inmediatamente, y cada modal abierto posteriormente usa el nuevo idioma.

// onSeeOnWall() waits for the async script tag. See JavaScript API.
onSeeOnWall(() => {
  // Drive language from your own logic
  SeeOnWall.setLanguage('pl')

  // All injected button labels update immediately.
  // The <html lang> observer is disabled for the rest of this page load.
  // Call setLanguage() again at any time to switch back.
})

Estático: data-lang en la etiqueta de script

Establece data-lang (cualquier valor indicado para data-lang en Instalación, por ejemplo data-lang="de") en la etiqueta <script> para fijar el idioma de toda la página. El observador de <html lang> nunca se activa. Aún puedes llamar a setLanguage() en tiempo de ejecución para anularlo.

Idioma por botón: data-lang en el elemento

Añade data-lang a un elemento .seeonwall-button individual para fijar ese botón específico a un idioma, independientemente de la configuración global del snippet. La etiqueta del botón y el visualizador abierto desde ese botón usarán ambos el idioma especificado. Estos botones no se ven afectados por las llamadas a SeeOnWall.setLanguage() ni por las mutaciones de <html lang> — útil para sitios estáticos que sirven contenido en varios idiomas desde una sola página.

<div class="seeonwall-button"
     data-lang="pl"
     data-poster-url="https://example.com/poster.jpg"
     data-poster-width="50"
     data-poster-height="70"></div>

Orden de prioridad

setLanguage() anula el idioma actual en cualquier momento. El observador de <html lang> solo está activo cuando ni se estableció data-lang ni se ha llamado a setLanguage() aún.

Anulaciones de texto por botón

Los botones individuales también pueden reemplazar el texto de la etiqueta usando data-button-text-en, data-button-text-pl, data-button-text-de, data-button-text-es, data-button-text-fr, data-button-text-it, data-button-text-pt, data-button-text-nl, data-button-text-sv, data-button-text-nb, data-button-text-da, data-button-text-fi, data-button-text-cs o data-button-text-sk. Se usa el atributo que corresponde al idioma efectivo de ese botón (definido por data-lang en el elemento o el idioma global del snippet). → Marcado del botón



Flujo de visitantes

Cómo un visitante de la tienda experimenta seeonwall.com, desde hacer clic en el botón de vista previa hasta ver su póster en su pared real. → Detección automática de la pared

Escritorio (predeterminado)

  1. 1El visitante hace clic en "Ver en la pared" en una página de producto.
  2. 2Se abre un modal en el escritorio con un código QR.
  3. 3El visitante configura el fondo de pared: escanea el código QR con su teléfono para capturar la sala en vivo, sube una foto desde su PC, o elige una plantilla de sala.
  4. 4Para fotos capturadas y subidas: la pared se detecta automáticamente y sus dimensiones reales se estiman, por lo que la vista previa suele aparecer sin más intervención. Si la foto no es clara, el visitante ajusta las esquinas y dimensiones ya rellenadas en lugar de empezar de cero.
  5. 5La vista previa aparece enseguida: el póster se coloca centrado en la pared de forma automática, a su tamaño impreso real.
  6. 6El modal del escritorio muestra esa misma vista previa, y el póster sigue siendo movible: el visitante lo desplaza, lo redimensiona o lo reencuadra sobre la vista previa final.

Mismo dispositivo (el visitante ya está en móvil)

  1. 1El visitante toca "Ver en la pared" en su teléfono.
  2. 2El visualizador se abre en una nueva pestaña del navegador — sin paso de código QR.
  3. 3La foto se analiza al llegar: normalmente la vista previa aparece de inmediato; si no, el visitante confirma primero la calibración prerrellenada.
  4. 4La vista previa final se muestra en la misma pestaña.

Si el visitante cierra y vuelve a abrir el modal dentro del período de validez de 7 días de la sesión, la sesión anterior se reanuda automáticamente — no tiene que repetir los pasos de foto y calibración.


Detección automática de la pared

Cada foto de pared se analiza en cuanto llega, antes de pedirle nada al visitante. Cuando el análisis tiene confianza suficiente —lo habitual— el póster aparece en la pared de inmediato. Marcar las esquinas a mano es el camino alternativo, no el predeterminado.

Qué ocurre con una foto de pared

  1. 1Comprobación de calidad y contenido. Cada foto se revisa nada más llegar. Una foto que no supera la comprobación de contenido se rechaza: no se vincula a ninguna sesión, no se muestra nunca y el archivo subido se elimina de inmediato.
  2. 2Detección de la pared. Se localiza la pared en la imagen y sus cuatro esquinas se devuelven como porcentajes de la foto, de modo que sobreviven a cualquier redimensionamiento.
  3. 3Estimación de dimensiones. El ancho y el alto reales de la pared se estiman a partir de la escena, así que normalmente el visitante no tiene que medir su pared. Cuando no es posible estimarlas, el visitante introduce las dimensiones de la pared en el paso manual.
  4. 4Configuración en un solo paso. Cuando la confianza en las esquinas es suficientemente alta, la calibración y una colocación centrada del póster se guardan juntas en un único paso, y la sesión pasa directamente de la foto a la vista previa terminada.
  5. 5El visitante mantiene el control. La vista previa se identifica como una estimación automática y ofrece un ajuste fino. Las esquinas, las dimensiones de la pared y la posición del póster siguen siendo editables.

Cuando la foto es difícil

Pared parcialmente oculta

Un sofá, una estantería o un encuadre demasiado ajustado pueden ocultar el borde real de la pared. En lugar de rendirse, la detección devuelve el mayor rectángulo utilizable —por ejemplo, el espacio libre encima de un sofá— y el póster se coloca dentro de él.

Confianza baja

Por debajo del umbral de confianza el visitante pasa por el paso de calibración manual, pero los controles de esquina parten de las posiciones detectadas y las dimensiones estimadas vienen rellenadas. Es un ajuste, no una hoja en blanco.

Ningún resultado

Si el análisis agota el tiempo o falla, el flujo continúa con los controles de esquina predeterminados y dimensiones manuales. La detección es de mejor esfuerzo y nunca impide crear una vista previa.

Indicaciones que ve el visitante

  • Poca luz: sugiere encender más luz o abrir las cortinas.
  • Pared a contraluz o con reflejos, como una ventana detrás de la pared: sugiere tomar la foto desde otro ángulo.
  • No se encontró ninguna pared: pide repetir la foto con la pared bien visible, permitiendo aun así la colocación manual.
  • Póster mayor que la pared detectada: se indica al visitante que el póster no cabe y se le ofrecen los tamaños que sí caben, en lugar de mostrar una vista previa que no podría ser real.

Qué hace buena a una foto de pared

  • Encuadra la pared entera, incluido su encuentro con el suelo y el techo.
  • Fotografía de frente, no en ángulo pronunciado.
  • Evita una ventana luminosa justo detrás de la pared.
  • Enciende las luces: las fotos oscuras dan una estimación más débil.

La detección automática se ejecuta en todas las fotos de pared y en todos los planes, incluido el gratuito. No hay nada que activar ni configurar. Las plantillas de sala se saltan el paso por completo, porque su geometría ya se conoce.

El análisis lo realiza un modelo de IA en Amazon Bedrock en Fráncfort (eu-central-1), al que se accede a través de la pasarela europea de Requesty en Fráncfort. Las fotos de pared nunca se usan para entrenar modelos, la pasarela no las registra y el análisis se elimina junto con la sesión. → Subencargados


Límites de velocidad

Los límites se aplican por cuenta. Todos los límites de abajo son por hora y se restablecen al inicio de cada hora UTC, salvo el techo mensual de vistas de pósters, que se reinicia al inicio de cada mes UTC. Mejora tu plan en el panel de administración para desbloquear límites más altos. Los análisis de configuración automática también se cuentan por mes UTC.

PlanSesiones / hrFotos / hrVistas de pósters / hrVistas de pósters / mesDescargas / hrParedes / sesiónConfiguración automática / mes
FREE1504010050050230
BASIC5002001,0005,0002505200
PREMIUM2,5001,00010,00025,0001,00010500
ULTRA10,0002,00050,000Ilimitado2,000102,500
S
Se crea una sesión cuando un visitante abre el visualizador desde tu tienda y aún no tiene una sesión en ese dispositivo; al volver a abrir el visualizador se reanuda la sesión existente.
P
Se cuenta una foto cada vez que un visitante sube una imagen de pared desde su teléfono.
W
El número de paredes que un comprador puede tener a la vez en una sesión: fotos de sus propias habitaciones, habitaciones de ejemplo o una mezcla. Cambia entre ellas en la vista previa; si se alcanza el límite, primero hay que quitar una. Es un total, no un presupuesto por hora: no se consume ni se reinicia.
V
Se cuenta una vista de póster la primera vez en un día que una sesión muestra un póster concreto en una pared calibrada, por muchas veces que se renderice. Una vista previa rápida en la pared también cuenta como una vista de póster.
M
Las vistas de pósters son la única métrica con dos límites, y ambos se contabilizan: una vista consume el presupuesto por hora y el mensual, y agotar cualquiera de los dos detiene el registro de nuevas vistas. La ventana por hora se reinicia al inicio de cada hora UTC; la mensual, al inicio de cada mes UTC.
D
Se cuenta una descarga cada vez que un visitante guarda o comparte la imagen final de la vista previa del póster.
A
Se cuenta un análisis de configuración automática por cada producto que analiza la app de Shopify o WooCommerce, también cuando no encuentra ninguna imagen útil. Un producto no cuenta cuando su análisis falla o se detiene antes de que responda el modelo de IA (por ejemplo, porque no se puede cargar una imagen). Sí cuenta cuando eso ocurre después de que el modelo haya respondido, y analizar de nuevo el mismo producto vuelve a contar. El recuento es por cuenta y se reinicia al inicio de cada mes UTC. Durante la prueba gratuita de 14 días de un plan de pago se pueden analizar como máximo 100 productos, sea cual sea el plan. Un producto que muestra el mismo mockup que un producto analizado de la misma ejecución se configura a partir de ese resultado y no se cuenta. Cuando no quedan análisis, los demás productos de la ejecución no se analizan y una ejecución posterior los vuelve a seleccionar.

Se aplica un límite a nivel de IP además de los límites del plan: como máximo 600 solicitudes de creación de sesión y 300 solicitudes de carga de fotos por dirección IP, contadas en una ventana móvil de una hora que empieza con la primera solicitud de esa IP. Esto protege contra el abuso desde una sola IP y no afecta los patrones de uso normal.


Cuando se alcanzan los límites de velocidad

Lo que le ocurre al visitante cuando tu tienda alcanza un límite.

Límite de creación de sesiones alcanzado

El botón "Ver en la pared" sigue apareciendo en las páginas de tu producto. Cuando un visitante hace clic en él, el modal del visualizador se abre pero muestra un mensaje de error amigable en lugar de un código QR. El mensaje les pide que lo intenten de nuevo en breve. Sin fallos, sin pantalla en blanco.

Límite de carga de fotos alcanzado

Un visitante que ya escaneó el código QR y está en la pantalla de carga móvil verá un error si el límite se supera entre el momento en que abrió el modal y el momento en que intenta subir la foto. Se le pide que lo intente de nuevo.

Límite de vistas de pósters alcanzado

Se cuenta una vista de póster cuando se muestra una vista previa sobre una pared calibrada — en el escritorio, en el móvil o en ambos. Cuenta una vez por póster, sesión y día por muchas veces que se renderice, así que un comprador que mira un póster cuesta una vista. Este es el límite con el que se topa el comprador en el último paso: en lugar del póster en su pared ve un mensaje pidiéndole que lo intente de nuevo en unos minutos. Las vistas de pósters son la única métrica con dos límites, por hora y por mes, y una vista consume los dos.

Límite mensual de vistas de pósters alcanzado

Independiente del límite por hora y aplicado junto a él. Mientras el límite por hora se despeja solo dentro de la hora, este permanece agotado hasta que cambia el mes, así que es el límite que indica que tu plan se te ha quedado corto. Hasta que se reinicie o mejores de plan, el botón «Ver en la pared» se oculta en tus páginas de producto, para que los compradores no empiecen una vista previa que no puede terminar. Un comprador que abrió la página antes de que se agotara el límite sigue viendo el botón y, en el último paso, se le pide que lo intente más tarde. El botón vuelve en menos de un minuto tras el reinicio o la mejora de plan.

Límite de descargas alcanzado

Si se alcanza el límite de descargas, la acción de guardar/compartir falla y se muestra un error al visitante. La vista previa en sí sigue siendo visible — solo la acción de descarga está bloqueada.

Los límites por hora se restablecen al inicio de cada hora UTC, así que los picos de tráfico de menos de una hora suelen resolverse solos. El techo mensual de vistas de pósters se reinicia al comenzar cada mes UTC — alcanzarlo es una señal para mejorar de plan, no algo que se arregle por sí mismo.


Ciclo de vida de la sesión

Cada sesión del visualizador tiene uno de estos estados. El escritorio recibe actualizaciones en directo mediante un flujo de server-sent events. Una foto subida es un borrador hasta que se guarda su pared, así que una subida no cambia el estado. Las sesiones caducan a los 7 días y luego se eliminan automáticamente.

CREATED
Creada

Se activa cuando un visitante de la tienda abre el visualizador. Se genera un ID de sesión único y se muestra un código QR en el escritorio para que el visitante pueda continuar en su teléfono. La sesión sigue en este estado mientras el visitante sube una foto y revisa la pared.

→
READY
Lista

Se alcanza cuando la sesión tiene su primera pared. La calibración de la pared — las coordenadas de las cuatro esquinas y las dimensiones reales de la pared — y una colocación centrada del póster se guardan juntas en un solo paso. Cuando la detección de esquinas es fiable, el visitante no confirma nada; las escenas de habitación siguen el mismo camino. El escritorio renderiza entonces la vista previa. Más paredes, fotos nuevas y cambios del póster no cambian el estado. Cuando el visitante elimina la última pared, la sesión vuelve a Creada.

Expiración y limpieza

Todas las sesiones se conservan durante 7 días desde su creación, luego se eliminan permanentemente independientemente de su estado. Las fotos de pared se eliminan por la caducidad de 7 días del propio almacenamiento. Solo los datos del póster detrás de un enlace compartido se conservan más tiempo, para que un enlace compartido caducado pueda seguir mostrando una página de destino.

Objetos de datos

SesiónUUID único, estado actual, referencia a la tienda, marca de tiempo de creación, expiración de 7 días
Fotoimagen de la pared capturada o subida por el visitante; almacenada en la nube, vinculada a la sesión y acompañada del análisis derivado de ella (esquinas detectadas, dimensiones estimadas, indicadores de calidad)
Calibracióncuatro coordenadas de esquinas de la pared (cada una entre 0 y 100% de la foto) y dimensiones reales de la pared (cm)
Colocaciónposición del póster, escala y ángulo de rotación en la superficie de la pared calibrada

Requisitos de imagen del póster

Requisitos para la URL de imagen del póster que proporcionas. El navegador carga la imagen directamente en la vista previa, y el servidor la obtiene por separado al generar una vista previa descargable o compartible.

  • La URL debe ser absoluta (comenzando con https://).
  • La imagen debe ser públicamente accesible — sin autenticación, sin pantallas de inicio de sesión, sin protección de hotlink que bloquee orígenes externos.
  • Usa JPEG, PNG o WebP. AVIF se muestra en la vista previa del navegador pero no es compatible con la descarga y compartición de vistas previas.
  • Para la mejor calidad de renderizado, usa la versión más grande disponible de la imagen. El visualizador la reduce para que quepa en la pared; las fuentes de baja resolución se ven borrosas en tamaños de impresión grandes.
  • No se requieren encabezados CORS. El póster se muestra como una imagen superpuesta, no dibujada en un canvas, así que una imagen de tu CDN se carga con normalidad.
  • La imagen debe tener 4 MB o menos. El servidor obtiene tu imagen de póster durante la generación de la vista previa y rechaza cualquier cosa más grande.

El servidor rechaza las URLs que no devuelven un Content-Type que comience con image/ (p. ej. una página que devuelva text/html fallará). Las URLs estándar de CDN de imágenes siempre cumplen este requisito.

La protección de hotlink es la causa habitual cuando una imagen no carga: bloquea las peticiones con un referrer ajeno, lo que rompe tanto la vista previa en el navegador como la descarga del servidor usada para descargas y compartidos. Desactívala para la ruta de la imagen del póster, o aloja esas imágenes donde no se aplique.


Hooks y filtros de WooCommerce

El plugin de WooCommerce coloca y da estilo al botón desde su propia pantalla de ajustes. Estos filtros y funciones auxiliares actúan donde esa pantalla no llega, como un tema con su propia plantilla de producto. Añádelos en el functions.php de tu tema o en un pequeño plugin del sitio.

Colocar el botón tú mismo

Pon “Posición en la página de producto” en “Lo coloco yo con un shortcode”, con lo que el plugin deja de añadir su propio botón, y escribe el shortcode donde tu tema o maquetador lo permita. En una página que no sea de producto, indica el producto por su ID.

[seeonwall_button]

[seeonwall_button id="123"]

Solo productos publicados: un ID que apunte a un borrador o a un producto pendiente no renderiza nada. El shortcode funciona con cualquier ajuste de posición, pero con los demás añade un segundo botón en lugar de mover el primero, así que elige “Lo coloco yo” cuando el shortcode deba ser el único.

Referencia de filtros

seeonwall_button_hook( string $hook, string $position ) — la acción de WooCommerce en la que se renderiza el botón. Una cadena vacía significa ninguna colocación automática.
seeonwall_button_priority( int $priority, string $position ) — la prioridad con la que el botón se engancha a esa acción, para moverlo dentro de un hook que otras cosas también usan.
seeonwall_button_html( string $html, WC_Product $product ) — el marcado del botón en sí, después de que el plugin haya escapado cada valor de atributo.
// Render on an action the settings list does not offer.
add_filter( 'seeonwall_button_hook', function () {
    return 'my_theme_after_gallery';
} );

// Or: no automatic placement at all, leaving the shortcode to place it.
add_filter( 'seeonwall_button_hook', '__return_empty_string' );

Añade los dos filtros de colocación antes de wp_loaded: el functions.php de un tema es lo bastante temprano. El plugin resuelve su colocación en wp_loaded precisamente para que un tema pueda adelantarse.

Llamar al botón desde una plantilla

mount_html() devuelve el mismo marcado que configura la pantalla de ajustes, para cualquier producto que le pases.

if ( class_exists( 'SeeOnWall_Storefront' ) ) {
    echo SeeOnWall_Storefront::mount_html( $product );
}

Devuelve una cadena vacía si la tienda no está conectada o el producto no es apto. También carga el script del visualizador para el botón que devuelve, en cualquier página, así que funciona también fuera de las páginas de producto.


Dominios permitidos

Por defecto, el visualizador acepta solicitudes de creación de sesión desde cualquier origen. Puedes restringir esto a una lista específica de dominios para evitar que tu ID de tienda sea utilizado en otros sitios web.

→ Guía paso a paso: Dominios permitidos: dónde se puede abrir la vista previa

Cómo configurar

Abre el panel de administración → Ajustes de la tienda → Dominios permitidos. Añade cada dominio donde esté instalado tu embed (p. ej. ejemplo.com). Un subdominio no queda incluido en su dominio principal: añádelo por separado, o añade *.ejemplo.com para permitir todos los subdominios (ejemplo.com necesita su propia entrada). Un comodín debe ir sobre un dominio propio: *.com o *.myshopify.com se rechazan.

Qué sucede cuando se bloquea un dominio

En una página cuyo dominio no está en tu lista, el snippet quita el botón (salvo que el dominio de la imagen del póster esté en la lista), para que los compradores no inicien una vista previa que no se puede abrir. Si aun así se abre el visualizador allí, muestra una pantalla de error de "no permitido" en lugar del código QR, y no se crea ninguna sesión.

Entradas de ejemplo

example.com
www.example.com
*.example.com

Tanto ejemplo.com como https://ejemplo.com se aceptan — el protocolo se elimina y solo se almacena el nombre de host. Se pueden añadir hasta 30 dominios.

Recomendamos añadir el dominio de tu tienda a la lista. Sin él, cualquiera que encuentre tu ID de tienda puede incrustar el visualizador en su propio sitio web y consumir el límite de velocidad de tu plan.


Política de seguridad de contenido

Si tu tienda establece un encabezado Content-Security-Policy, necesitas incluir seeonwall.com en la lista blanca para que el snippet se cargue y el visualizador se incruste correctamente.

Directivas CSP requeridas

script-src https://seeonwall.comPermite cargar el script del snippet.
frame-src https://seeonwall.comPermite incrustar el iframe del visualizador.
connect-src https://seeonwall.comPermite las llamadas API del snippet desde tu página: configuración de la tienda, la vista previa rápida en la pared, las variantes del póster y el análisis de pedidos.
style-src 'unsafe-inline'Permite la hoja de estilos que el snippet inyecta para el botón y el modal. Solo es necesario si tu política define style-src.

Las llamadas API del visualizador ocurren dentro del iframe de seeonwall.com, así que no cuentan para el connect-src de la página de tu tienda — pero el snippet mismo llama a https://seeonwall.com/api/ desde tu página: para leer la configuración de tu tienda (marca, dominios permitidos, límite mensual), y para la vista previa rápida en la pared, las variantes del póster, el análisis de pedidos y los informes de errores. Si la CSP bloquea la llamada de configuración, el snippet mantiene los botones y el logo de seeonwall.com permanece en el botón incluso en los planes que lo ocultan. La URL de tu imagen de póster se carga dentro del contexto del iframe, por lo que no necesitas añadir tu host de imágenes a la directiva img-src de la página de la tienda.

Valor mínimo de ejemplo del encabezado

Content-Security-Policy: script-src 'self' https://seeonwall.com; frame-src https://seeonwall.com; connect-src 'self' https://seeonwall.com; style-src 'self' 'unsafe-inline';

SPA y páginas dinámicas

El snippet funciona automáticamente en aplicaciones de página única y en cualquier página que añada elementos .seeonwall-button dinámicamente después de la carga inicial.

Después del escaneo inicial del DOM, el snippet instala un MutationObserver en el cuerpo del documento. Cada vez que se añaden nuevos elementos .seeonwall-button al DOM — ya sea por un renderizado de React, un cambio de ruta o cualquier otra actualización dinámica — el observador los detecta e inyecta el botón de vista previa inmediatamente.

No se necesita configuración especial. No necesitas llamar a SeeOnWall.init() de nuevo después de eventos de navegación o re-renderizados. Los botones que ya fueron inyectados se rastrean y no se procesarán una segunda vez.


Solución de problemas

Problemas comunes y cómo resolverlos.

→ Guía paso a paso: ¿Por qué no aparece el botón?

El botón "Ver en la pared" no aparece en la página.

Comprueba que: (1) la etiqueta de script está en el <head> de la página con un data-shop-id válido; (2) el elemento de montaje tiene exactamente la clase seeonwall-button (sensible a mayúsculas); (3) data-poster-url es una URL absoluta; (4) data-poster-width y data-poster-height están configurados, o se usa data-poster-sizes; (5) tu límite mensual de vistas de pósters no está agotado — si lo está, el botón se oculta hasta que cambie el mes o mejores de plan. Abre la consola del navegador para ver advertencias con el prefijo [SeeOnWall].

Al hacer clic en el botón se abre el modal pero inmediatamente muestra un error.

La causa probable es que tu límite horario de sesiones se ha alcanzado — espera a la siguiente hora UTC o mejora tu plan. Una página cuyo dominio no está en tu lista de dominios permitidos, o un data-shop-id incorrecto, quita el botón en su lugar, con un aviso [SeeOnWall] en la consola. → Dominios permitidos

El código QR aparece pero la página móvil dice "sesión no encontrada" o "sesión expirada".

Las sesiones son válidas durante 7 días. El visitante puede haber escaneado un código QR antiguo de una visita anterior. Cerrar y volver a abrir el modal genera una sesión nueva con un código QR nuevo. También confirma que el teléfono del visitante tiene conexión a internet.

La vista previa final se ve borrosa o la imagen del póster no se renderiza.

La URL de la imagen del póster debe ser públicamente accesible y no estar bloqueada por protección de hotlink — revisa la configuración de imágenes de tu CDN o plataforma de tienda. Asegúrate también de que la resolución de la imagen fuente sea suficiente para el tamaño de póster seleccionado. → Requisitos de imagen

La consola del navegador muestra un error de Content-Security-Policy.

Añade script-src, frame-src y connect-src para https://seeonwall.com al encabezado CSP de tu tienda, y permite la hoja de estilos que inyecta el snippet. Consulta la sección de Política de seguridad de contenido para el ejemplo completo. → CSP / CORS

El botón aparece y luego desaparece en desarrollo local.

Si tu lista de dominios permitidos no está vacía, añade http://localhost:PUERTO a ella mientras desarrollas. Una lista vacía (el valor predeterminado) permite todos los orígenes incluyendo localhost. → Dominios permitidos

El botón ha dejado de funcionar en todas las páginas, aunque no has cambiado nada.

Consulta la página de estado. Muestra si seeonwall.com tiene un problema conocido. Si no aparece ningún problema, escribe a support@seeonwall.com. → Estado


Soporte

Cómo contactarnos y cuánto tarda una persona en responder. Los plazos son para la primera respuesta, no para la solución.

  • Free: escribe a support@seeonwall.com. Respondemos lo antes posible, sin un plazo comprometido.
  • Basic: escribe a support@seeonwall.com. Primera respuesta en un máximo de 3 días laborables.
  • Premium y Ultra: envía una solicitud de soporte desde la página de Soporte de tu panel o de la app de Shopify, o escribe a support@seeonwall.com. Primera respuesta en un máximo de 1 día laborable.

Los días laborables son de lunes a viernes, sin contar los festivos de Polonia. Una solicitud enviada en fin de semana o en festivo cuenta desde el siguiente día laborable.

Si el botón dejó de funcionar en todas las páginas, consulta primero la página de estado: muestra los problemas conocidos mientras ocurren. → Estado


Pruebas y staging

Usa el entorno de staging para probar tu integración sin afectar a los datos de producción.

URLs de staging

Reemplaza la URL de producción con la URL de staging al hacer pruebas:

<script
  src="https://staging.seeonwall.com/seeonwall.js"
  data-shop-id="YOUR_STAGING_SHOP_ID"
  data-embed-url="https://staging.seeonwall.com/visualizer/embed"
></script>

Sin data-embed-url, el snippet abre el visualizador de producción, que no conoce el ID de tu tienda de staging. Con él, el iframe del visualizador carga desde: https://staging.seeonwall.com/visualizer/embed

Obtener un ID de tienda de staging

Crea una cuenta separada en staging.seeonwall.com/admin. Las cuentas de staging y de producción son completamente independientes — los datos nunca cruzan entre entornos.

Aislado de producción

Las sesiones creadas en staging no cuentan para tus límites de velocidad de producción ni para la analítica. Puedes ejecutar tantos flujos de prueba como necesites sin afectar las métricas de uso de tu tienda.

Depuración en la consola del navegador

El snippet registra información útil en la consola del navegador. Abre DevTools y busca:

  • [SeeOnWall] — avisos sobre problemas que el snippet ha encontrado (atributos del botón ausentes o ilegibles, ID de tienda desconocido, límite de vistas agotado, página que no está en la lista de dominios permitidos)
  • eventos postMessage entre tu página y el iframe del visualizador — inspeccionalos con: window.addEventListener('message', e => console.log(e))
  • Pista de sesión almacenada en el localStorage del origen de tu tienda, una entrada por tienda — inspecciónala en: localStorage.getItem('seeonwall:session:TU_SHOP_ID'). El JSON incluye sessionId, expiresAt, state (creating o ready) y opcionalmente referenceSize. Es una pista de interfaz, no autorización.
  • Pestaña de red — el snippet llama a /api/shops/* desde tu página, y el iframe a /api/sessions/* y /api/storage/*; comprueba los códigos de respuesta si el flujo se detiene

Privacidad y GDPR

seeonwall.com está diseñado para ser respetuoso con la privacidad por defecto: sin cuentas de cliente, sin cookies de seguimiento y sin nada que se conserve más de 7 días.

  • Sin cuentas de usuario. Los visitantes usan el visualizador sin registrarse ni iniciar sesión.
  • Sin cookies de seguimiento. El snippet no establece ninguna cookie en la página de tu tienda. Guarda entradas en el localStorage del origen de tu tienda — el ID de la sesión actual, su caducidad, la pista de preparación y opcionalmente el tamaño de comparación, además de tokens de acceso de corta duración para esa sesión — y el visualizador guarda entradas similares en el origen de seeonwall.com, para que los visitantes puedan reanudar una sesión en curso sin repetir el paso de la foto. Si activas el análisis de pedidos y el cliente da su consentimiento, la entrada también guarda los pósters que estuvieron en su pared en esta sesión.
  • Las fotos de pared son temporales. Cada foto subida se almacena solo durante la duración de la sesión (máximo 7 días) y se elimina automáticamente cuando la sesión expira.
  • Las sesiones se eliminan automáticamente. Todos los datos de la sesión — incluidas las coordenadas de calibración y la colocación del póster — se eliminan permanentemente al vencer. No hay archivo ni copia de seguridad.
  • Sin identificadores personales. Las sesiones se identifican por un UUID aleatorio. No se vincula ninguna dirección de correo electrónico, nombre, dirección IP ni huella digital del dispositivo a los datos de la sesión.
  • Las fotos de pared se analizan con IA. Cada foto pasa por la pasarela europea de Requesty (Fráncfort) hasta un modelo de IA en Amazon Bedrock en Fráncfort para localizar la pared, estimar su tamaño y detectar contenido inapropiado. El análisis se ejecuta dentro de la UE, las fotos nunca se usan para entrenar modelos y el análisis se elimina junto con la sesión.

Si tu tienda opera bajo el RGPD, es posible que quieras añadir una breve mención en tu política de privacidad indicando que la función de vista previa de pared está desarrollada por seeonwall.com, que las fotos de pared temporales se almacenan hasta 7 días antes de la eliminación automática y que cada foto es analizada con IA a través de Requesty y Amazon Bedrock (Amazon Web Services) como subencargados del tratamiento. Las fotos se tratan dentro de la UE. → Subencargados