Autorizou uma aplicação Shopify personalizada, viu o ecrã de confirmação e ainda assim não consegue encontrar nada na página de agradecimento ou página de estado da encomenda. A aplicação aparece no admin, mas os seus clientes não veem um editor de encomendas, upsell ou funcionalidade de conta. Essa situação é comum porque instalar uma aplicação Shopify personalizada não é uma tarefa de um clique. Tem dois trabalhos separados: autorizar a aplicação para a loja correta e depois colocar o seu bloco de aplicação numa superfície Shopify suportada.

Índice

Por que a instalação de uma aplicação personalizada é um trabalho de duas fases

A Shopify trata a autorização e apresentação como operações diferentes. Durante a autorização, o comerciante aprova o acesso aos dados solicitados pela aplicação e a política de privacidade, depois instala-a através de uma ligação de instalação específica da loja. A documentação oficial de instalação de aplicações da Shopify explica que uma ligação de aplicação personalizada está vinculada a uma loja e não pode ser reutilizada noutro local.

Essa aprovação dá permissão à aplicação para operar. Não decide automaticamente onde a aplicação deve aparecer na experiência do cliente. Para ferramentas pós-compra, o trabalho importante geralmente ocorre nos editores de checkout e contas de clientes, onde um comerciante adiciona o bloco da aplicação a um destino compatível.

Um diagrama explicando que a instalação de uma aplicação personalizada do Shopify requer dois passos: autorização da loja e colocação de tema.

A fase um é a autorização da loja

O programador cria ou configura a aplicação personalizada no Painel de Desenvolvimento do Shopify. O comerciante abre então a ligação de instalação gerada enquanto conectado à loja pretendida, revê os âmbitos solicitados e seleciona Instalar aplicação. Esta é a fronteira de segurança. Se o comerciante não aprovar o acesso solicitado, a aplicação não receberá as permissões de que necessita.

A fase dois é a colocação do bloco da aplicação

Após a autorização, o comerciante abre o editor relevante, encontra a aplicação instalada e adiciona o seu bloco a uma página suportada. As opções de personalização de caixa de pagamento do Shopify descrevem este modelo baseado em blocos, incluindo pesquisa de aplicações instaladas e verificação de quais destinos cada bloco suporta.

Regra prática: Se a aplicação está instalada mas ausente da página do cliente, verifique a colocação antes de a reinstalar.

O modelo mental mais fiável é simples: a autorização torna a aplicação disponível para o Shopify, a colocação torna a funcionalidade visível para os clientes. Uma primeira fase bem-sucedida pode portanto parecer uma instalação falhada até que a segunda fase seja concluída.

Pré-requisitos, Planos e Permissões de Pessoal

Antes de abrir uma ligação de instalação, confirme que a loja, a aplicação e as pessoas envolvidas estão prontas. A documentação de personalização de caixa de pagamento e conta de cliente do Shopify indica que as personalizações de aplicações suportadas estão disponíveis no plano Shopify Básico ou superior, com algumas capacidades também disponíveis no Shopify Plus. O destino exato ainda depende da extensão da aplicação e da página que suporta, portanto, a elegibilidade do plano por si só não garante que cada bloco apareça.

A aplicação personalizada já deve existir no Painel de Desenvolvimento do Shopify, e o programador deve configurar os âmbitos de acesso e pontos de extensão necessários para a funcionalidade. Um editor de encomendas pós-compra, por exemplo, necessita de uma superfície de estado de encomenda ou conta de cliente suportada. Uma reescrita de tema não substituirá uma extensão de caixa de pagamento ou conta de cliente em falta.

Confirme as pessoas e as permissões

O proprietário da loja deve executar a autorização sempre que possível. O acesso do pessoal pode ser suficiente para partes do fluxo de trabalho, mas a conta deve ter as permissões relevantes de instalação e configuração de aplicações. Um programador com acesso de pessoal pode preparar e resolver problemas da aplicação, mas não deve assumir que pode autorizá-la em nome do comerciante.

A autenticação de dois fatores também é necessária para fluxos de trabalho de desenvolvimento e instalação de aplicações personalizadas. Verifique cuidadosamente o URL da loja antes de abrir a ligação de instalação. Shopify vincula uma ligação de instalação de aplicação personalizada à loja pretendida, pelo que uma ligação gerada para uma loja não funcionará como ligação de uso geral para outra.

Se a sua equipa gere fluxos de trabalho operacionais e também experiências pós-compra, documente quem é responsável pela instalação, colocação de blocos e testes. Uma referência de acompanhamento útil é este guia sobre configuração de fluxo de trabalho de encomendas Shopify.

