Search docs

Search the TryOnCloud API docs

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 temasLoja «Headless» (da Hydrogen)
MontraTema do ShopifyA tua aplicação React no Oxygen
Como se adiciona a funcionalidade de experimentaçãoInstale a aplicação Shopify e adicione o blocoUma rota de servidor e um componente
FaturaçãoPlano do Shopify, na sua fatura do ShopifyCréditos da API para programadores, pré-pagos
GuiaShopifyEsta página

Como funciona

Shopper browser
Your Hydrogen route

POST /api/try-on (photo + product image URL)

▶

POST /api/v1/generate (X-API-KEY)

◀

200 image/png

◀

200 image/png

◀
  1. O cliente clica em Experimentar na página de um produto e tira ou carrega uma fotografia.
  2. O navegador envia a fotografia e o URL da imagem do produto para a tua rota do Hydrogen.
  3. A sua rota chama o TryOnCloud com a sua chave secreta e recebe a imagem finalizada, normalmente em cerca de 20 segundos.
  4. 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:

bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here

Para 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:

ts
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.

ts
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).

Nota: Uma experiência demora cerca de 20 segundos. Mantenha o pedido aberto e não defina um tempo de espera mais curto para esta rota. As experiências que falharem são reembolsadas automaticamente.

4. Adicionar o botão à página do produto

Crie o ficheiro app/components/TryOnButton.tsx:

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:

tsx
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:

ts
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

  1. 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.
  2. Experimente alguns produtos: tops, vestidos, saris, conjuntos de kurta e calças.
  3. Experimente utilizar uma fotografia demasiado grande e um ficheiro que não seja de imagem, e verifique as mensagens de erro.
  4. Remova ?mock=true e 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:

NecessidadeComo
Separação entre a fase de preparação e a fase de produçãoCrie 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óveisEnvie 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 auditoriaCada 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 clientesEnvie 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 popularesA 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álogoCrie 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áfego300 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çãoTaxa de sucesso e velocidade em tempo real em /status; utilização por chave no Generations (pesquisa, exportação para CSV).
Geradores de clientesEspecificaçã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=true removido da rota
  • blob: adicionado a imgSrc
  • As imagens dos produtos provêm de cdn.shopify.com e 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-Key enviado em cada tentativa de experimentação e X-Request-Id registado 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