, etc.) ou componentes de bibliotecas de UI genéricas diretamente aqui.

Passo 3: Testando sua extensão localmente

1. Certifique-se de estar na pasta raiz do seu app (checkout-message-app).

2. Execute o comando para iniciar o servidor de desenvolvimento:

bash

shopify app dev

3. O CLI pedirá para você selecionar uma loja de desenvolvimento. Escolha a sua.

4. Ele então fornecerá um link para o seu dev preview do checkout. Ele se parecerá com https://admin.shopify.com/store/[your-store-name]/apps/development/[your-app-id]/extensions/[your-extension-id]/preview.

5. Clique neste link. Isso abrirá seu admin da Shopify e você será levado ao Editor de Checkout.

No Editor de Checkout:

• Você verá um novo bloco chamado “Lembrete de Frete Grátis” (ou o nome que você deu ao seu block_properties.title no shopify.extension.toml).
• Arraste e solte este bloco para a área desejada no checkout (ex: acima do resumo do pedido ou abaixo do formulário de contato).
• Clique em “Salvar”.
• Agora, vá para o frontend da sua loja, adicione um produto ao carrinho e prossiga para o checkout. Você deverá ver sua mensagem personalizada!

SCREENSHOT: Editor de Checkout mostrando o novo bloco arrastável.

(Imagine aqui uma imagem do editor de checkout da Shopify, com um novo bloco de extensão visível na barra lateral e sendo arrastado para a área principal do checkout.)

SCREENSHOT: Checkout real com a extensão renderizada.

(Imagine aqui uma imagem do frontend do checkout, com a mensagem “🎉 Frete Grátis em compras acima de R$200! 🎉” e os botões personalizados visíveis.)

Passo 4: Acessando dados do checkout

Uma extensão geralmente precisa interagir com os dados do checkout. O hook useExtensionApi nos dá acesso a objetos importantes.

Vamos modificar nossa extensão para exibir o subtotal do carrinho.

jsx

// extensions/free-shipping-reminder/src/index.jsx (Modificado)
import React from 'react';
import {
render,
BlockStack,
TextBlock,
InlineStack,
Button,
useExtensionApi, // Importamos o hook
reactExtension,
} from '@shopify/ui-extensions-react/checkout';
render('Checkout::Dynamic::Render', () => );
function App() {
// Acessa a API da extensão para obter dados do checkout
const { cost } = useExtensionApi();
const subtotalAmount = cost.totalAmount.current; // Pega o valor atual do subtotal
return (


🎉 Frete Grátis em compras acima de R$200! 🎉


Seu subtotal atual é: {subtotalAmount.currencyCode} {subtotalAmount.amount}

{/ Exemplo de renderização condicional /}
{parseFloat(subtotalAmount.amount) < 200 && (

Faltam {subtotalAmount.currencyCode} {200 - parseFloat(subtotalAmount.amount)} para frete grátis!

)}


Confira nossa promoção


Política de Frete



);
}

• useExtensionApi(): Este hook fornece acesso a vários objetos da API de checkout, incluindo cost (para informações de custo), cart (para itens do carrinho), customer (para dados do cliente), etc.
• cost.totalAmount.current: Acessamos o subtotal atual do carrinho. Ele retorna um objeto com amount (o valor numérico) e currencyCode (a moeda).
• Renderização Condicional: Adicionei um exemplo de como você pode exibir uma mensagem diferente com base no valor do subtotal. Se o valor for menor que R$200, ele mostra quanto falta para o frete grátis. Isso é super poderoso para personalização!

Sempre que fizer alterações no código, o Shopify CLI detectará as mudanças e fará um hot reload no seu preview do checkout. Atualize a página do checkout no seu navegador para ver as mudanças.

5. Publicando sua Checkout UI Extension

Uma vez que sua extensão esteja funcionando perfeitamente no ambiente de desenvolvimento, é hora de publicá-la para que ela possa ser usada em sua loja de produção.