Funções de pessoal e permissões de instalação

Função Pode instalar aplicação personalizada Pode colocar bloco de aplicação Notas
Proprietário da loja Sim Sim Pode rever a autorização e completar a etapa de aprovação do comerciante.
Membro da equipa com permissões de aplicação Geralmente, sujeito às definições da loja Sim, se lhe for concedido acesso de editor Pode configurar a aplicação e colocação quando o proprietário ativou o acesso necessário.
Programador com acesso de pessoal Pode preparar a aplicação e ajudar Pode configurar editores suportados se permitido Não deve assumir que podem aprovar autorização para o comerciante.

Uma verificação prévia rápida evita a maioria das tentativas desperdiçadas: verifique a loja-alvo, confirme a autenticação de dois fatores, verifique as permissões de pessoal e pergunte ao programador qual é a superfície Shopify para a qual a aplicação foi concebida.

Criação e Autorização da Aplicação Personalizada

A autorização começa no Painel de Controlo de Desenvolvimento Shopify, não no editor de tema. O programador seleciona a loja-alvo, abre a aplicação personalizada e revê a sua configuração. Nas definições de acesso à API, selecione apenas os escopos que a aplicação necessita, depois guarde a configuração antes de gerar a ligação de instalação.

A orientação de instalação de aplicações personalizadas da Shopify indica que a ligação é específica da loja. Isto é importante em agências com lojas de desenvolvimento, lojas de teste e lojas de produção. Uma ligação copiada da organização parceira errada ou gerada para uma loja diferente pode produzir um resultado de loja inválida, mesmo quando a aplicação em si está configurada corretamente.

