Cómo crear bloques de HTML y CSS personalizados para Klaviyo Customer Hub

Objetivos del artículo

Cómo crear un bloque personalizado para tu Klaviyo Customer Hub con tu propio HTML y CSS. Úsalo para crear contenido con tu marca, como tarjetas de progreso de lealtad, módulos promocionales y tablas comparativas, cuando los campos del bloque de contenido estándar no sean lo suficientemente flexibles.

Antes de empezar

Esta guía se basa en bloques de contenido. Si aún no has creado un bloque de contenido, empieza con Cómo crear bloques de contenido para Klaviyo Customer Hub. Para cambiar el aspecto de todo tu Klaviyo Customer Hub en lugar de un solo bloque, consulta Cómo dar estilo a tu Klaviyo Customer Hub.

Lo que puedes hacer con bloques HTML personalizados

Un bloque HTML personalizado es un bloque de contenido avanzado con dos campos de código: uno para HTML y otro para CSS. HTML define la estructura y el contenido del bloque, y CSS controla su estilo, diseño y comportamiento responsivo. Usa bloques HTML personalizados para:

• Muestra una tarjeta de progreso de lealtad o un resumen de recompensas con puntos o datos de nivel de un perfil de Klaviyo.
• Crea una tabla comparativa, por ejemplo, para explicar niveles de membresía o planes.
• Crea un banner o módulo promocional que coincida con tu marca.
• Organiza el contenido de maneras que los campos estándar de encabezado, párrafo e imagen no permiten.
• Agrega funcionalidades, como una lista de deseos de terceros o una herramienta de reseñas, haciendo referencia a un elemento personalizado definido en tu sitio.

Los bloques de HTML personalizado aparecen en la pestaña Para ti junto con tus otros bloques de contenido, y también puedes usarlos en bloques de contenido del sitio. El estado de inicio de sesión, la visibilidad basada en grupos, la programación y la configuración del contexto de visualización funcionan de la misma manera que en otros bloques de contenido.

Qué es compatible y qué no lo es

Klaviyo depura el HTML y el CSS, y limita el alcance del CSS al bloque para que no pueda cambiar el resto de tu Klaviyo Customer Hub ni tu sitio web. Ten en cuenta estos límites:

• Compatible: HTML para la estructura y el contenido, CSS para el estilo y el diseño, etiquetas de personalización de Klaviyo para los datos del perfil y elementos personalizados definidos en el sitio para cualquier funcionalidad adicional.
• JavaScript vive en tu sitio, no en el bloque: No puedes escribir JavaScript directamente en el campo HTML. Cualquier cosa que escribas ahí se elimina y no se guarda. Para agregar funcionalidad, incluidas las integraciones de terceros, define un elemento personalizado en tu propio sitio y haz referencia a este en tu bloque. Consulta Integrar herramientas de terceros con elementos personalizados a continuación.
• No compatible: CSS que afecte cualquier cosa fuera de tu bloque, como el estilo de toda la página, o ediciones del marcado de los bloques nativos de Klaviyo.
• Datos: Cualquier dato que muestres debe provenir de las propiedades del perfil de Klaviyo mediante etiquetas de personalización. Los datos del evento no son compatibles.

Crear un bloque HTML personalizado

1. Ve a Klaviyo Customer Hub en la pestaña Sitio web.
2. Selecciona Diseño en la navegación de Klaviyo Customer Hub.
3. Haz clic en Editar Hub para abrir el editor de Klaviyo Customer Hub.
4. Selecciona el “+” en la barra de navegación izquierda para agregar un bloque de contenido
5. Haz clic en Crea el tuyo y, después, elige HTML en la parte superior del panel de contenido para usar campos separados de HTML y CSS.
6. Ingresa un nombre interno. Klaviyo usa este nombre para generar informes sobre los clics en el bloque, y no puedes cambiarlo después de que se cree el bloque.
7. Ingresa el código en los campos de HTML y CSS. Consulta Escribe el HTML y el CSS a continuación.
8. Configura quién ve el bloque con el estado de inicio de sesión, la visibilidad basada en grupos, la programación y el contexto de visualización.
9. Revisa la vista previa en vivo y resuelve cualquier advertencia de validación. Con HTML seleccionado, haz clic en Publicar para guardar el bloque. Para mostrarlo en el sitio, Klaviyo Customer Hub también debe estar en vivo.

Escribe tu HTML y CSS

