Como personalizar o painel Jumpseller com o Tampermonkey

O Tampermonkey é uma extensão de navegador de terceiros que executa scripts de utilizador: pequenos programas que podem alterar a apresentação ou o comportamento de uma página no seu navegador. Um script revisto pode destacar informação útil ou acrescentar um resumo visual ao painel de administração do Jumpseller.

Não precisa de escrever código para utilizar o exemplo completo deste guia. Precisa de compreender o que faz, que permissões utiliza e onde funciona. Este guia explica a configuração no Chrome e utiliza um contador visual de unidades de uma encomenda como exemplo.

O que muda e o que se mantém

Uma personalização visual altera o que vê nesse perfil do navegador. Não é uma funcionalidade nativa do Jumpseller nem aparece automaticamente para os seus colegas ou noutro computador.

O contador do exemplo apenas lê as quantidades já apresentadas numa encomenda e acrescenta uma faixa. Não guarda o total na encomenda, não altera a loja pública nem acrescenta o total aos emails ou às exportações. Outros scripts podem ter comportamentos diferentes: não assuma que todos os scripts do Tampermonkey são de apenas leitura.

Antes de começar

• Utilize o Chrome num computador onde tenha autorização para instalar extensões.
• Tenha acesso ao painel da sua loja e um script revisto por alguém de confiança.
• Confirme que abre as encomendas no endereço do painel da sua loja terminado em .jumpseller.com e reveja o âmbito do script antes de o instalar.
• Não utilize scripts de origem desconhecida, não introduza palavras-passe ou tokens API nos mesmos e não os utilize para contornar permissões, verificações de pagamento ou regras de processamento de encomendas.

O Tampermonkey não é desenvolvido pela Jumpseller. Uma alteração no painel pode fazer com que uma personalização deixe de funcionar; não se garante compatibilidade com todas as lojas, navegadores ou versões futuras do painel.

1. Instale a extensão oficial

1. Abra o Tampermonkey na Chrome Web Store.
2. Confirme o nome Tampermonkey e o site do programador tampermonkey.net.
3. Selecione Add to Chrome ou Adicionar ao Chrome.
4. Leia o diálogo de permissões. Na instalação utilizada para este guia, o Chrome pediu autorização para ler e alterar todos os dados em todos os sites, apresentar notificações e modificar os dados que copia e cola. São permissões amplas da extensão, mesmo quando um script específico tem um âmbito restrito.
5. Se aceitar essas permissões e a sua organização o permitir, selecione Add extension ou Adicionar extensão.
6. Aguarde a confirmação de que o Tampermonkey foi adicionado ao Chrome.

Se aparecer Remove from Chrome ou Remover do Chrome, a extensão já está instalada. Não instale outra cópia. Se a sua organização bloquear a instalação, peça ajuda ao administrador em vez de contornar a restrição.

2. Verifique as definições de scripts do Chrome

1. Escreva chrome://extensions/ na barra de endereços do Chrome e prima Enter.
2. Verifique Developer mode ou Modo de programador. No nosso exemplo já estava ativo. Se precisar de o ativar, consulte primeiro o administrador: também permite carregar extensões manualmente.
3. Localize o Tampermonkey e selecione Details ou Detalhes.
4. Procure Allow User Scripts. Na versão do Chrome testada era um interruptor separado do modo de programador. A tradução deste rótulo pode variar.
5. Leia o aviso sobre a execução de código não revisto pela Google. Ative-o apenas quando a sua organização o autorizar e confiar no script.

A imagem mostra as definições reais utilizadas neste exemplo, não uma recriação do diálogo de instalação. Os nomes e requisitos podem variar consoante a versão do Chrome; consulte a ajuda oficial do Tampermonkey se o seu ecrã for diferente. Este exemplo não precisa de acesso em navegação anónima, acesso a ficheiros locais nem permissões adicionais de transferência de ficheiros.

3. Copie e ative o contador

O script completo encontra-se abaixo. Não precisa de alterar o domínio nem editar o código. É executado apenas nas rotas de encomendas orders-v2 do painel, em endereços de lojas que terminam em .jumpseller.com. Não é executado na loja pública nem noutros sites. Um painel num domínio personalizado ou noutra interface de encomendas fica fora do âmbito deste exemplo.

