Documentação do Product Page Pro & SEO

Instalação

Requisitos

Magento 2.4.x. PHP 8.1–8.5. Funciona com Hyvä (qualquer tema filho) e Luma (o tema Magento por defeito) — o tema ativo é detetado automaticamente, sem necessidade de configuração. Em qualquer outro tema o módulo não tem qualquer efeito (nenhuma ação, como se estivesse desativado).

Passos de instalação

1. Adiciona as credenciais que vais receber por email a auth.json na raiz do teu projeto Magento:

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-ppps
4. bin/magento module:enable Codingrow_Ppps
5. bin/magento setup:upgrade && bin/magento setup:di:compile
6. Cola a tua chave de licença em Admin → Stores → Configuration → Codingrow Extensions → Product Page Pro & SEO → License → License Key, guarda, depois bin/magento cache:flush.
7. bin/magento setup:static-content:deploy -f (em modo production).

Não é necessário nenhum passo de build Tailwind nem configuração do tema: cada regra de layout crítica (proporções da grelha, posicionamento fixo, breakpoints) é CSS puro incluído nos próprios templates do módulo, não classes utilitárias Tailwind.

Configuração

Cinco interruptores independentes em Stores → Configuration → Codingrow Extensions → Product Page Pro & SEO → General:

• Enable column gallery on desktop — grelha de imagens em 2 colunas em vez de uma imagem de cada vez.
• Enable sticky buy-box on desktop — no Hyvä, tanto as imagens como a coluna de preço tornam-se fixas (a naturalmente mais curta permanece fixa em vista enquanto a outra desliza); a descrição move-se para debaixo da galeria, e esta definição desbloqueia as duas seguintes. No Luma, apenas a coluna de preço/compra permanece fixa durante o scroll.
• Enable repeated image strip below description — requer a definição sticky buy-box acima. Mostra novamente todas as imagens do produto numa linha que se ajusta.
• Enable simplified section titles — remove o nome do produto repetido junto a títulos como "Description" (apenas Hyvä).
• Enable product SEO structured data — adiciona um bloco JSON-LD schema.org/Product (nome, imagem, marca, GTIN, preço, disponibilidade) para os rich results do Google, e preenche uma meta description para os produtos que não têm nenhuma. Não visual; Hyvä e Luma, tanto desktop como móvel; nunca substitui uma meta description existente.

Todas as cinco requerem uma licença válida; sem ela, o módulo comporta-se como se estivesse completamente desativado (layout predefinido do tema inalterado, nenhum erro mostrado aos visitantes da loja).

Desinstalação

composer remove codingrow/module-ppps depois bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.

Guia do utilizador

Galeria em colunas

No desktop (a partir de 1024px), todas as imagens do produto são mostradas de uma vez numa grelha de 2 colunas em vez da imagem única mais faixa de miniaturas do Hyvä ou do slider Fotorama do Luma. O telemóvel nunca é afetado — mantém sempre o comportamento nativo da galeria do tema (imagem única, faixa de miniaturas deslizável por baixo).

No Hyvä, isto é implementado como um bloco adicional dentro do próprio componente de galeria Alpine.js do tema, reutilizando os mesmos dados de imagem já carregados para a galeria predefinida — sem estado JavaScript duplicado. No Luma, a grelha é adicionada junto ao widget Fotorama nativo (nunca modificado ou reinicializado); os dois são alternados com CSS puro no breakpoint desktop.

Coluna de preço fixa

No Hyvä: tanto a coluna de imagens como a coluna de preço/compra tornam-se position: sticky — a naturalmente mais curta (normalmente a coluna de preço, já que a coluna de imagens+descrição é normalmente mais alta) permanece fixa em vista enquanto a outra desliza. A descrição move-se da sua posição predefinida (sob ambas as colunas) diretamente para debaixo das imagens, dentro dessa mesma coluna esquerda.

No Luma: apenas a coluna de preço/compra permanece visualmente fixa enquanto fazes scroll, entre o cabeçalho e o final da secção de informação do produto — a coluna de imagens e descrição desliza sempre normalmente. Isto é implementado em JavaScript (transform: translateY(), recalculado a cada scroll) em vez de CSS position: sticky, já que o posicionamento fixo revelou-se pouco fiável combinado com o layout nativo de duas colunas baseado em floats do Luma. A descrição também é reposicionada diretamente para debaixo das imagens (por defeito o Luma coloca-a a toda a largura sob ambas as colunas).

Faixa de imagens repetida