Agrega tu HTML

Usa el campo HTML para crear la estructura del bloque con elementos estándar, como encabezados, párrafos, listas, enlaces, imágenes y tablas. Vincula páginas de tu sitio con etiquetas de anclaje normales. Como no se puede escribir JavaScript en el bloque, los botones y enlaces deben apuntar a una URL. Para cualquier cosa más interactiva, usa un elemento personalizado.

Aplicar estilo con CSS

Usa el campo de CSS para controlar el espaciado, el color, la tipografía y el diseño responsivo. El CSS solo se aplica a este bloque. De forma predeterminada, el estilo de un bloque HTML personalizado se ajusta para coincidir con los otros bloques de contenido, así que solo necesitas escribir CSS para las partes que quieras cambiar.

• Asigna nombres de clase personalizados a los elementos, como rewards-card, y luego segmenta esas clases en el CSS.
• Agrega @media reglas para que el bloque se vea bien en pantallas pequeñas.
• Usa font-family: inherit para que el texto coincida con las fuentes que elegiste en la pestaña Estilo.

Añadir personalización

Usa las etiquetas de personalización de Klaviyo en el HTML para mostrar datos del perfil, como el saldo de puntos de lealtad. Incluye siempre un valor predeterminado para que el bloque no muestre espacios en blanco cuando un comprador no haya proporcionado los datos. Los datos del perfil solo aparecen para compradores que hayan iniciado sesión o estén identificados. Todos los demás ven el valor predeterminado.

Ejemplo: tarjeta de puntos de fidelización

Este ejemplo muestra el nivel y el saldo de puntos de un comprador con un botón que vincula a la página de recompensas. Reemplaza los nombres de propiedad (loyalty_points y Membership Tier) por las propiedades del perfil que sincroniza tu integración de lealtad y actualiza la URL del enlace.

<div class="rewards-card">
  <p class="rewards-eyebrow">{{ person|lookup:'Membership Tier'|default:'Member' }} status</p>
  <h3 class="rewards-points">{{ person|lookup:'loyalty_points'|default:'0'|floatformat:0 }} points</h3>
  <p class="rewards-copy">Redeem your points for discounts on your next order.</p>
  <a class="rewards-button" href="/pages/rewards">Redeem rewards</a>
</div>

.rewards-card {
  padding: 20px;
  border-radius: 12px;
  background: #f6f1ea;
  color: #232323;
  font-family: inherit;
}

.rewards-eyebrow {
  margin: 0 0 4px;
  font-size: 12px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
}

.rewards-points {
  margin: 0 0 8px;
  font-size: 28px;
  line-height: 1.2;
}

.rewards-copy {
  margin: 0 0 16px;
  font-size: 14px;
}

.rewards-button {
  display: inline-block;
  padding: 10px 18px;
  border-radius: 999px;
  background: #232323;
  color: #ffffff;
  font-size: 14px;
  text-decoration: none;
}

@media (max-width: 480px) {
  .rewards-card {
    padding: 16px;
  }

  .rewards-points {
    font-size: 24px;
  }
}

Ejemplo: tabla comparativa de membresías

Este ejemplo compara dos niveles de membresía. El contenedor permite que la tabla se desplace horizontalmente en pantallas estrechas en lugar de romper el diseño.

<div class="compare-wrap">
  <table class="compare">
    <thead>
      <tr>
        <th></th>
        <th>Standard</th>
        <th>VIP</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">Free shipping</th>
        <td>Orders over $75</td>
        <td>Always</td>
      </tr>
      <tr>
        <th scope="row">Early access</th>
        <td>No</td>
        <td>Yes</td>
      </tr>
      <tr>
        <th scope="row">Birthday reward</th>
        <td>Yes</td>
        <td>Yes</td>
      </tr>
    </tbody>
  </table>
</div>

.compare-wrap {
  overflow-x: auto;
}

.compare {
  width: 100%;
  border-collapse: collapse;
  font-size: 14px;
}

.compare th,
.compare td {
  padding: 10px 12px;
  border-bottom: 1px solid #e4e4e4;
  text-align: left;
}

.compare thead th {
  background: #f6f1ea;
}

Integra herramientas de terceros con elementos personalizados

