Como criar blocos personalizados de HTML e CSS para o Klaviyo Customer Hub

O que você vai aprender

Como criar um bloco personalizado para o seu Klaviyo Customer Hub usando seu próprio HTML e CSS. Use para criar conteúdo com a identidade da sua marca, como cartões de progresso de fidelidade, módulos promocionais e tabelas comparativas, quando os campos padrão do bloco de conteúdo não forem flexíveis o suficiente.

Antes de começar

Este guia se baseia em blocos de conteúdo. Se você ainda não criou um bloco de conteúdo, comece com Como criar blocos de conteúdo para o Klaviyo Customer Hub. Para mudar a aparência de todo o seu Klaviyo Customer Hub, em vez de um único bloco, consulte Como estilizar seu Klaviyo Customer Hub.

O que você pode fazer com blocos HTML personalizados

Um bloco de HTML personalizado é um bloco de conteúdo avançado com dois campos de código: um para HTML e outro para CSS. O HTML define a estrutura e o conteúdo do bloco, e o CSS controla o estilo, o layout e o comportamento responsivo. Use blocos de HTML personalizado para:

• Mostre um cartão de progresso de fidelidade ou um resumo de recompensas usando dados de pontos ou de nível de um perfil do Klaviyo.
• Crie uma tabela de comparação, por exemplo, para explicar níveis de assinatura ou planos.
• Crie um banner promocional ou um módulo que combine com a sua marca.
• Organize o conteúdo de maneiras que os campos padrão de cabeçalho, parágrafo e imagem não permitem.
• Adicione funcionalidades, como uma lista de desejos de terceiros ou uma ferramenta de avaliações, referenciando um elemento personalizado definido no seu site.

Os blocos de HTML personalizado aparecem na aba Para você, junto com seus outros blocos de conteúdo, e você também pode usá-los em blocos de conteúdo no site. As configurações de status de login, visibilidade baseada em grupos, agendamento e contexto de exibição funcionam da mesma forma que em outros blocos de conteúdo.

O que é compatível e o que não é

A Klaviyo higieniza seu HTML e CSS e aplica um escopo ao seu CSS no bloco para que ele não consiga alterar o restante do seu Klaviyo Customer Hub ou do seu site. Tenha estes limites em mente:

• Compatível: HTML para estrutura e conteúdo, CSS para estilo e layout, tags de personalização da Klaviyo para dados de perfil e elementos personalizados definidos no seu site para qualquer funcionalidade adicional.
• O JavaScript fica no seu site, não no bloco: Você não pode escrever JavaScript diretamente no campo HTML. Qualquer coisa que você inserir ali será removida e não será salva. Para adicionar funcionalidades, incluindo integrações de terceiros, defina um elemento personalizado no seu próprio site e faça referência a ele no seu bloco. Veja Integrar ferramentas de terceiros com elementos personalizados abaixo.
• Não compatível: CSS que afeta qualquer coisa fora do seu bloco, como um estilo aplicado à página inteira, ou edições na marcação dos blocos nativos da Klaviyo.
• Dados: Quaisquer dados que você exibir devem vir das Propriedades do perfil do Klaviyo por meio de tag de personalização. Os dados do evento não são suportados.

Criar um bloco HTML personalizado

1. Acesse o Klaviyo Customer Hub na aba Website.
2. Selecione Design na navegação do Klaviyo Customer Hub.
3. Clique em Editar seu Hub para abrir o editor do Klaviyo Customer Hub.
4. Selecione o “+” na barra de navegação à esquerda para adicionar um bloco de conteúdo
5. Clique em Crie o seu e, em seguida, escolha HTML na parte superior do painel de conteúdo para usar campos separados de HTML e CSS.
6. Insira um Nome interno. A Klaviyo usa esse nome para informar os cliques no bloco, e você não pode alterá-lo depois que o bloco for criado.
7. Insira seu código nos campos HTML e CSS. Veja Escreva seu HTML e CSS abaixo.
8. Configure quem vê o bloco usando status de login, visibilidade baseada em grupos, agendamento e contexto de exibição.
9. Revise a prévia ao vivo e resolva quaisquer avisos de validação. Com HTML selecionado, clique em Publicar para salvar seu bloco. Para exibir no seu site, o Klaviyo Customer Hub também precisa estar ao vivo.

Escreva seu HTML e CSS

Adicione seu HTML

Use o campo HTML para criar a estrutura do seu bloco com elementos padrão, como títulos, parágrafos, listas, links, imagens e tabelas. Crie links para páginas no seu site usando tags de âncora comuns. Como não dá para escrever JavaScript no bloco, botões e links devem direcionar para um URL. Para qualquer coisa mais interativa, use um elemento personalizado.

Estilize com CSS

Use o campo CSS para controlar espaçamento, cor, tipografia e layout responsivo. Seu CSS se aplica apenas a este bloco. Por padrão, um bloco de HTML personalizado é estilizado para corresponder aos seus outros blocos de conteúdo, então você só precisa escrever CSS para as partes que quer alterar.