Passo 1: Construir e implantar a extensão

1. Pare o servidor de desenvolvimento (Ctrl+C).

2. Na pasta raiz do seu app (checkout-message-app), execute o comando de deploy:

bash

shopify app deploy

• O CLI perguntará se você deseja criar uma nova versão do app ou usar uma existente. Escolha a opção para criar uma nova versão.
• Ele fará o build do seu código e o enviará para a Shopify.
• Ao final, ele fornecerá um link para o “Developer Console” da sua extensão.

Passo 2: Habilitar e configurar a extensão no Admin

1. Acesse o link do Developer Console ou navegue até Apps no seu admin da Shopify e depois clique no seu app de desenvolvimento.

2. Dentro do seu app, vá para a seção “Extensions”. Você verá sua FreeShippingReminder listada.

3. Clique nela. Você terá opções para gerenciar a versão e publicá-la.

Importante: A extensão precisa ser instalada na sua loja para ser visível no Editor de Checkout.

• Acesse Configurações > Checkout e conta no seu admin da Shopify.
• Na seção “Personalização do checkout”, clique em Personalizar checkout.
• Isso abrirá o Editor de Checkout.
• Você deverá ver o bloco da sua extensão na barra lateral de blocos. Arraste e solte-o onde desejar e salve as alterações.

Sua extensão agora estará ativa no seu checkout da loja!

DICA: Sempre teste sua extensão em um ambiente de desenvolvimento ou staging antes de publicá-la para sua loja principal.

6. Boas Práticas e Limitações

• Use os componentes da Shopify UI: Sempre use os componentes fornecidos por @shopify/ui-extensions-react/checkout. Eles são otimizados, acessíveis e garantem compatibilidade futura. Não tente injetar HTML ou CSS customizado diretamente, pois não funcionará e não é suportado.
• Foco na performance: Mantenha seu código limpo e otimizado. O checkout precisa ser o mais rápido possível.
• Teste em diferentes dispositivos: Garanta que sua extensão se adapte bem a diferentes tamanhos de tela (desktop, tablet, mobile). Os componentes da Shopify UI já são responsivos, mas sempre verifique.
• Atenção aos targets: Escolha o target de injeção mais apropriado para sua extensão. Um lugar errado pode confundir o cliente.
• Segurança e Privacidade: Evite coletar informações sensíveis desnecessariamente. Esteja ciente das políticas de privacidade da Shopify.
• Não abuse: Evite adicionar muitas extensões ou funcionalidades que possam sobrecarregar o cliente no checkout. Menos é mais!

💻 Exemplos Práticos

Vamos criar mais uma extensão simples para adicionar um campo de texto para “Instruções Especiais para o Pedido”.

1. Adicionar uma nova extensão:

Na pasta raiz do seu checkout-message-app (ou no seu app existente), execute:

bash

shopify app generate extension

• Escolha Checkout UI Extension.
• Nome: SpecialInstructions
• Template: JavaScript React

2. Código da extensão (extensions/special-instructions/src/index.jsx):

jsx

import React from 'react';
import {
render,
TextField,
reactExtension,
useExtensionApi,
} from '@shopify/ui-extensions-react/checkout';
render('Checkout::Dynamic::Render', () => );
function App() {
const { applyAttributeChange } = useExtensionApi();
// Função para lidar com a mudança no campo de texto
const handleInstructionChange = (value) => {
// applyAttributeChange permite salvar metadados no pedido
applyAttributeChange({
key: 'special_instructions', // Chave para o metadado
type: 'updateAttribute',
value: value,
});
};
return (

label="Instruções Especiais para o Pedido (Opcional)"
multiline={3} // Campo de texto com 3 linhas
onChange={handleInstructionChange}
placeholder="Ex: 'Entregar na portaria', 'Embalar para presente'"
maxLength={250} // Limite de caracteres
/>
);
}