No puedes escribir JavaScript directamente en un bloque HTML personalizado, pero aun así puedes agregar funcionalidad basada en JavaScript haciendo referencia a un elemento personalizado que define el sitio. Un elemento personalizado es una etiqueta HTML reutilizable con un nombre con guion, como <wishlist-widget>, que un desarrollador registra en JavaScript en la tienda online. El bloque solo contiene la etiqueta, y el código del sitio hace el trabajo. Usa este enfoque para mostrar contenido de herramientas de terceros, como una lista de deseos, reseñas o apps de lealtad.

Cómo funciona

1. El desarrollador o la app de terceros define el elemento personalizado en la tienda. Por lo general, esto se hace a través del tema o del script propio de la app.
2. En el campo HTML, agrega la etiqueta donde quieras que aparezca el elemento. Se permite cualquier nombre de etiqueta que contenga un guion.
3. De manera opcional, pasa datos de perfil al elemento como atributos usando etiquetas de personalización.
4. Publica el bloque. Cuando Klaviyo Customer Hub se carga en una página donde tu sitio ha definido el elemento, el código del sitio lo renderiza dentro del bloque.

Este ejemplo coloca un elemento de lista de deseos en un bloque y le pasa la dirección de correo electrónico del comprador. El enlace dentro de la etiqueta es contenido alternativo que aparece si el elemento no está definido en la página. Reemplaza el nombre de la etiqueta y los atributos por los que use tu herramienta de terceros.

<div class="wishlist-block">
  <h3>Your wishlist</h3>
  <wishlist-widget customer-email="{{ person.email }}" max-items="4">
    <a href="/pages/wishlist">View your wishlist</a>
  </wishlist-widget>
</div>

Lo que debes saber

• El elemento debe definirse en tu sitio. Solo funciona en páginas donde el sitio haya cargado el script que lo define. Klaviyo no carga scripts de terceros por ti. Agrega contenido de respaldo dentro de la etiqueta para que los compradores vean algo útil si el elemento no está disponible.
• Personalization funciona con atributos. Se aplican las mismas reglas que en cualquier otra parte del bloque. Los datos del perfil solo aparecen para compradores que iniciaron sesión o están identificados, así que incluye un valor predeterminado para todos los demás.
• Los elementos personalizados heredan los estilos del sitio. Klaviyo Customer Hub no se muestra dentro de un iframe ni de un shadow DOM, así que el elemento personalizado adopta el CSS del sitio y puede verse afectado por él. También puedes aplicar estilo a la etiqueta del elemento desde el CSS del bloque.
• Escribe JavaScript en tu sitio, no en el bloque. Cualquier JavaScript que ingreses en el campo HTML se elimina y no se guarda. Define la funcionalidad en un elemento personalizado en tu sitio y luego haz referencia a ese elemento desde el bloque.
• Eres responsable del código y los datos de terceros. Antes de pasar datos del perfil a una herramienta de terceros, asegúrate de que hacerlo cumpla con tus obligaciones de privacidad. El equipo de soporte de Klaviyo no puede solucionar problemas de tu elemento personalizado ni de la herramienta de terceros que hay detrás.

Usa HTML personalizado en bloques en el sitio

El HTML personalizado funciona de la misma manera en los bloques de contenido en el sitio que en la pestaña Para ti. Creas el bloque en el mismo editor de bloques de contenido usando los campos HTML y CSS, y todo lo que se describe en este artículo aplica, incluidas las etiquetas de personalización, los elementos personalizados y el seguimiento de clics.

Ten en cuenta estos puntos cuando el bloque se muestre en la tienda:

• El CSS del sitio puede afectar el bloque. Los bloques en el sitio se muestran directamente en la página, por lo que los estilos del sitio pueden influir en cómo se ven. Revisa el bloque en la página en vivo después de publicar.
• La vista previa puede ser diferente a la página en vivo. La vista previa del editor no puede reproducir todos los estilos de tu sitio.
• Los elementos personalizados deben cargarse en todas las páginas donde aparezca el bloque. Asegúrate de que el script que define el elemento personalizado se cargue en cada página donde se muestre el bloque.

Usa HTML personalizado en los bloques de contenido en el sitio

El HTML personalizado también funciona en los bloques de contenido del sitio, que se muestran directamente en las páginas de la tienda en lugar de dentro del panel deslizable de Klaviyo Customer Hub. Los creas en el mismo editor de bloques de contenido y se aplican las mismas reglas: elige HTML para usar campos separados de HTML y CSS, usa la etiqueta de personalización para los datos del perfil y haz referencia a elementos personalizados para cualquier funcionalidad adicional. Algunas cosas funcionan de forma diferente en el sitio:

• El CSS del sitio tiene más influencia. El bloque se renderiza directamente en la página, por lo que los estilos del sitio pueden afectarlo más de lo que lo hacen dentro del panel lateral de Klaviyo Customer Hub. Prueba el CSS en la página publicada.
• Es posible que la vista previa no coincida exactamente con la página. Usa la vista previa en el sitio para revisar el bloque y luego confirma cómo se ve el bloque publicado en la tienda.
• Los elementos personalizados deben cargarse en todas las páginas donde aparezca el bloque. Si haces referencia a un elemento personalizado, asegúrate de que el script que lo define se cargue en cada página donde se muestre tu bloque en el sitio.

Previsualiza y prueba el bloque

La vista previa se actualiza a medida que editas el HTML y el CSS. Si hay un error en el código, el editor muestra un mensaje de validación para que puedas corregirlo antes de publicar. Antes de publicar:

• Usa Vista previa como para seleccionar un perfil y comparar las vistas de sesión iniciada y sesión cerrada.
• Prueba con un perfil al que le falten los datos que usan tus etiquetas de personalización, para confirmar que los valores predeterminados se vean bien.
• Revisa el bloque en tamaños de pantalla para móvil y escritorio.

Realizar un seguimiento del rendimiento del bloque

Klaviyo registra cada clic en un bloque HTML personalizado como un evento de Klaviyo Customer Hub hizo clic en el bloque de contenido, usando el nombre interno del bloque, y lo reporta de la misma forma que otros bloques de contenido. Klaviyo registra si se hizo clic en el bloque, no en qué enlace o botón individual dentro de él se hizo clic.

Mejores prácticas

• Manténlo simple. Empieza con el estilo predeterminado y modifica solo lo que necesites.
• Protege los datos personales. Si un bloque se muestra a compradores con sesión iniciada o reconocidos, no incluyas información personal sensible. Eres responsable de la privacidad de los datos que agregas a los bloques personalizados.
• Establece siempre valores predeterminados. Los visitantes anónimos y los perfiles con datos faltantes deberían seguir viendo un bloque completo.
• Diseña primero para dispositivos móviles. La mayoría de las visitas a Customer Hub se realizan en pantallas pequeñas, así que prueba primero los diseños estrechos.
• Nombra los bloques con claridad. Los nombres internos se usan en la elaboración de informes y no se pueden cambiar después.

Guía de solución de problemas

Mi bloque no se publica

Revisa los campos de HTML y CSS para ver los mensajes de validación, corrige los errores y vuelve a publicar. Si tu bloque depende de JavaScript, ten en cuenta que el JavaScript que se ingresa en el campo de HTML se elimina y no se guarda. Mueve esa funcionalidad a un elemento personalizado en el sitio y haz referencia a él en el bloque.

Mis estilos no se aplican

El CSS está limitado al bloque, así que los selectores deben coincidir con los elementos dentro de tu propio HTML. Revisa que los nombres de clase no tengan errores tipográficos. El CSS no puede aplicar estilos a nada fuera del bloque.

Personalization muestra texto en blanco o predeterminado

Los datos del perfil solo aparecen para compradores que hayan iniciado sesión o estén identificados. Confirma que el nombre de la propiedad en tu etiqueta coincida exactamente con las propiedades del perfil, incluida la capitalización, y agrega un valor predeterminado.

El bloque se ve diferente en mi sitio que en la vista previa

El CSS del sitio puede influir en cómo se renderiza Klaviyo Customer Hub, especialmente en los bloques del sitio, que se muestran directamente en la página. Revisa el bloque publicado en el sitio en vivo y ajusta el CSS según sea necesario.

Mi elemento personalizado está en blanco o no se muestra

El elemento solo se renderiza en las páginas donde tu sitio ha cargado el script que lo define. Confirma que el script se cargue en cada página donde se muestre el bloque y revisa que el nombre de la etiqueta en tu HTML coincida con el nombre que tu desarrollador registró. Si en su lugar ves el contenido de respaldo, el elemento no está definido en esa página.

Necesito ayuda para escribir código

El equipo de soporte de Klaviyo no puede escribir ni depurar HTML y CSS personalizados por ti. Si necesitas ayuda, trabaja con un desarrollador o con un socio de Klaviyo.