• Dê aos seus elementos seus próprios nomes de classe, como rewards-card, e direcione essas classes no seu CSS.
• Adicione @media regras para que o bloco fique com a aparência correta em telas pequenas.
• Use font-family: inherit para que o texto corresponda às fontes que você escolheu na aba Estilo.

Adicionar personalização

Use as tags de personalização da Klaviyo no seu HTML para mostrar dados do perfil, como um saldo de pontos de fidelidade. Sempre inclua um valor padrão para que o bloco não exiba espaços em branco quando um cliente não tiver fornecido os dados. Os dados do perfil só aparecem para clientes conectados ou identificados. Todos os outros veem o valor padrão.

Exemplo: cartão de pontos de fidelidade

Este exemplo mostra o nível e o saldo de pontos de um cliente, com um botão que direciona para a sua página de recompensas. Substitua os nomes das propriedades (loyalty_points e Membership Tier) pelas Propriedades do perfil que suas integrações de fidelidade sincronizam e atualize o URL do link.

<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;
  }
}

Exemplo: tabela de comparação de assinaturas

Este exemplo compara dois níveis de associação. O contêiner permite que a tabela seja rolada horizontalmente em telas estreitas, em vez de quebrar o layout.

<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;
}

Integre ferramentas de terceiros a elementos personalizados

Você não pode escrever JavaScript diretamente em um bloco de HTML personalizado, mas ainda pode adicionar funcionalidades baseadas em JavaScript fazendo referência a um elemento personalizado que seu site define. Um elemento personalizado é uma tag HTML reutilizável com um nome hifenizado, como <wishlist-widget>, que um desenvolvedor registra em JavaScript na sua loja. Seu bloco contém apenas a tag, e o código do seu site faz o trabalho. Use esta abordagem para exibir conteúdo de ferramentas de terceiros, como lista de desejos, avaliações ou apps de fidelidade.

Veja como funciona

1. Seu desenvolvedor ou o app de terceiros define o elemento personalizado na sua vitrine. Normalmente, isso é feito por meio do seu tema ou do próprio script do app.
2. No campo HTML, adicione a tag onde você quer que o elemento apareça. Qualquer nome de tag que contenha um hífen é permitido.
3. Opcionalmente, transmita dados do perfil para o elemento como atributos usando tags de personalização.
4. Publique seu bloco. Quando o Klaviyo Customer Hub é carregado em uma página em que seu site definiu o elemento, o código do seu site o renderiza dentro do bloco.

Este exemplo coloca um elemento de lista de desejos em um bloco e transmite a ele o endereço de e-mail do cliente. O link dentro da tag é um conteúdo alternativo que aparece se o elemento não estiver definido na página. Substitua o nome e os atributos da tag pelos que a sua ferramenta de terceiros usa.

<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>

O que saber

• O elemento precisa estar definido no seu site. Ele só funciona em páginas onde seu site carregou o script que o define. A Klaviyo não carrega scripts de terceiros para você. Adicione conteúdo de fallback dentro da tag para que os clientes vejam algo útil se o elemento não estiver disponível.
• A Personalização funciona em atributos. As mesmas regras se aplicam como em qualquer outro lugar no seu bloco. Os dados de perfil só aparecem para compradores que fizeram login ou foram identificados; por isso, inclua um valor padrão para todas as outras pessoas.
• Elementos personalizados herdam os estilos do seu site. O Klaviyo Customer Hub não é renderizado dentro de um iframe ou shadow DOM, então seu elemento personalizado aplica o CSS do seu site e pode ser afetado por ele. Você também pode estilizar a tag do elemento a partir do CSS do seu bloco.
• Escreva o JavaScript no seu site, não no bloco. Qualquer JavaScript que você inserir no campo HTML será removido e não será salvo. Defina a funcionalidade em um elemento personalizado no seu site e, em seguida, faça referência a esse elemento no seu bloco.
• Você é responsável por códigos e dados de terceiros. Antes de enviar dados de perfil para uma ferramenta de terceiros, verifique se isso atende às suas obrigações de privacidade. O suporte da Klaviyo não pode solucionar problemas do seu elemento personalizado nem da ferramenta de terceiros por trás dele.

Use HTML personalizado em blocos no site

O HTML personalizado funciona da mesma forma em blocos de conteúdo no site quanto na guia Para você. Você cria o bloco no mesmo editor de blocos de conteúdo usando os campos de HTML e CSS, e tudo deste artigo se aplica, incluindo tag de personalização, elementos personalizados e rastreamento de cliques.

Lembre-se destes pontos quando o bloco for exibido na sua vitrine:

• O CSS do seu site pode afetar o bloco. Os blocos no site são renderizados diretamente na sua página, então os estilos do seu site podem influenciar a aparência deles. Verifique o bloco na sua página publicada depois de publicar.
• A prévia pode ser diferente da sua página ativa. A prévia do editor não consegue reproduzir todos os estilos do seu site.
• Os elementos personalizados precisam ser carregados em todas as páginas em que o bloco aparece. Garanta que o script que define seu elemento personalizado seja carregado em cada página em que o bloco é exibido.

Use HTML personalizado em blocos de conteúdo no site

O HTML personalizado também funciona em blocos de conteúdo onsite, que são exibidos diretamente nas páginas da sua vitrine, em vez de dentro da gaveta do Klaviyo Customer Hub. Você os cria no mesmo editor de blocos de conteúdo, e as mesmas regras se aplicam: escolha HTML para usar campos separados de HTML e CSS, use tag de personalização para dados de perfil e faça referência a elementos personalizados para qualquer funcionalidade adicionada. Algumas coisas funcionam de forma diferente no onsite:

• O CSS do seu site tem mais influência. O bloco é renderizado diretamente na sua página, então os estilos do seu site podem afetá-lo mais do que afetam dentro da gaveta do Klaviyo Customer Hub. Teste seu CSS na página ao vivo.
• A prévia pode não corresponder exatamente à sua página. Use a prévia no site para conferir seu bloco e, em seguida, confirme como o bloco publicado aparece na sua loja.
• Os elementos personalizados precisam ser carregados em todas as páginas em que o bloco aparece. Se você referenciar um elemento personalizado, verifique se o script que o define é carregado em cada página em que o seu bloco no site é exibido.

Visualize e teste seu bloco

A prévia é atualizada conforme você edita seu HTML e CSS. Se houver um erro no seu código, o editor exibe uma mensagem de validação para que você possa corrigi-lo antes de publicar. Antes de publicar:

• Use Visualizar como para selecionar um perfil e comparar as visualizações Conectado e Desconectado.
• Teste com um perfil que não tenha os dados que suas tags de personalização usam para confirmar se seus valores padrão estão corretos.
• Confira o bloco nas larguras de celular e desktop.

Acompanhe o desempenho do bloco

A Klaviyo rastreia cada clique em um bloco HTML personalizado como um evento de clique no bloco de conteúdo do Klaviyo Customer Hub, usando o nome interno do bloco, e informa isso da mesma forma que outros blocos de conteúdo. A Klaviyo registra se o bloco foi clicado, e não qual link ou botão individual dentro dele foi clicado.

Práticas recomendadas

• Mantenha a simplicidade. Comece com o estilo padrão e sobrescreva apenas o que você precisa.
• Proteja os dados pessoais. Se um bloco for exibido para compradores com login ou reconhecidos, não inclua informações pessoais sensíveis. Você é responsável pela privacidade dos dados que você adiciona a blocos personalizados.
• Sempre defina valores padrão. Visitantes anônimos e perfis com dados ausentes ainda devem ver um bloco completo.
• Crie um design pensando primeiro em dispositivos móveis. A maioria das visitas ao Klaviyo Customer Hub acontece em telas pequenas, então teste primeiro layouts estreitos.
• Nomeie os blocos com clareza. Os nomes internos são usados em relatórios e não podem ser alterados depois.

Solução de problemas

Meu bloco não publica

Verifique se há mensagens de validação nos campos de HTML e CSS, corrija os erros e publique novamente. Se o seu bloco depender de JavaScript, observe que o JavaScript inserido no campo HTML é removido e não é salvo. Mova essa funcionalidade para um elemento personalizado no seu site e faça referência a ela no seu bloco.

Meus estilos não estão sendo aplicados

O CSS tem escopo limitado ao bloco, então seus seletores precisam corresponder a elementos dentro do seu próprio HTML. Verifique se há erros de digitação nos nomes das suas classes. Seu CSS não pode aplicar estilos a nada fora do bloco.

A personalização mostra texto em branco ou padrão

Os dados do perfil só aparecem para compradores que fizeram login ou foram identificados. Confirme se o nome da propriedade na sua tag corresponde exatamente às Propriedades do perfil, incluindo maiúsculas e minúsculas, e adicione um valor padrão.

O bloco aparece diferente no meu site do que na prévia

O CSS do seu site pode influenciar como o Klaviyo Customer Hub é exibido, especialmente para blocos no site, que aparecem diretamente na sua página. Confira o bloco publicado no seu site ativo e ajuste seu CSS conforme necessário.

Meu elemento personalizado está em branco ou não aparece

O elemento só é renderizado nas páginas em que seu site carregou o script que o define. Confirme se o script é carregado em todas as páginas em que o bloco é exibido e verifique se o nome da tag no seu HTML corresponde ao nome que seu desenvolvedor registrou. Se, em vez disso, você vir seu conteúdo de fallback, o elemento não está definido nessa página.

Preciso de ajuda para escrever código

O Suporte da Klaviyo não pode escrever nem depurar HTML e CSS personalizados para você. Se você precisar de ajuda, trabalhe com um desenvolvedor ou um parceiro da Klaviyo.