• TextField: Componente de campo de texto da Shopify UI.
• useExtensionApi() e applyAttributeChange(): Este é um recurso muito importante! Ele permite que você salve dados (como as instruções especiais) como atributos do carrinho ou atributos do pedido. Esses dados serão anexados ao pedido e estarão visíveis no admin da Shopify quando o pedido for feito. Isso é perfeito para informações personalizadas que o cliente precisa fornecer.

3. Configuração da extensão (extensions/special-instructions/shopify.extension.toml):

toml

... (outras configurações)
[targeting.extension_point.purchase.checkout.block.render]
block_properties = { title = "Instruções Especiais" }

4. Teste e Deploy:

• shopify app dev para testar localmente. Arraste e solte o novo bloco “Instruções Especiais” no Editor de Checkout.
• Preencha o campo, complete um pedido de teste e verifique no admin da Shopify se as instruções foram salvas nos detalhes do pedido.
• shopify app deploy para publicar.

SCREENSHOT: Detalhes do pedido no admin da Shopify, mostrando o atributo personalizado.

(Imagine aqui uma imagem da tela de detalhes de um pedido no admin da Shopify, destacando uma seção onde “special_instructions: Entregar na portaria” é visível.)

🎯 Exercícios e Desafios

1. Desafio Básico: Modifique a extensão FreeShippingReminder para que, se o subtotal for acima de R$500, a mensagem mude para “Você é um cliente VIP! Frete GRÁTIS e um presente especial.”

2. Desafio Intermediário: Crie uma nova Checkout UI Extension que adicione um checkbox “Aceito receber ofertas e novidades por e-mail”. Use applyAttributeChange para salvar o estado deste checkbox como um atributo do pedido.

3. Desafio Avançado (Pensando fora da caixa): Pesquise sobre outros “targets” de injeção disponíveis para Checkout UI Extensions (por exemplo, purchase.checkout.shipping-method-list.render-after). Crie uma extensão que, após a seleção do método de envio, exiba uma estimativa de entrega mais detalhada (você pode usar dados fictícios para a estimativa, mas foque na injeção correta da UI).

📝 Resumo da Aula

Nesta aula super importante, você desvendou o mundo da personalização do checkout através das Checkout Extensions. Entendemos por que a Shopify evoluiu para este modelo (segurança, performance, atualizações), exploramos os tipos de extensões (UI, Functions, Pixels), e colocamos as mãos na massa para criar e implantar nossa primeira Checkout UI Extension. Aprendemos a usar o Shopify CLI, o framework ui-extensions-react, a acessar dados do checkout e a salvar informações personalizadas nos pedidos. O poder de controlar a experiência do cliente no ponto mais crítico da jornada de compra está agora ao seu alcance!

🚀 Preparação para próxima aula

Na nossa próxima aula, vamos aprofundar ainda mais no desenvolvimento de apps e extensões, explorando as Shopify Functions com mais detalhes. Veremos como elas podem ser usadas para criar lógicas complexas para descontos, taxas de frete ou validações de carrinho que não seriam possíveis com as UI Extensions ou com as ferramentas padrão da Shopify. Prepare-se para um mergulho no mundo do WebAssembly e da lógica de negócios!

📚 Recursos Adicionais

• Documentação Oficial da Shopify para Checkout UI Extensions: https://shopify.dev/docs/apps/checkout/getting-started
• Lista de Componentes @shopify/ui-extensions-react/checkout: https://shopify.dev/docs/api/checkout-ui-extensions/2023-10/components
• Shopify CLI (Documentação): https://shopify.dev/docs/apps/tools/cli
• Tutoriais em vídeo da Shopify Dev (YouTube): Procure por “Shopify Checkout Extensions Tutorial” para exemplos práticos.

Parabéns por chegar até aqui! A personalização do checkout é um diferencial enorme para qualquer loja. Vejo vocês na próxima aula! 👋