# Shopify Hydrogen (headless)

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](/docs/shopify) nossa [aplicação](/docs/shopify) do [Shopify](/docs/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](/docs/shopify) | Esta página |

## Como funciona

```flow
Shopper browser -> Your Hydrogen route: POST /api/try-on (photo + product image URL)
Your Hydrogen route -> TryOnCloud API: POST /api/v1/generate (X-API-KEY)
TryOnCloud API --> Your Hydrogen route: 200 image/png
Your Hydrogen route --> Shopper browser: 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:

| 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](/docs/async). |
| 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](/contact) para que possamos planear a capacidade. |
| Monitorização | Taxa de sucesso e velocidade em tempo real em [/status](/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](/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](/docs/kiosk) 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](/pricing#developer-api). Para grandes volumes ou um projeto-piloto em várias lojas, [contacte-nos](/contact) para obter preços empresariais.

## Relacionado

- [Gerar uma simulação](/docs/generate): todos os campos e respostas
- [Erros](/docs/errors) e [limites](/docs/limits)
- [Tarefas assíncronas, lotes e webhooks](/docs/async)
- [Estado da API](/status) e a [especificação OpenAPI](/api/v1/openapi.json)
- [Dados e privacidade](/docs/data-privacy) e o [Acordo de Tratamento de Dados](/dpa)