Requer a definição sticky buy-box. Debaixo da descrição, todas as imagens do produto são mostradas novamente em tamanho fixo (274×274px), reorganizando-se naturalmente à medida que o ecrã fica mais estreito — 3 por linha numa largura desktop típica, cada vez menos por linha à medida que fica mais estreito, até 1 por linha no telemóvel. As imagens só encolhem abaixo do seu tamanho fixo quando nem sequer uma única já cabe na largura disponível.

Títulos de secção simplificados

O tema predefinido do Hyvä mostra "Description / Nome do Produto" como título acima do separador de descrição — redundante assim que o nome do produto já está em destaque noutro local numa página reorganizada. Esta definição substitui-o por um título simples "Description". Os próprios separadores do Luma nunca tiveram esta repetição, pelo que a definição não tem efeito visível aí.

Dados estruturados SEO do produto

Independente de tudo o que foi descrito acima, e não é uma alteração visual. Quando ativado, cada página de produto recebe um bloco JSON-LD schema.org/Product que descreve o produto — nome, imagem, marca, GTIN/EAN, e uma Offer com preço, moeda, disponibilidade e estado do artigo — para que os motores de busca possam gerar rich results (preço e disponibilidade na SERP, elegibilidade para as listagens de produtos gratuitas do Google). Cada campo é preenchido na medida do possível: aquilo que o produto não tem é simplesmente omitido, nunca um erro, e o bloco é emitido da mesma forma no Hyvä e no Luma, tanto no desktop como no móvel.

A mesma definição também preenche uma meta description para os produtos que não têm uma própria — construída a partir da descrição curta/longa do produto (ou do seu nome como último recurso). Nunca mexe num produto que já tenha uma meta description, pelo que só preenche uma lacuna.

Fichas de comerciante: devoluções e envio

O Google lê da página do produto as condições de devolução e de envio para mostrá-las nas suas fichas de comerciante gratuitas, e o Search Console as aponta como ausentes quando não estão lá. Não dá para deduzi-las do catálogo — são condições comerciais — então são declaradas na configuração, em Merchant listings (returns and shipping). Os dois blocos vêm desligados e exigem os dados estruturados do produto ativos.

• Condições de devolução → hasMerchantReturnPolicy: países (escolhidos na lista do Magento), prazo de devolução, dias, como a mercadoria volta, quem paga e o custo quando houver.
• Condições de envio → shippingDetails: países atendidos, custo (0 para envio gratuito), prazos de preparação e entrega em dias úteis.

Duas regras são propositais. Um bloco com campos obrigatórios incompletos é descartado inteiro em vez de publicado pela metade: o Google compara o que você declara com o que o cliente encontra no seu site, então uma declaração errada vale menos do que uma ausente. E com "devoluções não aceitas" não se publica nem o método nem quem paga: não há devolução a descrever.

A oferta traz também validFrom, a data a partir da qual o preço publicado vale: o início do preço especial quando existe, caso contrário a data de criação do produto. Essa não precisa de configuração.

Quase nunca essas condições valem para o catálogo inteiro: os prazos de preparação e entrega mudam entre estoque próprio e dropshipping, o envio depende do volume, o prazo de devolução do que se vende. E o número normalmente já existe no produto, num atributo que o seu importador ou a sua equipe preenche. Por isso cada um desses campos pode apontar para um atributo do produto — a lista inclui os personalizados — com uma caixa para digitar um código que a lista não oferece. Onde o produto tem um valor, vence ele; onde não tem, fica o valor fixo; e um valor que não é um número recai no fixo em vez de publicar um absurdo.

Cada número pode vir de um atributo do produto, escolhido na lista do catálogo: aqui os prazos de preparação e entrega vêm dos atributos que um importador preenche.

Suporte Hyvä e Luma

O tema ativo é detetado automaticamente (sem necessidade de configuração) percorrendo a cadeia de temas superiores do tema atual à procura de "Hyva" ou "Luma" no código do tema. Em qualquer tema que não seja descendente de Hyvä ou Luma, todos os plugins deste módulo são garantidamente inócuos — a página é renderizada exatamente como sem o módulo instalado, nunca um erro.

Licença

Uma chave de licença por domínio Magento, inserida em Stores → Configuration → Codingrow Extensions → Product Page Pro & SEO → License → License Key. A chave é verificada pelo módulo, e a sua loja não depende dos nossos servidores para funcionar: uma falha nossa não a pára. Mudar para um novo domínio requer uma nova chave — contacta o suporte com os detalhes da tua compra original. A sua licença cobre a versão atual mais 1 ano de atualizações e assistência: as versões publicadas dentro desse ano ficam suas para sempre, e para instalar as posteriores renova o suporte (−35%). Para mudar de domínio: a primeira mudança é gratuita e imediata na sua área de cliente, depois uma por ano.