Skip to content

Contrato de importação e execução ​

O fluxo profissional usa o mesmo ThemeStorage, validador e metadados de revisões. O ZIP deve conter os arquivos diretamente na raiz, sem pasta envolvente. Aceita ZIP clássico sem criptografia, com entradas armazenadas ou Deflate; não aceita ZIP64, arquivos divididos, links, caminhos duplicados, absolutos ou traversal. Limites: 30 MiB de ZIP, 60 MiB descompactados, 12 MiB por arquivo e 500 entradas, incluindo diretórios. CRC, cabeçalhos e limites de expansão são verificados em memória antes de qualquer gravação; nenhum arquivo é extraído no filesystem.

A API de importação recebe application/zip, com expectedThemeRevision e baseThemeRevision na query. A identidade da loja vem exclusivamente da autenticação. JSON, Liquid, referências e fontes comerciais passam pelas mesmas validações do sistema. Templates e components ainda não utilizados também são validados e preservados na leitura, exportação e publicação.

O arquivo assets/theme.js do pacote importado deve ser idêntico ao da revisão-base. Scripts adicionais literais em Liquid são aceitos e identificados pelo editor, conforme o contrato abaixo. O layout pode manter a chamada canônica <script src="{{ theme.assets.js }}" defer></script>. CSS, templates, sections, components, imagens e estrutura Liquid podem ser editados externamente. Essa é uma restrição de execução, sem opções visuais ou schemas de layout.

Códigos personalizados ​

A seleção Onde aplicar? aparece somente ao adicionar um novo script: site inteiro, categoria específica ou página específica. Para scripts existentes, a interface oferece Editar ou Remover e envia alcance keep automaticamente, preservando suas condições. Remover com IA prepara a exclusão no rascunho sem exigir digitação de um pedido. Para restringir o alcance, use condições Liquid externas à tag script em layout.liquid, onde os objetos comerciais estão disponíveis. Components chamados com render têm contexto isolado: não suponha que recebam page, category ou product sem argumentos explícitos. Use page.type combinado com category.url, product.url ou page.slug para páginas institucionais (page.type == 'static'). Não use page.url, que não integra esse contexto. Condições de categoria incluem paginações e filtros, sem incluir categorias filhas automaticamente. Mover um script exige remover a inclusão anterior para evitar duplicação; não mude os demais scripts. A seleção é validada e também define a página da prévia; não cria cadastro paralelo.

O editor extrai scripts literais dos arquivos Liquid efetivos do tema, incluindo alterações do rascunho e trechos recebidos por ZIP. A IA identifica sua finalidade, nomeia os itens, explica o comportamento e informa o alcance. A análise recebe todos os arquivos textuais atuais (Liquid, JSON, CSS e JavaScript), incluindo manifesto, templates, components e rascunho, para seguir condições e referências entre arquivos. Quando o alcance não puder ser determinado, deve informar Aplicação não identificada. Ao pedir uma alteração, o mesmo fluxo de patches usado por cores e textos edita os arquivos originais. Nenhum cadastro prévio é necessário. A análise não executa o script nem garante a identificação do fornecedor; se a IA não conseguir descrevê-lo, o arquivo continua disponível.

Somente scripts literais do bundle recebem autorização de execução. Scripts montados por expressões Liquid ou provenientes do catálogo continuam proibidos. assets/theme.js é técnico e permanece protegido; cole códigos adicionais em layout.liquid, sections ou components existentes. Checkout, confirmação e conta não executam esses scripts adicionais. Depois de aplicar, confira e publique.

O arquivo opcional custom-codes.json permanece suportado para compatibilidade com revisões anteriores; não é necessário para a descoberta. Sua estrutura é:

json
{
  "version": 1,
  "codes": [
    {
      "id": "chat",
      "name": "Chat de atendimento",
      "position": "body",
      "enabled": true,
      "kind": "html",
      "code": "<script src=\"https://chat.example/widget.js\" async></script>"
    }
  ]
}

position aceita head (antes de </head>) ou body (antes de </body>). kind aceita javascript (JavaScript clássico, sem tags) ou html. IDs são únicos, com até 64 caracteres, usando letras minúsculas, números, hífen e underscore; o primeiro caractere deve ser alfanumérico. Nomes têm até 100 caracteres. São aceitos até 30 itens, 20 mil caracteres por código e 40 mil caracteres de código no conjunto. O objeto não aceita outras chaves. Uma lista vazia remove todos os códigos daquela revisão.

