Introdução
Blocos de conteúdo reutilizáveis que podem ser usados em várias páginas.
Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/blocks
🎯 O que este módulo faz?
O módulo Blocks permite que você recupere componentes de conteúdo reutilizáveis (blocos) — conjuntos de atributos que você cria uma vez no painel de administração e reutiliza em páginas e páginas de produtos: cabeçalhos, rodapés, banners, depoimentos, sliders e widgets de produtos/recomendações. Atualize um bloco uma vez e ele muda em todos os lugares onde é usado.
O SDK é somente leitura: você recupera blocos aqui e cria ou edita-os no painel de administração do OneEntry.
🚀 Início Rápido
Inicialize o módulo a partir de defineOneEntry:
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Recupere um único bloco pelo seu marcador e leia seus atributos:
// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");
console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true
// Custom fields live in attributeValues.
console.log(block.attributeValues);
✨ Conceitos Chave
O que é um Bloco?
Um bloco é um componente de conteúdo reutilizável que contém:
identifier— marcador único usado para referenciá-lo no código (sempre use o marcador; ele nunca muda)localizeInfos— dados localizados (por exemplo,title), conteúdo diferente por idiomatype— oBlockTypeque determina o que o bloco renderizaisVisible— flag de visibilidadeattributeValues— campos personalizados que você define via AttributesSets
Estrutura do Bloco
{
id: 3, // unique ID
localizeInfos: { // block localized data
title: 'Block', // block localized title
},
version: 0, // block version
position: 1, // block position in array of blocks
identifier: 'block', // block identifier (marker)
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
📋 O que Você Precisa Saber
- Referencie blocos pelo marcador (
identifier) no código — os marcadores nunca mudam. - Os blocos são criados no painel de administração. O SDK é somente leitura.
- Campos personalizados vêm de AttributesSets. Exemplos: um bloco de rodapé (copyright, links sociais, informações de contato), um banner hero (título, CTA, imagem de fundo), um depoimento (autor, foto, citação, avaliação).
- Blocos vs. Páginas. Uma página é um documento autônomo com uma URL (por exemplo,
/about) criado no módulo Pages; um bloco é um componente reutilizável que você insere em páginas.
📊 Tabela de Referência Rápida - Métodos Comuns
| Método | O que Faz | Quando Usar |
|---|---|---|
| getBlocks() | Obter todos os blocos (paginados, filtrados) | Listar todos os blocos disponíveis |
| getBlockByMarker() | Obter bloco pelo marcador | Recuperar bloco específico no código |
| searchBlock() | Pesquisar blocos | Recuperar blocos |
| getFrequentlyOrderedProducts() | Produtos frequentemente pedidos | "Frequentemente pedidos juntos" |
| getCartComplement() | "Complete seu carrinho" pelo contexto do carrinho | Venda cruzada a partir do carrinho |
| getCartComplementByProductIds() | "Complete seu carrinho" por productIds | Venda cruzada para produtos dados |
| getCartSimilar() | "Semelhante ao carrinho" pelo contexto do carrinho | Alternativas para itens do carrinho |
| getCartSimilarByProductIds() | "Semelhante ao carrinho" por productIds | Alternativas para produtos dados |
| getWishlistSimilar() | "Semelhante à lista de desejos" pela lista de desejos | Alternativas para itens da lista de desejos |
| getWishlistSimilarByProductIds() | "Semelhante à lista de desejos" por productIds | Alternativas para produtos dados |
| getPersonalRecommendations() | Recomendações pessoais | Feed de produtos personalizados |
| getRecentlyViewed() | Produtos visualizados recentemente | Widget "Visualizados recentemente" |
| getRepeatPurchase() | Produtos para compra repetida | Widget "Comprar novamente" |
| getTrending() | Produtos em alta | Widget "Tendências agora" |
| getSlides() | Árvore de slides do bloco slider | Renderizar um slider/carrossel |
🧩 Tipos de Blocos
O type de um bloco (o BlockType) determina o que ele renderiza. Além dos tipos básicos (common_block, product_block, similar_products_block, form, e outros), os seguintes tipos de blocos de produtos e personalização estão disponíveis:
| Tipo de bloco | Método |
|---|---|
frequently_ordered_block | getFrequentlyOrderedProducts() |
trending_block | getTrending() |
recently_viewed_block | getRecentlyViewed() |
repeat_purchase_block | getRepeatPurchase() |
slider_block | getSlides() |
personal_recommendations_block | getPersonalRecommendations() |
cart_complement_block | getCartComplement() / getCartComplementByProductIds() |
cart_similar_block | getCartSimilar() / getCartSimilarByProductIds() |
wishlist_similar_block | getWishlistSimilar() / getWishlistSimilarByProductIds() |
Os blocos de personalização (visualizados recentemente, compra repetida, recomendações pessoais, carrinho/lista de desejos) são impulsionados por atividade do usuário rastreada e funcionam tanto para usuários autorizados quanto para convidados (veja Modo convidado).
Fixando o preço (signPrice)
Os métodos de bloco de produtos e recomendações (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) aceitam um argumento opcional signPrice. Ele recebe o marcador de um armazenamento de pedidos e solicita ao servidor que bloqueie os preços dos produtos retornados por um tempo limitado, para que o preço que um cliente vê em um widget de recomendação seja o preço que ele paga no checkout.
signPrice— tipostringMarcador de armazenamento de pedidos para fixação de preço. Se o parâmetro estiver definido, o preço é fixado por um certo tempo.
- Nos métodos de recomendação,
signPriceé o último argumento posicional (apóslangCode). - Nas variantes
…ByProductIds(getCartSimilarByProductIds,getCartComplementByProductIds, …) é um campo dobodyda solicitação (body.signPrice).
Cada produto retornado carrega então um token signedPrice que codifica o preço bloqueado:
const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");
const signedPrice = products[0].signedPrice;
➡️ Reutilize esse token ao criar o pedido — veja a seção Preço fixo do produto (signedPrice) do módulo Orders. O mesmo parâmetro de fixação de preço também existe no módulo Products (em userQuery.signPrice).
❓ Perguntas Comuns (FAQ)
Qual é a diferença entre Blocos e Páginas?
- Páginas/Páginas de Produtos — páginas autônomas com URLs (por exemplo,
/about) criadas no módulo Pages, às quais você adiciona blocos e outros componentes. - Blocos — componentes reutilizáveis inseridos em páginas (por exemplo, um rodapé).
Pense em uma página como um documento completo e um bloco como um parágrafo que você reutiliza em documentos.
Como atualizo o conteúdo de um bloco?
Edite-o no painel de administração do OneEntry (seção Blocos). Todas as páginas que usam esse bloco são atualizadas automaticamente.
Devo criar muitos blocos pequenos ou poucos blocos grandes?
Prefira muitos blocos pequenos e focados (por exemplo, header_logo, footer_social_links) em vez de um grande bloco entire_page_layout — blocos pequenos são mais fáceis de reutilizar e manter.
Como mostro/ou escondo blocos condicionalmente?
Verifique o campo isVisible no bloco recuperado.
Como lido com blocos ausentes de forma elegante?
Envolva a recuperação em try/catch e renderize uma alternativa quando um bloco não for encontrado.
🎓 Melhores Práticas
- Crie blocos pequenos e focados (responsabilidade única).
- Use marcadores descritivos (
global_footer, nãoblock1); minúsculas com sublinhados. - Referencie blocos pelo marcador no código — os marcadores nunca mudam.
- Armazene blocos em cache — eles mudam raramente.
- Lide com blocos ausentes de forma elegante (try/catch).
🔗 Documentação Relacionada
- Módulo Pages - Gerencie páginas que usam blocos
- Módulo AttributesSets - Defina atributos de bloco
- Módulo Products - Use blocos em páginas de produtos
- Módulo User Activity - Impulsiona blocos de personalização