Design Studio — Conteúdo por audiência

O que essa funcionalidade resolve

Até aqui, o layout publicado no Design Studio era um só para todo mundo: a mesma home, a mesma vitrine e os mesmos produtos para qualquer visitante.

Ao mesmo tempo, a loja que usa o segmentador de audiências já sabe quem é o cliente — mas esse conhecimento só era acionado fora da loja (CRM, e-mail, campanha). Quando o cliente chegava na vitrine, a segmentação desaparecia.

Com vitrines por audiência, o lojista configura, dentro do mesmo bloco que já usa hoje, versões diferentes de conteúdo para audiências diferentes. Quem não pertence a nenhuma audiência configurada — e quem não está logado — continua vendo a versão padrão.

Não há página nova, ferramenta nova nem dependência de desenvolvedor. É a mesma tela, o mesmo fluxo, com uma seção a mais no painel do bloco.

Como funciona, em uma frase

Um bloco passa a ter uma versão padrão (obrigatória, é o content de sempre) e até 2 versões por audiência. Na renderização, o Storefront verifica as audiências do visitante e aplica, por cima da versão padrão, a primeira audiência configurada que o visitante possui. Nada bate? Renderiza a versão padrão.

Tudo isso acontece no servidor, na primeira pintura da página. Não existe estado de carregamento, troca de conteúdo na tela ou requisição adicional para popular a vitrine.

Vale para qualquer bloco do tema e para qualquer campo dele — não é um recurso exclusivo de vitrines de produto. O único requisito é que a agência declare a variação no schema daquele bloco (veja a Parte 1).

Pré-requisitos

Parte 1 — O que a agência precisa fazer no tema

1.1 Habilitar a variação no schema do bloco

A variação por audiência é opt-in por bloco. Ela só existe quando o *.schema.json declara varyByAudience como true, no nível do bloco (irmão de name, type e settings):

{
  "name": "Vitrine de produtos",
  "type": "product_carousel",
  "varyByAudience": true,
  "settings": [
    { "label": "Título",   "name": "title",    "type": "text" },
    { "label": "Produtos", "name": "products", "type": "product_list", "required": true }
  ]
}

Regras importantes:

• Vale para qualquer bloco. Não há lista de tipos suportados nem restrição a vitrines: banner, carrossel de banners, vitrine de produtos, faixa de texto, bloco de imagem, bloco autoral da agência — qualquer bloco do tema pode declarar a flag e passa a aceitar variação por audiência.
• Não existe um tipo de campo novo. Não há type: "audience" nem seletor de audiência declarável em settings. A flag no bloco é tudo o que o editor precisa para desenhar a seção de audiências.
• Não existe flag por campo. Quando o bloco é marcado, qualquer setting dele pode variar — texto, cor, imagem, url, select, checkbox, product_list, hotsite_products, etc.
• Bloco sem a flag continua idêntico ao que era. Se um layout tentar salvar variações em um bloco não marcado, o salvamento é rejeitado com HTTP 400.

1.2 O HTML do bloco não muda

O Blocks/<type>.html continua recebendo apenas block_data, exatamente como antes:

{{~
  titulo = block_data.title
  if titulo | string.empty
    titulo = "Destaques"
  end
~}}

<section class="vitrine">
  <h2>{{ titulo }}</h2>
  {{ spot_carousel products: block_data.products }}
</section>

O que chega em block_data já é o conteúdo resolvido para a audiência do visitante: a versão padrão com a variação aplicada por cima, quando houve match. O bloco não recebe — e não consegue ver — o contêiner de variações.

1.3 Ligar a resolução de audiência no SDK

A identificação do visitante é disparada pelo Storefront SDK, não pelo pipeline da página. Isso é intencional: CDN e cache de página ficam acima da aplicação, e uma requisição de página com frequência sequer chega ao servidor.

Use o SDK v1.3.0 ou superior e crie o client com a opção habilitada:

const clientConfig = {
    storefrontAccessToken: '{{settings.access_token}}',
    storeUrl: '{{store.urls.base}}',
    options: {
        resolveAudienceSegments: true
    }
};

const client = StorefrontClient.createClient(clientConfig);

Com a opção ligada, o SDK:

• chama a resolução logo após gravar o sf_customer_access_token e antes de devolver o controle para o redirecionamento pós-login — assim a primeira página depois do login já sai segmentada;
• refaz a chamada de forma idempotente quando existe token de cliente e não existe cookie de segmentos (cobre expiração do cookie e sessão persistida sem novo login);
• remove o cookie de segmentos no logout.

A opção nasce desligada. Se o tema não a ligar, nenhuma chamada é feita e a loja renderiza sempre a versão padrão.

1.4 Saber, no tema, se a loja tem o recurso

As configurações injetadas na página passam a carregar hasAudienceSegmentation, um booleano que indica se a segmentação por audiência está ativa para aquela loja. O identificador da loja no segmentador não é exposto ao cliente.