A sequência de autorização

  1. Selecione a loja pretendida. Confirme o nome e o domínio da loja no Painel de Controlo de Desenvolvimento antes de gerar qualquer coisa.
  2. Reveja os escopos da API. Pergunte ao programador o que cada escopo ativa. Se a aplicação edita encomendas, lê informações de clientes ou gere dados relacionados com cumprimento, o acesso solicitado deve corresponder a esse fim.
  3. Guarde a configuração. As alterações de escopo não são úteis até que a configuração da aplicação tenha sido guardada.
  4. Gere a ligação de instalação. Trate-a como uma ligação de implementação privada e específica da loja, não como um URL de aplicação reutilizável.
  5. Abra-a na sessão de administrador com sessão iniciada do comerciante. Evite testar numa sessão de browser ligada a outra loja.
  • Revise o ecrã de acesso. O Shopify apresenta informações sobre acesso a dados e privacidade antes da instalação.
  • Seleccione Instalar app. O comerciante deve aprovar activamente o acesso solicitado.
  • Screenshot from https://shopify.dev/assets/api/custom-apps/install-confirmation.png

    O que verificar antes da aprovação

    Não clique no ecrã de autorização apenas porque a app veio de um programador de confiança. Compare os âmbitos indicados com a funcionalidade que solicitou, confirme que a política de privacidade é a esperada e verifique que a loja apresentada no admin é o destino correcto.

    Se a app solicitar acesso que não corresponde à sua função, pare e peça ao programador para corrigir a configuração. Se um âmbito for rejeitado, a causa pode ser uma declaração incompleta de dados de clientes protegidos ou um âmbito que a app já não utiliza. O programador deve ajustar a configuração, guardá-la, gerar uma nova ligação específica da loja e repetir a revisão.

    Após a instalação, confirme que a app aparece na área de apps instaladas da loja. Isto confirma a primeira fase, mas não prova que a funcionalidade de cliente está activa. Ainda precisa de colocar e testar a extensão.

    Colocar o Bloco da App na Página de Estado da Encomenda

    A maioria das falhas de instalação após compra ocorrem após a autorização. O comerciante instala a app, regressa ao admin, e espera que a funcionalidade apareça automaticamente. O modelo actual do Shopify requer uma etapa de configuração separada no editor de checkout ou conta do cliente.

    Abra Definições, depois Checkout, e localize a área de personalização para a experiência de página de agradecimento e estado da encomenda. Consoante a app e configuração da conta, pode em alternativa trabalhar através de Definições, depois Contas do cliente, para abrir o editor de conta do cliente. O Shopify define a página de estado da encomenda como o local onde os clientes podem ver, rastrear e gerir uma encomenda específica, o que a torna uma superfície natural para editores de encomendas, acções de suporte e ofertas após compra.

    Adicionar o bloco

    No editor, utilize o selector de página para abrir Estado da encomenda ou o destino relevante da conta do cliente. Seleccione Adicionar bloco da app ou a opção Apps, depois procure na lista de apps instaladas a app personalizada. A documentação do Shopify sobre colocação de apps de checkout confirma que as apps podem ser adicionadas a páginas de agradecimento e estado da encomenda suportadas após a instalação.

    Se a app não aparecer na primeira lista, procure pelo seu nome instalado. Não assuma que todos os blocos suportam todas as páginas. O Shopify instrui especificamente os comerciantes a confirmarem destinos suportados após a instalação, e o editor apenas apresenta destinos compatíveis como Encomendas, Estado da encomenda, Perfil ou Contas quando a app suporta contas de cliente.

    Arraste o bloco para a secção pretendida, como a área de resumo do pedido, e depois pré-visualize a página. Utilize as vistas de ambiente de trabalho, móvel e ecrã completo do editor para verificar se o componente se adequa ao espaço disponível. Guarde a configuração apenas após confirmar o conteúdo, a posição e as regras de visibilidade.

    Captura de ecrã de https://help.shopify.com/en/manual/online-sales-channels/checkout/order-status-page/customize-order-status-page

    Uma referência útil para esta parte do fluxo de trabalho é o guia para personalizar a página de estado do pedido do Shopify.

    Considere a pré-visualização como uma verificação de configuração

    O editor confirma que o Shopify aceitou o bloco e a sua localização. Não substitui um teste de caminho do cliente. Coloque uma encomenda de teste real, abra a página de estado do pedido resultante e confirme que a aplicação é carregada para a conta do cliente e o estado do pedido que está a testar.

    Esta distinção é importante para aplicações condicionais. Um editor de pedidos pode ocultar-se após o cumprimento, enquanto uma venda adicional pode excluir um pedido sem produtos elegíveis. Um bloco pode, portanto, ser colocado corretamente e permanecer intencionalmente invisível para uma encomenda de teste específica.

    Resolução de Problemas das Falhas de Instalação Mais Comuns

    Uma instalação de aplicação personalizada com falha geralmente tem um sintoma reconhecível. Diagnostique primeiro o sintoma e depois altere uma variável de cada vez. A reinstalação repetida raramente resolve um ponto de extensão ausente ou um problema de compatibilidade do editor.

    Comece com a falha visível

    Se o bloco nunca aparecer no editor, verifique se o programador configurou o ponto de extensão pós-compra ou de conta do cliente correto. Verifique também se a aplicação está ligada ao arquivo pretendido e se a aplicação não está mais limitada a uma organização de desenvolvimento ou arquivo de teste não selecionado.

    Uma ligação de instalação que retorna uma mensagem 404 ou loja inválida geralmente aponta para uma incompatibilidade de arquivo. Verifique o domínio na ligação, o arquivo atualmente aberto no painel de administração e se a conta de pessoal utilizada para criar a ligação ainda tem acesso. A ligação deve ser gerada para o arquivo aprovado.

    A rejeição de âmbito requer informações do programador. O acesso à API solicitado pode estar desatualizado, incompleto ou sujeito a requisitos de dados do cliente que não foram declarados. Não contorne o ecrã de revisão. Peça a lista de âmbitos e compare-a com os requisitos reais da funcionalidade.

    Sintoma Causa provável Primeira solução
    App instalado, mas nenhum bloco aparece Ponto de extensão em falta ou incompatível Peça ao programador qual página e tipo de bloco a app suporta.
    Link de instalação mostra uma loja inválida Link gerado para outra loja Confirme novamente o domínio da loja e gere um novo link para essa loja.
    Autorização rejeita os âmbitos solicitados Problema de configuração de âmbito ou dados protegidos O programador deve rever os âmbitos e declarações no Dev Dashboard.
    App aparece na loja errada Dashboard de parceria definido por padrão para outro alvo Seleccione explicitamente a loja de produção do comerciante antes de gerar o link.
    Bloco aparece num editor, mas não noutro A extensão não suporta esse destino Use a página suportada mostrada pela Shopify, ou solicite uma extensão compatível.

    Antes de contactar o suporte, registe o domínio da loja, nome da app, texto de erro exato, função do utilizador atual e a página onde o bloco está em falta. As Perguntas Frequentes do Mayra Apps também são um lugar útil para verificar questões de instalação específicas do produto antes de escalar.

    Hábito de implementação: Mantenha os erros de autorização separados dos erros de renderização. Os primeiros dizem respeito ao acesso. Os segundos dizem respeito à compatibilidade, posicionamento ou comportamento de tempo de execução da extensão.

    Walkthrough Real: Do Clique ao Cliente

    Um comerciante Shopify Plus recebe um link de instalação específico da loja de um parceiro terceiro para uma app de venda adicional após a compra. O comerciante abre o link enquanto iniciou sessão na loja de produção, confirma a identidade da loja, revê o acesso aos dados solicitado, verifica a política de privacidade e clica em Instalar app.

    A app agora existe no admin Shopify do comerciante, mas a experiência do cliente não mudou. O comerciante abre o editor de checkout, selecciona a página de estado da encomenda, procura a lista de apps instaladas e adiciona o bloco de venda adicional à área de resumo da encomenda. A pré-visualização do editor mostra o posicionamento no desktop e dispositivos móveis, para que o comerciante guarde a configuração.

    Testar o caminho real do cliente

    O comerciante realiza uma encomenda de teste real com desconto usando a sua própria conta de cliente. Confirma que o bloco de venda adicional é carregado a partir da página de estado da encomenda, que a oferta corresponde às regras de elegibilidade da encomenda e que a funcionalidade não aparece quando a encomenda deve ser excluída.

    Para uma oferta após a compra, este teste deve cobrir mais do que o posicionamento visual. Confirme que o cliente pode interagir com o bloco, que a ação resultante actualiza corretamente a encomenda original e que a app regista o evento no seu dashboard. Uma encomenda de teste também expõe problemas de estado da conta que uma pré-visualização do editor pode não conseguir detectar.

    O comerciante depois verifica a actividade de eventos da app e os registos do admin Shopify. Apenas depois do comportamento voltado para o cliente, da gestão de encomendas e dos sinais de relatório estarem todos de acordo, a equipa deve publicar o fluxo de trabalho para clientes normais.

    Este é o significado prático do modelo de duas fases. O ecrã de instalação prova autorização. O pedido de teste prova que Shopify pode renderizar e executar a extensão autorizada onde os clientes a utilizam.

    Lista de Verificação e Perguntas Finais

    Utilize esta lista de verificação após cada implementação de Shopify instalar aplicação personalizada. Separa a prova de autorização da prova de colocação, para que uma falha silenciosa tenha um ponto de partida claro.

    1. Autorização da loja: Confirme que a aplicação aparece no Shopify admin correto e que os âmbitos de API aprovados correspondem aos requisitos do programador.
    2. Presença do bloco da aplicação: Abra Checkout ou Contas de cliente e verifique que o bloco foi adicionado ao estado do pedido suportado, página de agradecimento ou destino de conta.
    3. Teste de pedido: Coloque um pedido de teste real e inspecione a página virada para o cliente em desktop e mobile.
    4. Entrega de webhook: Pergunte ao programador onde os eventos webhook são registados e confirme a entrega bem-sucedida do pedido de teste.
    5. Revisão de permissões: Reconfirme o acesso do pessoal e confirme que as pessoas responsáveis pela configuração podem gerir a aplicação e o editor.

    Uma lista de verificação de cinco passos para verificar a instalação, configuração, testes e configurações de permissões de uma aplicação personalizada Shopify.

    Perguntas finais que comerciantes fazem

    Posso instalar qualquer aplicação personalizada em qualquer plano? Não. O tipo de extensão da aplicação e o plano Shopify da loja determinam quais as superfícies de personalização disponíveis. Verifique o plano e destino suportados com o programador antes da implementação.

    O que acontece se desinstalar a aplicação? A desinstalação remove a autorização da aplicação da loja, mas a retenção de dados e limpeza dependem da implementação e política da aplicação. Pergunte ao programador o que acontece à configuração armazenada, dados de cliente e registos históricos antes de a remover.

    E se a instalação tiver sucesso mas nada for renderizado? Volte ao editor, procure na lista de aplicações instaladas e verifique os destinos suportados do bloco. De seguida, coloque um pedido de teste real. Se o bloco continuar ausente, envie ao programador o domínio da loja, nome da aplicação, função do utilizador, página exata e qualquer ID de pedido mostrado por Shopify.

    Quem deve corrigir um âmbito ou erro de extensão? O programador da aplicação deve corrigir a configuração do Dev Dashboard, âmbitos, declarações ou pontos de extensão não suportados. O comerciante controla a autorização e colocação.

    O registo de implementação mais limpo tem duas confirmações: Shopify autorizou a aplicação e um teste de cliente provou que o bloco funciona na página pretendida.


    Mayra Apps ajuda comerciantes Shopify a configurar experiências pós-compra, tais como edições de pedidos de auto-atendimento, deflexão de cancelamento e upsells de um clique através de contas de cliente e na página de estado do pedido. Se estiver a instalar uma aplicação personalizada para estes fluxos de trabalho, visite Mayra Apps para rever as opções de configuração e colocação disponíveis.