HTML admite script, style, meta, link, noscript, div, span, p, a, img e br. No cabeçalho, somente script, style, meta e link. URLs devem ser HTTPS absolutas e sem credenciais. Não aceita atributos on*, nonce, http-equiv, iframe nem módulos JavaScript. Scripts aceitam os tipos clássicos e application/ld+json; JavaScript e JSON-LD são verificados antes de ativar. A validação de sintaxe não atesta a segurança nem o funcionamento de um serviço externo. Não incluir segredos ou dados privados.

O Node insere os itens ativos depois de renderizar e validar o Liquid, com nonce da renderização. O código não é interpretado como Liquid e não recebe objetos comerciais do servidor. Scripts executam na vitrine e podem acessar seu DOM; não são um sandbox de dados do comprador. Checkout, confirmação e conta do comprador não recebem códigos personalizados. A prévia usa iframe e cabeçalho CSP sandbox sem allow-same-origin, inclusive quando sua URL é aberta diretamente. Serviços dependentes de cookies, origem ou domínio real podem não funcionar nela. Códigos que usam eval continuam incompatíveis com a política de execução.

O editor oferece Códigos personalizados nas ações rápidas e no menu Mais opções. A tela analisa os scripts do tema ao abrir e permite pedir inclusão, alteração ou remoção com IA. Não há escolha de armazenamento: as alterações ficam sempre no tema atual, precisam ser conferidas no rascunho e publicadas. O código encontrado fica recolhido em detalhes; o alcance aparece junto ao nome do script. Pedidos pendentes são protegidos ao fechar. O chat principal também pode editar custom-codes.json por patch quando já existir nesse formato; para novos scripts do tema, prefira o arquivo Liquid adequado.

A compatibilidade técnica com códigos gerais existentes é independente das revisões do tema; o modal não consulta nem grava essa configuração. Não há conversão automática de scripts V2.

A política de execução tem três camadas compartilhadas:

  • A importação inspeciona HTML/SVG com o parser de sanitize-html, incluindo entidades em URLs e namespaces SVG. SVG exige UTF-8 válido, sem bytes nulos. Também avalia expressões Liquid constantes em todos os ramos, inclusive echo, com limites de tempo/memória. Scripts literais do bundle são validados separadamente; scripts construídos dinamicamente permanecem proibidos. Não aceita atributos de eventos, documentos embutidos, URLs executáveis, XML com entidades/folhas externas ou animação SVG que possa alterar atributos executáveis.
  • O ThemeEngine inspeciona o documento completo depois de resolver Liquid, componentes, concatenações e dados. Uma condição dependente de produto ou página não é considerada segura por não ter sido visitada na importação: cada renderização real passa pela verificação, tanto em preview quanto na loja publicada. Conteúdo executável causa erro antes de enviar HTML; não é removido silenciosamente. HTML legítimo via raw, SVG estático, classes, estilos e hooks permanecem disponíveis.
  • O navegador recebe CSP com nonce aleatório por documento, script-src-attr 'none', object-src 'none' e base-uri 'none', sem unsafe-inline/unsafe-eval. A política HTTP preserva frame-ancestors da preview; uma meta anterior a todo o conteúdo do tema protege também consumidores do HTML fora dessas rotas. O nonce não integra o contexto Liquid. Somente a plataforma o aplica ao entrypoint original do tema, ao runtime, à ponte da preview e aos códigos personalizados explicitamente habilitados. strict-dynamic permite scripts carregados pelo runtime confiável, como o SDK de pagamento. Scripts adicionais literais recebem nonce somente após validação do trecho original; conteúdo executável vindo de dados não recebe autorização. HTML usa private, no-store.

A verificação estática não procura prever todos os valores comerciais possíveis. Uma expressão dependente de dados pode ser aceita no rascunho e recusada quando produzir conteúdo executável. Essa recusa nunca ativa a revisão nem retorna o HTML inseguro. Pacotes e rascunhos seguem a publicação manual existente.

O contrato do navegador segue a especificação CSP. A homologação de integrações e navegadores deve conferir essa política; não se deve relaxá-la com unsafe-inline ou autorizar automaticamente scripts encontrados no HTML.

Temas V3 · Liquid estrutura, CSS desenha, JSON compõe.