1.5 Checklist da agência

• O bloco que deve variar tem "varyByAudience": true no .schema.json.
• O .html do bloco lê apenas block_data, sem condicional por audiência.
• O tema usa o Storefront SDK v1.3.0+ e cria o client com resolveAudienceSegments: true.
• O content_for_page do pages.json continua declarando o type do bloco (nada muda aqui).
• A versão padrão do bloco está preenchida e faz sentido sozinha — é o que a maior parte do tráfego vai ver.

Parte 2 — O que o lojista faz no Design Studio

2.1 Onde fica

Ao selecionar um bloco preparado pela agência, o painel de configuração exibe:

• Versão padrão — "Todos os clientes". É a base, obrigatória.
• Audiências — acordeões criados conforme o lojista adiciona audiências, com o botão Adicionar audiência.

Um contador mostra o consumo do limite (Audiências: 1/2, Audiências: 2/2 (limite atingido)).

Blocos que já têm variação configurada recebem identificação visual na lista de blocos, com o ícone de audiência e a lista de audiências no tooltip.

2.2 Como preencher uma versão de audiência

Cada acordeão de audiência mostra todos os campos do bloco, pré-preenchidos com o valor da versão padrão. O lojista altera só o que precisa mudar.

O que fica igual à versão padrão não é salvo como variação — é herança. Isso significa que:

• deixar um campo em branco não é erro: aquele campo simplesmente vem da versão padrão;
• uma versão de audiência sem nenhuma alteração é aceita e renderiza o conteúdo padrão;
• alterar depois a versão padrão propaga para todas as audiências nos campos que elas não sobrescreveram.

Exemplo: um carrossel com título "Novidades" e 12 produtos. Na audiência "Aniversariantes do mês" o lojista troca apenas a lista de produtos. Se amanhã o título da versão padrão virar "Chegou agora", a audiência "Aniversariantes do mês" também passa a exibir "Chegou agora", mantendo a sua própria lista de produtos.

2.3 Preview por audiência

O editor tem a barra "Visão por audiência", no topo do preview, com as opções:

• Padrão — versão padrão, todos os clientes;
• uma opção por audiência configurada na página.

A pré-visualização é renderizada no servidor, na mesma requisição que devolve o HTML — o que você vê no preview é o que o cliente daquela audiência recebe.

Se a audiência selecionada não existe mais no segmentador, o preview mostra a versão padrão e informa: "Esta audiência não existe mais no Wake Experience. Nenhum cliente se enquadra nela, então a loja exibe a versão padrão deste bloco."

2.4 Ordem das audiências = precedência

Um mesmo cliente pode pertencer a várias audiências ao mesmo tempo. Quando isso acontece, vence a primeira audiência na ordem em que o lojista as configurou no bloco.

As versões nunca são combinadas entre si: aplica-se uma variação, e só uma. A ordem em que o segmentador devolve as audiências do cliente não influencia o resultado — quem decide é a ordem no bloco.

2.5 Remover uma audiência

Remover uma audiência do bloco apaga a variação daquele bloco. O diálogo pede confirmação. A versão padrão nunca pode ser removida.

Parte 3 — Regras, limites e comportamento

3.1 Limites

Sobre o teto de audiências:

• ele é por bloco, não por página. Um bloco com A e B e outro com B e C na mesma página são aceitos — a união da página é 3, e isso é permitido;
• a contagem ignora diferença de maiúsculas/minúsculas;
• audiências usadas em outros layouts da loja não consomem o limite deste bloco;
• o limite não é arbitrário: cada combinação de audiências gera uma variação de cache de página. Segurar o número por bloco é o que mantém a cardinalidade de cache administrável.

Se o limite for estourado, o salvamento falha com HTTP 400 e código CMS_BLOCK_AUDIENCE_LIMIT_EXCEEDED, informando o bloco, o teto, a contagem e os identificadores excedentes. Estourar o tamanho do layout devolve CMS_CONTENT_EXCEEDS_MAX_LENGTH.

3.2 Como o visitante é identificado

1. O cliente faz login. O SDK grava o sf_customer_access_token e chama GET /cms/segments.
2. O Storefront só prossegue se todas estas condições forem verdadeiras: a loja tem o add-on de audiências configurado, existe sf_customer_access_token. Caso contrário, qualquer cookie de segmentos existente é removido.
3. As audiências do cliente são consultadas pelo e-mail.
4. O resultado é cruzado duas vezes: com as audiências configuradas nos layouts ativos da loja e com o catálogo de audiências da loja. Sobra apenas o que existe nos dois lugares.
5. O conjunto resultante é gravado no cookie sf_segments_token, com validade de 60 minutos.
6. A resposta é sempre 204 No Content, sem corpo e sem cache — as audiências do cliente nunca são devolvidas ao navegador.

Na renderização da página, o Storefront lê apenas o cookie. Não há chamada externa, nem varredura de layouts, no caminho da página.