1. Selecione Copiar script completo, abaixo destes passos. Se o navegador bloquear a cópia, o código fica selecionado: prima ⌘C no Mac ou Ctrl+C no Windows.
2. Abra Extensões (o botão em forma de peça de puzzle junto à barra de endereços) e selecione Tampermonkey.
3. Abra Dashboard ou Painel de controlo e selecione Create a new script ou Criar um novo script.
4. Apague todo o texto inicial do editor e cole o código copiado com ⌘V ou Ctrl+V. Não o cole num campo da encomenda nem na barra de endereços.
5. Guarde com ⌘S no Mac ou Ctrl+S no Windows.
6. Regresse ao painel do Tampermonkey. Deve aparecer apenas uma cópia ativa de Jumpseller — Order units (visual). Se testou outro contador anteriormente, desative-o para evitar dois indicadores.
7. Abra uma encomenda da loja e recarregue o separador. Isto também é necessário se chegou à encomenda a partir de outra secção do painel que já estava aberta.
8. Compare o indicador com a soma das quantidades, como no exemplo seguinte.

O âmbito do script abrange as rotas de encomendas do painel de lojas Jumpseller, não todos os sites. Reveja esse âmbito ao instalar. Este código apenas acrescenta um indicador local; não envia nem guarda dados. Foi testado na alejandrotest e com testes de rotas e idiomas; não foi testado em todas as lojas. Se o painel mudar ou o contador não aparecer, desative-o e contacte o suporte.

Copiar script completo

// ==UserScript==
// @name         Jumpseller — Order units (visual)
// @namespace    jumpseller.local.order-units
// @version      0.2.0
// @description  Suma las cantidades ya renderizadas del pedido. Solo visual; no guarda ni envía datos.
// @match        https://*.jumpseller.com/admin/*/orders-v2/*
// @match        https://*.jumpseller.com/admin/orders-v2/*
// @run-at       document-idle
// @grant        none
// @noframes
// ==/UserScript==
/* Local visual helper for Jumpseller orders-v2 admin pages only.
 * No network calls, credentials, storage or order/theme writes.
 * Tested in alejandrotest and representative DOM fixtures, not every store.
 * Bundles/packs are unsupported: parent/component rows can be double-counted.
 * If the admin markup changes, disable the script and request a review.
 */
(() => {
  'use strict';
  if (!/^([a-z0-9]+(?:-[a-z0-9]+)*)\.jumpseller\.com$/i.test(location.hostname) || window.top !== window.self) return;
  if (location.protocol !== 'https:' || !/^\/admin\/(?:[a-z]{2}(?:-[a-z]{2})?\/)?orders-v2(?:\/|$)/i.test(location.pathname)) return;
  const KEY = '__jumpsellerVisualOrderUnits';
  const ID = 'jumpseller-visual-order-units';
  window[KEY]?.stop?.();
  let scheduled = null;
  let stopped = false;
  const routeId = () => location.pathname.match(/^\/admin\/(?:[a-z]{2}(?:-[a-z]{2})?\/)?orders-v2\/edit\/(\d+)\/?$/i)?.[1] || null;
  const locale = location.pathname.match(/^\/admin\/([a-z]{2})(?:-[a-z]{2})?\/orders-v2/i)?.[1] || 'en';
  const labels = locale === 'pt' ? ['Total de unidades', 'linhas de produto', 'Cálculo local; não é guardado. Bundles não suportados.'] : locale === 'es' ? ['Total de unidades', 'líneas de producto', 'Cálculo local; no se guarda. Bundles no soportados.'] : ['Total units', 'product lines', 'Local calculation; not saved. Bundles unsupported.'];
  function remove() { document.getElementById(ID)?.remove(); }
  function directText(element) {
    return Array.from(element.childNodes).filter(n => n.nodeType === 3).map(n => n.textContent).join('');
  }
  function readTable(table) {
    let units = 0, lines = 0;
    for (const row of table.querySelectorAll('tbody > tr')) {
      // Source TableDesktop renders one price/qty div in each product row;
      // expanded discount/tax/profit rows have colspan and no such price div.
      const price = row.querySelector('td > div.tabular-nums');
      const productImage = row.querySelector('td img[width="56"]');
      if (!price && !productImage) continue;
      if (!price || !productImage) throw Error('Unrecognized product row');
      const match = directText(price).trim().match(/\s[x×]\s*(\d+)\s*$/u);
      if (!match) throw Error('Unrecognized quantity');
      const qty = Number(match[1]);
      if (!Number.isSafeInteger(qty) || qty < 0 || !Number.isSafeInteger(units + qty)) throw Error('Invalid quantity');
      units += qty; lines++;
    }
    if (!lines) throw Error('No product rows');
    return { units, lines };
  }
  function update() {
    scheduled = null;
    if (stopped) return;
    const id = routeId();
    if (!id) { remove(); return; }
    // Tie URL to the order header actually rendered by Edit.jsx. On SPA
    // navigation the old table must not be labelled as the newly requested order.
    const headings = Array.from(document.querySelectorAll('.text-xl.font-normal'))
      .filter(e => new RegExp('#\\s*' + id + '\\s*$').test(e.textContent.trim()));
    if (headings.length !== 1) { remove(); return; }
    const heading = headings[0];
    const root = heading.parentElement;
    const tables = Array.from(root.querySelectorAll('table.w-full.border-collapse'))
      .filter(t => t.querySelector('td img[width="56"]'));
    if (tables.length !== 1) { remove(); return; }
    let count;
    try { count = readTable(tables[0]); }
    catch (_) { remove(); return; } // Fail closed: no misleading partial count.
    let badge = document.getElementById(ID);
    if (!badge) {
      badge = document.createElement('div');
      badge.id = ID;
      badge.setAttribute('role', 'status');
      badge.setAttribute('aria-live', 'polite');
      badge.style.cssText = 'margin:8px 0;padding:10px 14px;border:1px solid #d1d5db;border-radius:6px;background:#f8fafc;color:#111827;font-size:15px;font-weight:600';
      heading.insertAdjacentElement('afterend', badge);
    } else if (badge.previousElementSibling !== heading) {
      heading.insertAdjacentElement('afterend', badge);
    }
    const label = `${labels[0]}: ${count.units}`;
    if (badge.textContent !== label) badge.textContent = label;
    const title = `#${id} · ${count.lines} ${labels[1]} · ${labels[2]}`;
    if (badge.title !== title) badge.title = title;
  }
  function schedule() {
    if (!stopped && scheduled === null) scheduled = setTimeout(update, 80);
  }
  const observer = new MutationObserver(schedule);
  observer.observe(document.body, { childList: true, subtree: true, characterData: true });
  const interval = setInterval(schedule, 1000); // URL changes with no DOM event.
  const handle = {
    stop() {
      stopped = true;
      observer.disconnect();
      clearTimeout(scheduled);
      clearInterval(interval);
      remove();
      if (window[KEY] === handle) delete window[KEY];
    }
  };
  window[KEY] = handle;
  update();
})();

