> For the complete documentation index, see [llms.txt](https://aiblue.gitbook.io/aiblue/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aiblue.gitbook.io/aiblue/documentation/integracoes-intermediarias/shopify.md). # Shopify ### Introdução: Uma Nova Era para a Customização na Shopify Este relatório transcende a função de um simples tutorial, apresentando uma análise técnica e estratégica completa sobre a implementação de scripts na plataforma Shopify. A customização de lojas, seja para aprimorar a experiência do cliente, integrar funcionalidades avançadas ou otimizar o desempenho, é uma necessidade fundamental para qualquer negócio online. No entanto, o ecossistema da Shopify está em constante evolução, e as abordagens de desenvolvimento que antes eram padrão estão sendo substituídas por soluções mais robustas e seguras. O presente guia abordará as duas metodologias predominantes para adicionar scripts – a abordagem moderna e segura, utilizando a arquitetura `Online Store 2.0` (OS 2.0), e a abordagem tradicional, que envolve a edição manual do código do tema. O ponto mais crítico abordado é o aviso de descontinuação do "Script Editor" e dos Shopify Scripts, com a transição completa para o ecossistema de Shopify Functions prevista para 30 de junho de 2026. Este anúncio fundamental sinaliza que a implementação de scripts não é mais uma decisão puramente técnica, mas uma escolha estratégica. O relatório irá desmistificar essa mudança, explicando o porquê da sua necessidade e como os comerciantes podem preparar sua loja para o futuro, garantindo performance e escalabilidade. O guia está estruturado para fornecer uma compreensão progressiva: a Parte I aborda as soluções imediatas com foco em segurança e desempenho, enquanto a Parte II discute o imperativo estratégico da migração para Shopify Functions. Ao final, o leitor terá em mãos um roteiro claro para a tomada de decisões informadas que irão não apenas resolver os desafios atuais, mas também posicionar a loja para um crescimento sustentável e resiliente a longo prazo. *** ### Parte I: Soluções Imediatas para Scripts e a Base da Estabilidade #### Capítulo 1: O Método Moderno e Seguro: Implementando Scripts via App Blocks e Embeds A Shopify tem incentivado a adoção de sua nova arquitetura de temas, conhecida como `Online Store 2.0` (OS 2.0). A base dessa arquitetura são os templates JSON e o conceito modular de "seções e blocos", que permitem a criação de layouts dinâmicos, personalizáveis e reutilizáveis, gerenciáveis diretamente pelo editor de temas. Essa abordagem contrasta drasticamente com a natureza mais rígida dos temas antigos, onde a customização exigia a edição manual de arquivos Liquid. Nesse novo paradigma, a Shopify introduziu dois mecanismos centrais para a integração de funcionalidades de aplicativos, que incluem a adição de scripts: `App Blocks` e `App Embeds`. * App Blocks: São componentes que permitem aos desenvolvedores empacotar a funcionalidade de um aplicativo em um bloco. O comerciante pode, então, adicionar esse bloco a qualquer seção compatível de uma página diretamente do editor de temas, sem a necessidade de tocar no código-fonte. Isso permite um controle granular sobre a localização da funcionalidade, seja em uma página de produto, no carrinho ou em qualquer outra seção que suporte blocos de aplicativos. * App Embeds: São uma alternativa para aplicativos que não possuem um componente de interface de usuário (UI) visível, como scripts de rastreamento ou de análise. Ao invés de um bloco visual, a funcionalidade é injetada automaticamente no código do tema, geralmente antes das tags de fechamento `` e ``. Os `App Embeds` funcionam em temas OS 2.0 e em temas mais antigos, pois não dependem de seções ou templates JSON para sua operação. A implementação de scripts via `App Blocks` ou `App Embeds` segue um processo simplificado, eliminando a barreira da edição de código para o comerciante. O processo é o seguinte: 1. Acessar o painel de administração da Shopify, navegar até `Online Store > Temas` e, ao lado do tema desejado, clicar em `Personalizar`. 2. Navegar até a página e a seção onde a funcionalidade deve ser adicionada. 3. Na barra lateral, clicar em `Adicionar bloco` e, na seção de aplicativos, selecionar o `App Block` desejado. Para scripts que funcionam como `App Embeds`, deve-se clicar no ícone de "App embeds" na barra lateral e ativá-lo. 4. Opcionalmente, o bloco pode ser arrastado para reposicionar a funcionalidade na página. Após a personalização das configurações, as alterações devem ser salvas. A principal vantagem deste método é a sua segurança e facilidade de manutenção. Ao dissociar a funcionalidade do script do código base do tema, as atualizações futuras do tema não irão quebrar a funcionalidade customizada, reduzindo a "dívida de suporte". Se um `App Block` falhar, é menos provável que ele comprometa a loja inteira. Essa abordagem segue o princípio de "anti-fragilidade", tornando a loja mais robusta e resiliente. #### Capítulo 2: O Método Legado e Seus Riscos: Edição Manual do Código Para lojas que ainda operam com temas mais antigos ou para a implementação de scripts que não estão disponíveis como `App Blocks` ou `App Embeds`, a edição manual do código do tema permanece uma opção. No entanto, esta abordagem acarreta riscos significativos e exige uma diligência extrema. O processo de edição manual de scripts tipicamente envolve a injeção de código JavaScript diretamente no arquivo `theme.liquid`, que é o arquivo de layout principal do tema. As instruções para essa tarefa são as seguintes: 1. Duplicar o Tema: Este passo é o mais importante e não negociável. Antes de realizar qualquer alteração, o tema deve ser duplicado para criar uma cópia de segurança. A ausência de um backup pode resultar na perda de todas as personalizações anteriores em caso de erro. A duplicação do tema pode ser feita no painel de administração, navegando até `Online Store > Temas`, clicando em `Ações` e selecionando `Duplicar`. 2. Acessar o Editor de Código: No painel de administração, deve-se navegar para `Online Store > Temas`, clicar em `Ações` e, em seguida, em `Editar Código`. 3. Injetar o Código: No editor de código, abrir o arquivo `theme.liquid`. O script customizado deve ser colado imediatamente acima da tag de fechamento ``. Uma prática recomendada é criar um novo arquivo na pasta `Snippets` (por exemplo, `powerreviews.liquid`) e carregar o código dentro do `theme.liquid` usando a tag de renderização Liquid: `{%- render 'nome-do-snippet' -%}`. A edição manual do código, no entanto, é perigosa e suscetível a erros. Um único caractere incorreto, como um ponto-e-vírgula ausente ou uma tag mal formatada, pode travar completamente o site, desabilitar funcionalidades cruciais como o botão "Adicionar ao Carrinho" e causar perda de receita. Além disso, o código que manipula o `Document Object Model` (DOM) é altamente vulnerável a quebras quando a Shopify atualiza a estrutura HTML dos temas. Essa dependência do DOM cria uma "dívida de suporte" contínua, exigindo que o comerciante ou desenvolvedor revise e atualize o código após cada atualização da plataforma. A decisão da Shopify de descontinuar o `checkout.liquid` para as etapas de pagamento é um precedente importante que demonstra a intenção da plataforma de mover toda a lógica de negócio crítica para um ambiente mais controlado e seguro, tornando a dependência de edições manuais cada vez mais inviável. #### Capítulo 3: Melhores Práticas Fundamentais para Performance e Estabilidade A implementação de scripts customizados requer um conhecimento aprofundado não apenas de onde colocar o código, mas também de como otimizá-lo para garantir o melhor desempenho e evitar conflitos. **Otimização de Carregamento de Scripts: A Escolha entre `async` e `defer`** O carregamento de scripts pode impactar significativamente a velocidade de renderização da página. Scripts "parser-blocking" (que bloqueiam o analisador) impedem a construção e renderização do DOM até que sejam totalmente carregados e executados, resultando em atrasos na experiência do usuário. Para mitigar esse problema, os atributos `async` e `defer` devem ser utilizados estrategicamente. Ambos os atributos permitem que o navegador baixe o script em segundo plano, sem bloquear a análise do HTML, mas o comportamento de execução é o que os diferencia. * `async`: Um script com o atributo `async` é executado imediatamente após ser baixado, independentemente de o HTML ter sido totalmente analisado. Isso pode causar problemas de dependência se o script tentar interagir com elementos do DOM que ainda não foram carregados. É ideal para scripts de terceiros que são independentes, como scripts de análise ( `analytics`) ou de publicidade, pois sua execução não é crítica para o funcionamento da página. * `defer`: Um script com o atributo `defer` também é baixado de forma assíncrona, mas sua execução é adiada até que a análise completa do HTML esteja finalizada. Essa abordagem garante que os scripts sejam executados na ordem em que aparecem no código e que o DOM esteja disponível para manipulação. É a escolha preferida para scripts que dependem de outros scripts ou da estrutura do DOM. A Tabela 1 a seguir sintetiza as diferenças e os casos de uso ideais para cada atributo, oferecendo uma referência rápida para o planejamento da implementação de scripts. | Característica | Carregamento Síncrono (Padrão) | `async` | `defer` | | ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- | | Download do Script | Bloqueia a análise do HTML | Assíncrono | Assíncrono | | Análise do HTML | Pausada até o script ser executado | Continua durante o download, pausada durante a execução | Continua durante o download, nunca é pausada pela execução | | Execução | Imediata, após o download | Imediata, após o download | Após a análise do HTML ser completada, na ordem em que aparecem | | Ordem de Execução | Sequencial | Indeterminada | Sequencial | | Casos de Uso Ideais | Scripts críticos que precisam ser executados antes do DOM estar pronto | Scripts de terceiros não essenciais e sem dependências | Scripts que interagem com o DOM e precisam da ordem de execução | Exportar para as Planilhas **Prevenção de Conflitos e Otimização do Código** Para evitar problemas de estabilidade, é crucial adotar práticas de desenvolvimento rigorosas. * Redução e Minimização de Código: O código JavaScript deve ser o mais leve possível, idealmente com um tamanho de 16 KB ou menos após a minificação. A introdução de frameworks de terceiros como jQuery, React ou Vue deve ser evitada, pois eles aumentam o tamanho do pacote e podem degradar a velocidade de carregamento. * Proteção do Namespace: A principal causa de conflitos entre scripts é a poluição do escopo global. Envolver o código em uma `Immediately Invoked Function Expression` (IIFE) é a melhor prática para criar um escopo de função isolado, prevenindo que variáveis e funções colidam com o código de outros aplicativos que também operam no escopo global. * Auditoria de Aplicativos: O uso de múltiplos aplicativos que executam funções semelhantes pode levar a conflitos de scripts e degradar a performance. Uma auditoria regular da loja para remover aplicativos e scripts desnecessários é uma prática recomendada para manter a estabilidade e a velocidade. * Remoção Condicional de Scripts: Uma técnica avançada para evitar a carga de scripts de aplicativos em páginas onde eles não são necessários é usar o filtro `remove` no Liquid. Por exemplo, é possível usar um `if` statement para verificar o `page.handle` e, se a condição for verdadeira, usar o filtro `remove` em `{{ content_for_header }}` para excluir o URL do script. Esta abordagem, embora tecnicamente sofisticada, demonstra o nível de esforço necessário para contornar a fragilidade do modelo legado. A obsessão da Shopify por performance, com a meta de `Functions` executando em menos de 5 ms, não é apenas uma diretriz técnica; é um pilar estratégico para garantir que as lojas tenham a melhor performance possível para aumentar as conversões e a receita. *** ### Parte II: O Imperativo Estratégico: A Mudança para Shopify Functions #### Capítulo 4: O Fim de uma Era: A Descontinuação dos Shopify Scripts O uso de Shopify Scripts e o "Script Editor" da Shopify estão sendo oficialmente descontinuados. A Shopify estabeleceu a data de 30 de junho de 2026 como o prazo final, após o qual os scripts legados não mais funcionarão. Esta mudança não é arbitrária, mas sim uma resposta às limitações inerentes à arquitetura de scripts original. As principais razões para a descontinuação incluem: * Performance Limitada: Os scripts legados, escritos em Ruby, operavam com restrições de desempenho e não eram escaláveis para lidar com eventos de alto tráfego, como flash sales, sem degradação de performance. Eles eram propensos a problemas de tempo limite e limites de memória da CPU. * Implantação Fragilizada: A instalação e a atualização de scripts eram um processo manual de copiar e colar código, o que era ineficiente e propenso a erros. Os desenvolvedores não podiam codificar e testar em seus ambientes locais, tornando o processo de desenvolvimento e distribuição mais complexo. * Compatibilidade Limitada: Os scripts de item de linha, por exemplo, não podiam acessar valores de descontos aplicados por `Functions` e só conseguiam reconhecer o primeiro código de desconto aplicado ao carrinho. Essa falta de interoperabilidade e a rigidez na ordem de execução limitavam a complexidade das lógicas de negócio que podiam ser implementadas. * Falta de Universalidade: Os Shopify Scripts eram uma funcionalidade exclusiva para o plano Shopify Plus, criando uma lacuna significativa de funcionalidade entre os planos. A descontinuação dos Scripts é uma peça em um quebra-cabeça maior: o movimento da Shopify em direção a uma arquitetura de back-end mais moderna e segura. Essa transição está alinhada com a iniciativa de `Checkout Extensibility`, que visa consolidar a lógica de negócio em um ambiente de execução robusto para garantir um futuro mais flexível e resiliente para a plataforma. Além disso, ao empacotar a funcionalidade em aplicativos, que podem ser disponibilizados para todos os planos, a Shopify democratiza a capacidade de lojas menores implementarem lógicas de negócio complexas sem a necessidade de desenvolvedores internos. #### Capítulo 5: O Futuro da Lógica de Negócios: Uma Análise de Shopify Functions Shopify Functions são a substituição moderna para os Shopify Scripts. Diferentemente dos scripts legados, os `Functions` são pequenos pedaços de código de back-end que rodam na infraestrutura da Shopify, processando dados de entrada para gerar resultados com base em eventos específicos. A lógica de negócio é empacotada em aplicativos e pode ser configurada diretamente na interface de administração da Shopify, eliminando a necessidade de edição manual de código do tema. **A Tecnologia por Trás: WebAssembly (Wasm)** A Shopify escolheu WebAssembly (Wasm) como a tecnologia subjacente para os `Functions` porque ela atende a três requisitos técnicos fundamentais: segurança, performance e flexibilidade. * Segurança: O código Wasm é executado em um ambiente isolado (`sandbox`), o que impede que o código acesse o sistema de arquivos ou a rede, a menos que explicitamente permitido. Isso protege a plataforma e a loja contra códigos maliciosos. * Performance: O Wasm é projetado para rodar com velocidade "quase nativa", permitindo que os `Functions` sejam executados em menos de 5 ms. Isso garante que a loja mantenha a performance mesmo sob picos de tráfego, como durante flash sales. O estudo de caso do aplicativo `Discount Kit` demonstrou que a migração para a API Wasm reduziu a contagem de instruções de execução em 30% e o tamanho do binário em 40%, resultando em um checkout mais rápido e confiável. * Flexibilidade: O Wasm é uma linguagem agnóstica. Isso significa que os desenvolvedores podem escrever a lógica em linguagens como Rust, AssemblyScript ou outras que compilam para Wasm, o que permite usar linguagens mais eficientes sem alterar o modelo de execução subjacente. Os Shopify Functions trazem um conjunto de `Function APIs` que permitem a customização de áreas-chave do comércio: * `Discount API` (Order, Product, Shipping): Permite a criação de lógicas de desconto complexas e flexíveis. * `Cart and Checkout Validation API`: Permite a aplicação de regras de validação para o carrinho e o checkout, como limites de quantidade ou `tokengated commerce`. * `Delivery Customization` e `Payment Customization`: Permitem a personalização das opções de entrega e pagamento, como ocultar métodos com base no valor do pedido ou nas preferências do cliente. * `Cart Transform API` (Beta): Permite a criação de pacotes de produtos (`bundles`) exibidos diretamente no checkout. A natureza de código fechado e as restrições de `Functions` (como a proibição de funções de relógio ou randomização) não são deficiências, mas escolhas de design deliberadas para manter a segurança e a determinabilidade do back-end da Shopify. A introdução de um `fetch target` permite uma comunicação segura e controlada com APIs externas. | Característica | Shopify Scripts | Shopify Functions | | ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Arquitetura | Código customizado em Ruby (principalmente) | Módulos WebAssembly (Wasm) | | Performance e Escalabilidade | Sinais de limitação de memória e tempo limite | Execução em menos de 5ms; construído para picos de tráfego | | Método de Implantação | Edição manual ou `Script Editor` | Empacotado em aplicativos, configurável via admin | | Áreas de Customização | Descontos de itens, envio, gateways de pagamento | Descontos, validação de carrinho/checkout, personalização de entrega/pagamento | | Requisitos do Desenvolvedor | Dependência de programação em Ruby; alto trabalho manual de implantação | Escreve em linguagens como Rust ou AssemblyScript; implantação facilitada pela Shopify CLI | | Suporte Futuro | Descontinuado em 30 de junho de 2026 | Ativamente suportado e em evolução | A Tabela 2 compara as duas tecnologias, destacando o porquê de a migração não ser apenas uma obrigação, mas uma oportunidade estratégica. #### Capítulo 6: O Roteiro Estratégico para Migração e o Futuro da Sua Loja A Shopify está oferecendo aos comerciantes um caminho claro para a transição. A capacidade de scripts legados e `Functions` coexistirem na mesma loja por um período é uma decisão estratégica da plataforma, que visa evitar uma migração de "tudo ou nada" e permitir que os comerciantes testem e migrem gradualmente com menos risco. **Passo 1: Avalie e Planeje (A Auditoria de Scripts)** O ponto de partida oficial para a transição é o "Shopify Scripts customizations report". Este é um relatório personalizado no painel de administração da Shopify que lista todos os scripts ativos na loja e sua funcionalidade. Este relatório serve como uma ferramenta proativa, fornecendo um roteiro para a migração e links relevantes para documentação e aplicativos. O comerciante deve revisar o relatório para identificar quais scripts são essenciais e precisam ser recriados com `Functions`. **Passo 2: Escolha o Seu Caminho de Migração** Após a auditoria, o comerciante pode escolher entre dois caminhos principais para a migração: * Caminho A: Usar um App Existente: Para lógicas de negócio comuns, como descontos escalonados ou validações de carrinho, a solução mais simples é instalar um aplicativo já construído com Shopify Functions. O relatório de customizações da Shopify já sugere aplicativos compatíveis, tornando esta rota a mais rápida e segura para muitas lojas. * Caminho B: Construir uma Solução Customizada: Para lógicas de negócio únicas que não são atendidas por aplicativos existentes, será necessário construir uma solução customizada. Esta rota requer conhecimento técnico (Rust, AssemblyScript) e o uso da Shopify CLI para desenvolver e implantar o aplicativo customizado. É importante notar que aplicativos customizados com `Functions` devem ser criados através do Partner Dashboard, não diretamente do admin da loja. **Desafios Comuns e Limitações a Considerar** Embora os `Functions` sejam mais robustos, eles apresentam desafios de desenvolvimento específicos que devem ser considerados: * Ordem de Execução: É crucial entender como os `Scripts` e `Functions` interagem durante a coexistência. Scripts de item de linha, por exemplo, executam antes dos `Functions` de desconto. Já scripts de envio e pagamento executam após os `Functions` de customização de entrega e pagamento. Essa interação detalhada é vital para evitar comportamentos inesperados. * Limitações de Recursos: `Functions` operam com limites fixos (por exemplo, 256 kB para o binário compilado) e dinâmicos (contagem de instruções de execução) para garantir a performance da plataforma. Lógicas de negócio muito complexas podem precisar ser divididas em múltiplos `Functions` para evitar erros de limite de instrução. * Acesso à Rede: Diferente de outros ambientes, `Functions` têm acesso limitado à rede para garantir a segurança. Para acessar dados externos, é necessário utilizar o conceito de "fetch target", onde a Shopify faz a chamada HTTP em nome do `Function` e disponibiliza o resultado. A impossibilidade de usar funções não determinísticas como randomização ou relógio é uma escolha de design deliberada para manter a previsibilidade. ### Conclusão: Recomendação de Especialista para uma Loja Resiliente e Preparada para o Futuro A Shopify está se movendo em direção a um ecossistema mais seguro, mais rápido e mais escalável. A descontinuação dos scripts legados é um passo fundamental nessa evolução, e a migração para Shopify Functions não é apenas uma obrigação, mas uma oportunidade estratégica para os comerciantes. A recomendação para uma loja que busca resiliência e crescimento a longo prazo é clara: * Curto Prazo: Para a implementação imediata de scripts, evite a edição manual do código do tema sempre que possível. Opte por soluções via `App Blocks` e `App Embeds`, que são mais seguras, fáceis de gerenciar e resistentes a futuras atualizações do tema. Para scripts legados existentes, faça um backup completo, otimize o código com `async`/`defer` e, se necessário, use filtros Liquid para carregamento condicional. * Médio Prazo: Comece o planejamento da migração para Shopify Functions imediatamente, utilizando o "Shopify Scripts customizations report" como ponto de partida. Para funcionalidades de negócio comuns, a via mais rápida e segura é a instalação de aplicativos já construídos sobre `Functions`. Para lógicas de negócio únicas, inicie o planejamento de uma solução customizada. * Longo Prazo: Abrace a arquitetura moderna da Shopify. Ao mover a lógica de back-end para um ambiente de execução seguro e performático como os `Functions` e a lógica de front-end para componentes modulares como os `App Blocks`, a loja estará posicionada para prosperar com o ecossistema Shopify moderno, garantindo desempenho superior, confiabilidade e prontidão para o crescimento e eventos de alta demanda.