3.3 Quando o cliente vê a versão padrão

Sempre que:

• não está logado, ou o login não é do tipo autenticado;
• está logado, mas não pertence a nenhuma audiência configurada naquele bloco;
• pertence a uma audiência que foi removida do segmentador;
• a loja não tem o add-on ativo;
• a consulta de audiências falhou (timeout, erro, indisponibilidade).

Falha de resolução nunca derruba a página nem mostra erro para o cliente: o pior cenário é a loja se comportar exatamente como se comportava antes do recurso.

3.4 Propagação: o cookie é o limite da defasagem

O cookie de segmentos vale 60 minutos e não é invalidado por publicação.

Consequência prática, que vale explicar ao lojista: se você publicar agora um bloco com uma audiência nova, um cliente que já está logado só entra nessa audiência quando o cookie dele expirar (até 60 minutos) ou quando ele fizer login de novo. Novas sessões pegam a configuração nova imediatamente.

O mesmo vale no sentido inverso: uma audiência excluída do segmentador deixa de casar assim que o cookie for renovado.

3.5 Cache

O cache de página passa a variar pelo cookie sf_segments_token. Clientes com audiências diferentes nunca recebem o HTML um do outro; clientes com o mesmo conjunto de audiências compartilham a mesma entrada de cache. Tráfego anônimo continua exatamente como era.

3.6 O que não entra nesta versão

• Segmentação de conteúdo para visitante anônimo (por UTM, origem de campanha ou navegação).
• Audiências que dependem de algoritmo de recomendação (ex.: recomendação hiperpersonalizada). Como o conteúdo é escolhido manualmente pelo lojista, esses segmentos não se aplicam ao modelo.
• Exposição da segmentação na Storefront API / arquitetura headless.
• Replicação automática de variações entre templates ou entre URLs.

Parte 4 — Referência técnica

4.1 Formato armazenado

Cada bloco do layout pode ter, ao lado de content, a propriedade opcional audience_content. As chaves são os identificadores das audiências; os valores carregam apenas o que difere da versão padrão.

{
  "type": "product_carousel",
  "content": {
    "title": "Novidades",
    "products": [101, 102, 103]
  },
  "audience_content": {
    "aniversariantes": {
      "products": [201, 202, 203]
    },
    "ba9f7ba7-9267-4594-a8a1-2a2df47e966c": {
      "title": "Selecionamos pra você",
      "products": [301, 302]
    }
  }
}

Regras do contrato:

4.2 Códigos de erro

4.3 Endpoints e cookies

Perguntas frequentes

Preciso ter o add-on para usar o Design Studio?
Não. O Design Studio continua igual. O add-on libera apenas a variação por audiência dentro dos blocos.

Como contrato?
Abra um chamado na Central de Atendimento ou fale com o seu Customer Success solicitando a ativação do add-on de Audiências no Design Studio. É um aditivo contratual.

Posso usar em qualquer bloco?
Sim. Não há restrição de tipo: qualquer bloco do tema — banner, carrossel, vitrine de produtos, faixa de texto, bloco autoral da agência — pode ter variação por audiência, e qualquer campo desse bloco pode variar. O que define quais blocos oferecem a seção "Audiências" é a agência ter declarado varyByAudience: true no schema deles. Se o bloco que você quer segmentar ainda não oferece a seção, é uma alteração de uma linha no schema — fale com a sua agência.

Por que só 2 audiências por bloco?
Cada combinação de audiências gera uma variação de cache da página. O teto protege a performance da loja. Ele é por bloco: páginas com vários blocos segmentados podem, somadas, usar mais audiências.

Cliente deslogado vê a versão segmentada?
Não. A audiência é resolvida pelo e-mail do cliente autenticado. Sem login, sempre versão padrão.

Tem "piscar" de conteúdo — mostra o padrão e depois troca?
Não. A resolução acontece no servidor e o HTML já sai segmentado na primeira pintura.

Publiquei uma audiência nova e um cliente logado não viu. Por quê?
O cookie de segmentos dele foi emitido antes da publicação e vale até 60 minutos. Ele passa a ver na expiração do cookie ou no próximo login.

Apaguei uma audiência no segmentador. O que acontece com os blocos que a usavam?
Nada quebra. Nenhum cliente casa com ela e os blocos passam a exibir a versão padrão. Vale limpar a configuração para não deixar variação órfã ocupando espaço no layout.

Um cliente que pertence a duas audiências configuradas vê o quê?
A primeira das duas na ordem configurada no bloco. As versões nunca são mescladas.

Funciona junto com layout exclusivo por URL?
Sim, e são independentes: primeiro a plataforma resolve qual layout vale para aquela URL, depois resolve qual versão de cada bloco vale para aquele cliente.

Consigo testar isso no ambiente local?
Consegue simular. Veja a seção de audiências em Design Studio Local.