Plataformas
Shopify Hydrogen (headless)
Shopify «Headless» no Hydrogen e no Oxygen: uma rota de servidor e um botão na página do produto.
Os exemplos de código, os pontos de extremidade e os códigos de erro são os mesmos em todas as línguas.
Adicione a funcionalidade de experimentação virtual a uma loja virtual headless do Shopify, criada com o Hydrogen e alojada no Oxygen. Basta uma rota de servidor e um componente de página de produto, e a chave da API nunca chega ao navegador.
O que significa «sem cabeça»
Uma loja normal do Shopify apresenta as suas páginas através de um tema. A nossa aplicação do Shopify adiciona o botão «Experimentar» a esse tema sem necessidade de código.
Uma loja headless mantém o Shopify para os produtos, o carrinho, o checkout e os pagamentos, mas a interface que os clientes veem é uma aplicação React separada, criada pelos seus programadores. O Hydrogen é o framework do Shopify para essa aplicação e o Oxygen é o serviço de alojamento do Shopify para a mesma. Como não existe um tema, os blocos da aplicação de temas não aparecem; por isso, uma loja «headless» adiciona a funcionalidade de «experimentar» através da API para programadores.
| Loja de temas | Loja «Headless» (da Hydrogen) | |
|---|---|---|
| Montra | Tema do Shopify | A tua aplicação React no Oxygen |
| Como se adiciona a funcionalidade de experimentação | Instale a aplicação Shopify e adicione o bloco | Uma rota de servidor e um componente |
| Faturação | Plano do Shopify, na sua fatura do Shopify | Créditos da API para programadores, pré-pagos |
| Guia | Shopify | Esta página |
Como funciona
POST /api/try-on (photo + product image URL)
POST /api/v1/generate (X-API-KEY)
200 image/png
200 image/png
- O cliente clica em Experimentar na página de um produto e tira ou carrega uma fotografia.
- O navegador envia a fotografia e o URL da imagem do produto para a tua rota do Hydrogen.
- A sua rota chama o TryOnCloud com a sua chave secreta e recebe a imagem finalizada, normalmente em cerca de 20 segundos.
- O cliente imagina-se a usar o produto. O TryOnCloud não guarda nada, a menos que ative a opção de armazenamento dos resultados.
1. Obter uma chave API
Registe-se, aceda ao Painel de Controlo > Chaves API e crie uma chave. Esta começa por tk_dev_v1_ e só é apresentada na íntegra uma única vez. A sua conta começa com períodos de teste gratuitos, e o modo de teste (?mock=true) é sempre gratuito.
2. Guardar a chave no Oxygen
No painel de administração do Shopify, aceda a Hydrogen > a sua loja > Definições da loja > Ambientes e variáveis e adicione uma variável secreta:
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_herePara desenvolvimento local, importa-o para o ficheiro .env com o comando npx shopify hydrogen env pull ou adiciona-o manualmente ao ficheiro .env. Em seguida, adiciona-o ao tipo Env no ficheiro env.d.ts, para que context.env fique tipado:
interface Env extends HydrogenEnv {
TRYONCLOUD_API_KEY: string
}3. Adicionar a rota do servidor
Crie o ficheiro app/routes/api.try-on.tsx. O Hydrogen disponibiliza-o em /api/try-on. A rota só aceita imagens de produtos provenientes do seu próprio CDN do Shopify, para que ninguém possa utilizar a sua chave para experimentar imagens aleatórias.
import type { Route } from "./+types/api.try-on"
const MAX_PHOTO_BYTES = 15 * 1024 * 1024
export async function action({ request, context }: Route.ActionArgs) {
if (request.method !== "POST") return new Response("Method not allowed", { status: 405 })
const incoming = await request.formData()
const person = incoming.get("person")
const garmentUrl = incoming.get("garmentUrl")
// One id per try-on, made in the browser. A retry with the same id is never charged twice.
const tryOnId = incoming.get("tryOnId")
if (!(person instanceof Blob) || person.size === 0 || person.size > MAX_PHOTO_BYTES) {
return Response.json({ error: "Please add a photo under 15MB." }, { status: 400 })
}
// Only your own product images: blocks anyone using this route as a free try-on service.
if (typeof garmentUrl !== "string" || !garmentUrl.startsWith("https://cdn.shopify.com/")) {
return Response.json({ error: "Invalid product image." }, { status: 400 })
}
const form = new FormData()
form.append("person_image", person, "person.jpg")
form.append("garment_url", garmentUrl)
// Optional: your own shopper id (for example a hash of the Customer Account id),
// so you can find this shopper's try-ons and erase them on request.
// form.append("customer_id", shopperId)
const headers: Record<string, string> = { "X-API-KEY": context.env.TRYONCLOUD_API_KEY }
if (typeof tryOnId === "string" && /^[\w-]{8,64}$/.test(tryOnId)) headers["Idempotency-Key"] = tryOnId
const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
method: "POST",
headers,
body: form,
signal: AbortSignal.timeout(120_000),
})
const requestId = res.headers.get("X-Request-Id") ?? ""
if (!res.ok) {
const { error, code } = await res.json()
console.error("try-on failed", code, requestId) // quote requestId to TryOnCloud support
return Response.json({ error, code }, { status: res.status })
}
return new Response(res.body, {
headers: { "Content-Type": "image/png", "Cache-Control": "no-store", "X-Request-Id": requestId },
})
}Num projeto Hydrogen mais antigo baseado no Remix, importe os tipos a partir de @shopify/remix-oxygen: import type { ActionFunctionArgs } from "@shopify/remix-oxygen" e defina o tipo da ação como ({ request, context }: ActionFunctionArgs).
4. Adicionar o botão à página do produto
Crie o ficheiro app/components/TryOnButton.tsx:
import { useState } from "react"
export function TryOnButton({ productImageUrl }: { productImageUrl: string }) {
const [result, setResult] = useState<string | null>(null)
const [busy, setBusy] = useState(false)
const [error, setError] = useState<string | null>(null)
async function onFile(file: File) {
setBusy(true)
setError(null)
const form = new FormData()
form.append("person", file)
form.append("garmentUrl", productImageUrl)
form.append("tryOnId", crypto.randomUUID()) // reuse the same id if you add a "Retry" button
try {
const res = await fetch("/api/try-on", { method: "POST", body: form })
if (!res.ok) throw new Error((await res.json()).error ?? "Try-on failed")
setResult(URL.createObjectURL(await res.blob()))
} catch (e) {
setError(e instanceof Error ? e.message : "Try-on failed")
} finally {
setBusy(false)
}
}
return (
<div>
<label>
{busy ? "Creating your look..." : "Try it on"}
<input
type="file"
accept="image/*"
capture="user"
hidden
disabled={busy}
onChange={(e) => e.target.files?.[0] && onFile(e.target.files[0])}
/>
</label>
<p>Your photo is used only to create this image and is not stored.</p>
{error && <p role="alert">{error}</p>}
{result && <img src={result} alt="You wearing this product" />}
</div>
)
}Em seguida, apresenta-a na rota do produto, app/routes/products.$handle.tsx, com a imagem da variante selecionada, recorrendo à imagem principal do produto caso a outra não esteja disponível:
const garmentUrl =
product.selectedOrFirstAvailableVariant?.image?.url ?? product.featuredImage?.url
{garmentUrl && <TryOnButton productImageUrl={garmentUrl} />}Certifique-se de que a sua consulta de produto solicita image { url } na variante e featuredImage { url } no produto.
5. Permita que a imagem resultante seja incluída no seu CSP
O Hydrogen envia uma Política de Segurança de Conteúdo (CSP) rigorosa. O resultado é apresentado a partir de uma URL blob:, pelo que deve adicionar blob: a imgSrc em app/entry.server.tsx:
const { nonce, header, NonceProvider } = createContentSecurityPolicy({
shop: { checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN, storeDomain: context.env.PUBLIC_STORE_DOMAIN },
imgSrc: ["'self'", "https://cdn.shopify.com", "data:", "blob:"],
})Não é necessário alterar o connectSrc: o navegador apenas comunica com a sua própria rota /api/try-on.
6. Testar antes de colocar em funcionamento
- Defina a rota para o modo de teste enquanto compila: utilize
https://www.tryoncloud.com/api/v1/generate?mock=true. Esta opção executa todas as verificações e devolve a fotografia inalterada, sem utilizar créditos. - Experimente alguns produtos: tops, vestidos, saris, conjuntos de kurta e calças.
- Experimente utilizar uma fotografia demasiado grande e um ficheiro que não seja de imagem, e verifique as mensagens de erro.
- Remova
?mock=truee faça experimentações reais.
7. Implementá-lo à escala de retalho
Catálogos extensos e muitas lojas precisam de algo mais do que um simples botão. Tudo isto já está integrado:
| Necessidade | Como |
|---|---|
| Separação entre a fase de preparação e a fase de produção | Crie uma chave por ambiente na secção Chaves de API. Atribua à chave de teste um limite de crédito mensal e uma data de validade, para que os testes nunca gastem créditos de produção. |
| Novas tentativas seguras em redes móveis | Envie uma Idempotency-Key (o tryOnId acima). Uma nova tentativa da mesma experiência de experimentação após uma perda de ligação é cobrada uma única vez, e o botão fica desativado enquanto a experiência de experimentação está a decorrer, pelo que um toque duplo não pode iniciar uma segunda experiência. |
| Apoio e auditoria | Cada resposta inclui o cabeçalho X-Request-Id. Registe-o juntamente com os seus erros e indique-nos o valor desse cabeçalho. |
| Pedidos de privacidade dos clientes | Envie customer_id e, em seguida, elimine os dados desse cliente com DELETE /api/v1/customers/:id. Por predefinição, as fotografias dos clientes nunca são guardadas. |
| Produtos populares | A análise da peça de vestuário fica armazenada em cache durante 30 dias, pelo que as novas experiências de vestuário com a mesma fotografia do produto são cerca de 2 segundos mais rápidas. |
| Imagens do catálogo | Crie fotografias com modelos para vários SKUs através do método POST /api/v1/batches (até 500 por lote) e receba um webhook assinado quando cada uma estiver pronta. Consulte tarefas assíncronas, lotes e webhooks. |
| Picos de tráfego | 300 pedidos por minuto por chave e 600 por conta. Antes de uma grande promoção ou de um lançamento festivo, avise-nos para que possamos planear a capacidade. |
| Monitorização | Taxa de sucesso e velocidade em tempo real em /status; utilização por chave no Generations (pesquisa, exportação para CSV). |
| Geradores de clientes | Especificação OpenAPI 3.1 em /api/v1/openapi.json. |
8. Lista de verificação para a entrada em funcionamento
TRYONCLOUD_API_KEYé uma variável secreta no ambiente de produção do Oxygen- A chave não aparece em nenhum lugar no código do navegador nem no código-fonte da página
?mock=trueremovido da rotablob:adicionado aimgSrc- As imagens dos produtos provêm de
cdn.shopify.come mostram a peça de roupa com clareza - A linha de privacidade é apresentada ao lado do botão (a fotografia é utilizada apenas para a simulação de experimentação e não é guardada)
- Créditos recarregados. Enviamos automaticamente um e-mail ao titular da conta quando o saldo desce para 10% do valor da última compra (no mínimo 20 créditos)
- Uma chave de produção distinta da chave de teste, cada uma com o limite de crédito mensal que desejar
Idempotency-Keyenviado em cada tentativa de experimentação eX-Request-Idregistado em caso de erros
Cronologia
Uma equipa da Hydrogen demora normalmente entre 1 a 2 semanas a implementar um projeto-piloto: um dia para adicionar a chave e testar em modo de simulação, dois ou três dias para a rota e o botão da página do produto, e o resto para o controlo de qualidade em produtos reais e uma implementação gradual.
As lojas também
Também têm lojas físicas? O quiosque na loja permite experimentar roupa num ecrã ou num espelho inteligente, incluindo a possibilidade de os clientes segurarem uma peça de roupa diante da câmara. Utiliza a mesma conta.
Preços
As lojas «Headless» utilizam créditos da API para programadores: são pré-pagos, não expiram e uma experiência de experimentação mal sucedida nunca é cobrada. Consulte os preços. Para grandes volumes ou um projeto-piloto em várias lojas, contacte-nos para obter preços empresariais.
Relacionado
- Gerar uma simulação: todos os campos e respostas
- Erros e limites
- Tarefas assíncronas, lotes e webhooks
- Estado da API e a especificação OpenAPI
- Dados e privacidade e o Acordo de Tratamento de Dados