Também pode transferir o mesmo script. O bloco de código e a transferência utilizam uma única fonte; não precisa de editar nenhum deles.

4. Exemplo prático de um contador de unidades

Imagine que vende ingredientes de padaria. Uma encomenda tem três linhas: 3 sacos de farinha, 2 embalagens de fermento em pó e 5 embalagens de manteiga. São 10 unidades, não três unidades.

A captura seguinte foi obtida no painel real da alejandrotest, com dados fictícios. A encomenda 2416 contém três linhas de produtos físicos sem relações de bundle. A captura apresenta o rótulo Total de unidades: 10. O script atual acompanha o idioma do painel: Total units em inglês e Total de unidades em espanhol ou português.

Para verificar um contador revisto na sua própria loja:

1. Inicie sessão no painel como habitualmente.
2. Abra Encomendas e escolha uma encomenda existente com produtos normais, sem bundles.
3. Recarregue o separador e aguarde até os produtos terminarem de carregar.
4. Procure um único contador por baixo do número da encomenda.
5. Some as quantidades dos produtos e compare o resultado.
6. Abra outra encomenda a partir da lista. Confirme que o total muda para corresponder a essa encomenda.
7. Regresse à lista. O contador do exemplo não deve permanecer aí.

Os bundles não são suportados por este exemplo. O script soma as linhas apresentadas, pelo que pode contar em simultâneo a linha principal do bundle e as linhas dos seus componentes. Não o utilize para determinar quantos artigos físicos deve embalar numa encomenda com bundles. A sua equipa tem de acordar e implementar essa regra separadamente. Consulte Conjuntos de produtos ou bundles.

O exemplo foi observado na apresentação de computador e em vistas adaptáveis do navegador. Instalar uma extensão no Chrome de computador não a instala num telemóvel.

5. Desative ou remova uma personalização

Para deixar de a ver, abra o Tampermonkey, localize o respetivo script, desative-o e recarregue a página do painel. O contador do exemplo desaparece sem alterar a encomenda.

Para eliminar o script, abra Dashboard, identifique o correto e utilize o respetivo ícone do caixote do lixo. Não elimine outros scripts de que precise. Para remover a extensão completa, abra chrome://extensions/, localize o Tampermonkey e selecione Remover. Esta ação afeta também os restantes scripts geridos pela extensão.

Resolução de problemas

Mantenha cada personalização pequena, reversível e limitada às páginas previstas. Se uma alteração tiver de ser guardada, partilhada entre utilizadores ou integrada no processamento de encomendas, utilize uma funcionalidade adequada do Jumpseller ou consulte a sua equipa técnica sobre uma integração, em vez de transformar um script visual num processo crítico.