Magento/Adobe Commerce no enterprise de moda
Magento (rebranded como Adobe Commerce após a aquisição pela Adobe) é a plataforma escolhida por marcas grandes e enterprises de moda no Brasil e no mundo. Operações de catálogo amplo, com múltiplos sites por canal, integrações ERP/PIM/OMS e times técnicos dedicados encontram em Magento a flexibilidade necessária.
A complexidade tem um preço: cada modificação no storefront requer atenção a Layout XML, módulos, escopos (default, store view, website) e cache. Adicionar um script de terceiros não é apenas colar uma tag: é entender onde inserir, como persistir entre deploys e como evitar cache stale.
Este guia cobre integração do Provou em Magento 2.4+ e Adobe Commerce 2.4+. Os caminhos descritos funcionam em ambas as edições (Open Source e Commerce). O foco é técnico: assume que você está confortável com Magento Layout XML, módulos custom e CLI.
Antes de começar
- Magento 2.4+ ou Adobe Commerce 2.4+ instalado.
- Acesso SSH ao servidor (ou ambiente onde se faz deploy).
- Magento CLI (
bin/magento) disponível. - Cadastro Provou ativo (use o cadastro gratuito, 14 dias sem cartão).
- Slug da loja no painel Provou.
- Tabela de medidas em CSV ou conexão à REST API.
- Conhecimento de cache layers ativos (default, Varnish, Redis, Cloudflare).
Tempo estimado: 30 a 60 minutos para integração robusta com módulo dedicado.
Onde inserir o script: Layout XML
A forma canônica em Magento 2 é criar um módulo dedicado que injeta o script via Layout XML. Não edite vendor/magento/* diretamente.
Crie um módulo simples:
`` app/code/SeuVendor/Provou/ ├── etc/module.xml ├── registration.php └── view/frontend/layout/default.xml ``
registration.php:
``php <?php \Magento\Framework\Component\ComponentRegistrar::register( \Magento\Framework\Component\ComponentRegistrar::MODULE, 'SeuVendor_Provou', __DIR__ ); ``
etc/module.xml:
``xml <?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd"> <module name="SeuVendor_Provou" setup_version="1.0.0"/> </config> ``
view/frontend/layout/default.xml:
``xml <?xml version="1.0"?> <page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"> <head> <script src="https://cdn.provou.app.br/v1.js" src_type="url" async="true"/> </head> </page> ``
Em seguida:
``bash bin/magento module:enable SeuVendor_Provou bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``
O data-store precisa ser injetado como atributo. Magento Layout XML não suporta data-* arbitrário em <script> diretamente. Alternativa: injete via bloco template com phtml customizado.
default.xml vs default_head_blocks.xml
default.xml cobre todas as páginas. default_head_blocks.xml cobre só as que herdam dele (na maioria das instalações, todas). Para lojas que querem inserir só em PDPs, use catalog_product_view.xml.
Alternativa: header.phtml customizado
Para incluir atributos data-* (como data-store), o caminho mais limpo é via template phtml:
view/frontend/templates/provou.phtml:
``php <script src="https://cdn.provou.app.br/v1.js" data-store="<?= $block->escapeHtmlAttr('sua-loja') ?>" async></script> ``
view/frontend/layout/default.xml:
``xml <page> <head> <block class="Magento\Framework\View\Element\Template" name="provou.script" template="SeuVendor_Provou::provou.phtml"/> </head> </page> ``
PDP customizadas (catalog_product_view)
Se sua loja tem PDPs altamente customizadas (Hyvä Theme, PWA Studio, custom front), o widget detecta automaticamente o seletor de variantes Magento padrão. Em PDPs com bibliotecas de variantes customizadas, ajuste o ponto de ancoragem:
``xml <referenceBlock name="product.info.options.wrapper"> <block class="Magento\Framework\View\Element\Template" name="provou.anchor" template="SeuVendor_Provou::anchor.phtml" after="-"/> </referenceBlock> ``
Em anchor.phtml:
``php <div data-provou-anchor="provador"></div> ``
E configure anchor: provador no painel Provou.
Importação de tabelas via API
Magento expõe REST API e GraphQL. O Provou aceita:
- REST API (
/rest/V1/products): gere um Integration token no admin (System > Extensions > Integrations) com permissão de leitura de catálogo. Forneça ao Provou. - GraphQL: mais eficiente para enterprise com catálogos enormes. Endpoint
/graphql. - CSV via System > Import: caminho rápido para validação inicial.
A sincronização inicial em catálogos enterprise (50k+ SKUs) pode levar de 30 minutos a 2 horas. Use modo incremental para atualizações subsequentes.
Para padronizar a tabela antes de importar, consulte o guia de tabela de medidas.
Cache e Varnish
Magento usa cache em múltiplas camadas: Block Cache, Full Page Cache (FPC), Varnish (em produção), e CDN externa (Cloudflare, Fastly).
Após instalar o módulo:
``bash bin/magento cache:clean bin/magento cache:flush varnishadm 'ban req.url ~ /' # ou via VCL ``
Em produção com Varnish, o script externo v1.js não passa pelo Varnish (servido por CDN do Provou diretamente). O HTML que contém a tag <script> passa pelo FPC, então qualquer alteração de layout requer flush.
Para evitar reaplica de cache em cada deploy, use o cache warmer (Magento_PageCache + jobs cron de warming).
Developer mode e como testar
Em ambiente de homologação, ative developer mode:
``bash bin/magento deploy:mode:set developer ``
Isso desativa cache de layout e permite ver alterações em XML imediatamente. Em produção, sempre rode em production mode.
Para testar:
- Aplique o módulo em ambiente de staging.
- Valide PDPs em desktop e mobile.
- Verifique DevTools > Network:
v1.jscarrega 200 OK. - Verifique painel Provou: eventos chegam.
- Promova para produção via deploy padrão (composer + setup:upgrade + di:compile + flush).
Boas práticas enterprise
- Sempre use módulo dedicado em
app/code/SeuVendor/Provou. Edição de tema base ou devendor/é receita para conflito em updates. - Versione o módulo no Git. Reuso entre stores do mesmo grupo.
- Configure escopos diferentes (default, store view) se a operação tem múltiplos sites com slugs diferentes do Provou.
- Monitore tempo de hidratação via New Relic, Datadog ou Magento APM. O Provou não deve impactar TTFB nem hidratação. Em testes, score Lighthouse não muda.
- Documente o módulo no Confluence/wiki interno do time.
- Use feature flag para liga/desliga por escopo se a operação requer rollback rápido.
Para começar, faça o cadastro gratuito, copie o slug, crie o módulo e deploy em staging. Em uma tarde a operação enterprise está com Provou rodando.
Para outras plataformas com perfil enterprise, leia o guia de VTEX. Para storefronts headless e PWA, veja o post sobre storefronts custom. Para o panorama completo, navegue pelo blog.
Multi-store, escopos e governança em Magento
Magento brilha em operações multi-bandeira, multi-país, multi-canal. Para essas operações, a integração do Provou requer atenção a escopos:
Escopos disponíveis: default (fallback), website, store, store view. Cada nível pode ter configuração distinta.
Múltiplos slugs Provou por escopo: se sua operação tem várias bandeiras com tabelas de medidas distintas (ex.: marca premium e marca economy), configure slugs diferentes por escopo. No template phtml:
``php <?php $slug = $this->_scopeConfig->getValue( 'provou/general/slug', \\Magento\\Store\\Model\\ScopeInterface::SCOPE_STORE ); ?> <script src="https://cdn.provou.app.br/v1.js" data-store="<?= $block->escapeHtmlAttr($slug) ?>" async></script> ``
Configure os valores em Stores > Configuration > Provou > General > Slug com escopo apropriado.
Governança via System Config: para times técnicos disciplinados, exponha campos de configuração em etc/adminhtml/system.xml (slug, ativar/desativar, debug mode). Isso evita edição direta de código por marketing.
Webhooks de catálogo: em catálogos enterprise (50k+ SKUs), use catalog_product_save_after para enviar atualizações ao Provou em tempo quase real. Em volumes maiores, prefira sincronização batch noturna.
Métricas e analytics em Magento
A medição em Magento integra-se a Adobe Analytics, GA4 ou data warehouses corporativos (Snowflake, BigQuery via ETL). O Provou emite eventos client-side que você captura via JavaScript ou via Tag Manager.
KPIs primários:
- Taxa de abertura do widget: 10% a 18% da PDP em moda.
- Completude: 70% a 85% dos que abriram.
- Aplicação da recomendação: 65% a 80%.
- Lift de conversão: +2 a +4 pp para usuários do widget vs não usuários.
- Redução de devoluções por tamanho: -25% a -42% em 60 a 90 dias.
Em operações enterprise, conecte os eventos ao seu BI corporativo para cruzar com cohort de cliente, CLV, retorno e canal de aquisição. O Provou expõe API REST para export de eventos agregados (mais detalhes no painel).
Para o framework financeiro de defesa de investimento, leia o guia de ROI passo a passo. Para o playbook operacional de redução, veja reduzir devoluções em 90 dias.
Para começar, faça o cadastro gratuito, crie o módulo SeuVendor_Provou em ambiente de staging e valide. Em uma sprint, está em produção.
Roadmap de implementação para enterprise
Enterprises Magento normalmente seguem um roadmap em três fases.
Fase 1 - Discovery e POC (2 semanas). Time técnico cria módulo SeuVendor_Provou em ambiente de desenvolvimento. Validar integração com Layout XML, sincronização via REST API ou GraphQL, escopo de configuração. POC valida que a recomendação funciona em PDPs reais com SKUs reais.
Fase 2 - Pilot e UAT (3-4 semanas). Subir o módulo em staging com cópia do catálogo de produção. Time de QA roda casos de teste end-to-end (Playwright, Cypress) cobrindo PDP padrão, PDP customizada, variantes complexas, mobile, acessibilidade. Marketing aprova UI. Compliance valida LGPD (veja guia LGPD aplicado).
Fase 3 - Production rollout (2-3 semanas). Deploy gradual: feature flag liga widget para 5% do tráfego, depois 25%, 50%, 100%. Monitoramento via APM (Datadog, New Relic) confirma zero impacto em LCP, INP e CLS. Em uma sprint adicional, rede de eventos é integrada ao data warehouse corporativo.
O ciclo total típico é de 6 a 9 semanas, contando aprovações internas. Para times técnicos disciplinados, a integração escala bem.
Boas práticas finais
- Versione o módulo no monorepo da empresa, não em repositório separado.
- Configure escopos por bandeira se a operação é multi-store.
- Documente a integração no Confluence/wiki interno com snippet, fluxo de eventos, contatos.
- Crie alertas no APM para queda anômala de
recommendation_computed. - Mantenha contrato de DPA com o Provou conforme exigência de compliance enterprise.
Para perfis SaaS mais simples, leia os guias de Shopify, VTEX e WooCommerce.
Magento entrega a flexibilidade enterprise. Provou entrega a recomendação de tamanho. A integração via módulo dedicado preserva a governança que enterprises exigem e segue boas práticas Magento de cabo a rabo.