Principais pontos
- Trate o ativo original do produto como a fonte de verdade e gere variantes para os canais com base em uma política explícita.
- Separe as saídas para listagem, detalhe, zoom e amostra de cor, pois cada uma tem necessidades diferentes de pixels e carregamento.
- Use identificadores estáveis de produtos e ativos nos caminhos de saída, em vez de nomes de arquivo fornecidos por um navegador.
A mídia de produtos fica cara quando cada canal inventa suas próprias regras de recorte, formato e nomenclatura. Um fluxo útil parte do registro do produto e produz um conjunto pequeno e deliberado de derivados cujos caminhos, metadados e ciclo de vida podem ficar sob responsabilidade do sistema de e-commerce.
O que mais importa
- Mantenha o estado de aprovação e do catálogo na aplicação de e-commerce, enquanto a Transloadit informa o estado do processamento e da exportação.
- Meça os bytes, o tempo de processamento, a taxa de falhas e a qualidade visual por canal antes de adicionar mais variantes.
Defina o contrato de mídia de produto
Comece pelos locais de exibição, em vez das operações. Um card de listagem, uma página de detalhes do produto, um visualizador com zoom, uma amostra de cor, um email, um feed de marketplace e um vídeo de produto têm, cada um, um tamanho de exibição, uma política de recorte, um requisito de formato e um orçamento de desempenho diferentes. Documente esses requisitos antes de escolher os Steps para que o Template expresse uma regra de produto, em vez de um amontoado de transformações.
Mantenha o catálogo de produtos como fonte de referência para SKU, localidade, aprovação e publicação. O pipeline de processamento deve receber uma identidade estável do ativo e retornar derivados verificados. Essa divisão permite que o sistema de e-commerce decida se um produto está pronto, enquanto a Transloadit se concentra em operações repetíveis com arquivos.
Nomeie cada local de exibição
Registre as dimensões, a proporção, a política de recorte, o formato, a qualidade e o limite máximo de bytes para cada canal.
Versione o original
Use uma versão do ativo controlada pela aplicação para que uma nova sessão de fotos não possa sobrescrever inesperadamente um derivado publicado.
Defina um orçamento
Meça os bytes e o custo de processamento antes de adicionar outro ponto de quebra ou outra variante para marketplace.
Crie derivados com limites definidos
Um fluxo comum aceita o original, valida esse original, cria imagens para listagem e detalhe, prepara um derivado maior para zoom quando isso se justifica e codifica o vídeo de produto separadamente. Mantenha a exportação do original disponível para reprocessamento, mas não faça com que todas as páginas carreguem o original. No exemplo, zoom: false impede a ampliação além das dimensões solicitadas. Use o menor derivado que preserve os detalhes desejados do produto no local de exibição.
O recorte precisa de uma política explícita. Um recorte central é previsível, mas pode cortar parte de um produto; a gravidade baseada em atenção ou entropia pode ajudar em algumas imagens; use /image/facedetect quando forem necessárias coordenadas de rostos e, ainda assim, faça uma revisão em catálogos de alto valor. Armazene a política de recorte e a versão do original junto ao registro do derivado para que seja possível explicar uma diferença visual posteriormente.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 104857600
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"accepted_image": {
"use": ":original",
"robot": "/file/filter",
"accepts": [["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]],
"error_on_decline": true
},
"listing": {
"use": "accepted_image",
"robot": "/image/resize",
"width": 640,
"height": 640,
"resize_strategy": "fit",
"zoom": false,
"format": "webp",
"quality": 82,
"result": true
},
"detail": {
"use": "accepted_image",
"robot": "/image/resize",
"width": 1600,
"height": 1600,
"resize_strategy": "fit",
"zoom": false,
"format": "webp",
"quality": 86,
"result": true
},
"original_export": {
"use": "accepted_image",
"robot": "/s3/store",
"credentials": "catalogue-media",
"path": "catalog/${fields.product_id}/${fields.asset_version}/original-${unique_prefix}.${file.ext}",
"acl": "bucket-default",
"result": true
},
"listing_export": {
"use": "listing",
"robot": "/s3/store",
"credentials": "catalogue-media",
"path": "catalog/${fields.product_id}/${fields.asset_version}/listing.webp",
"acl": "bucket-default",
"result": true
},
"detail_export": {
"use": "detail",
"robot": "/s3/store",
"credentials": "catalogue-media",
"path": "catalog/${fields.product_id}/${fields.asset_version}/detail.webp",
"acl": "bucket-default",
"result": true
}
}
}Listagem
Imagens pequenas e de carregamento rápido para grades e resultados de busca, com dimensões que correspondam ao layout do card.
Detalhe
A visualização principal do produto, com resolução suficiente para a página, mas sem transferir desnecessariamente o volume de dados de uma imagem no tamanho original.
Zoom e vídeo
Gere essas saídas somente quando a experiência precisar delas e defina uma política própria de carregamento e armazenamento para elas.
Mantenha o roteamento e os caminhos confiáveis
Os caminhos de saída fazem parte do contrato do catálogo. Construa esses caminhos a partir de identificadores de produto e de uma versão validada do ativo, autorizada pela sua aplicação, e depois grave os metadados dos resultados no sistema de e-commerce. Não deixe que um nome de arquivo ou campo fornecido pelo navegador determine onde o derivado de outro locatário será armazenado ou a qual SKU ele pertence.
Assinar params.fields no servidor não protege esses caminhos quando um navegador envia a requisição. Os campos de formulário multipart também se tornam campos da Assembly e não são cobertos pela assinatura, e um campo enviado após params substitui o valor assinado de mesmo nome. O navegador controla essa ordem. Como o exemplo grava os nomes fixos listing.webp e detail.webp sob ${fields.product_id} e ${fields.asset_version}, uma requisição enviada pelo navegador poderia sobrescrever os derivados de outro produto. Faça com que o servidor da aplicação monte e envie a requisição inteira da Assembly, incluindo o upload e valores não vazios, autorizados e seguros para uso em caminhos para product_id e asset_version, e não encaminhe campos arbitrários do cliente.
Aplique a mesma regra aos outros campos dinâmicos. Mantenha as dimensões fixas no Template ou use um Template para cada conjunto aprovado de variantes; os campos da requisição sobrescrevem os campos definidos no Template, portanto, somente o servidor deve fornecê-los. Salvar allow_steps_override: false no Template estabelece um limite separado: impede substituições de Steps em tempo de execução ao usar template_id, mas não autoriza os valores dos campos. Ainda vale a pena verificar as chaves de armazenamento retornadas em relação ao prefixo esperado antes da publicação no catálogo, mas isso não pode desfazer uma sobrescrita na chave errada, portanto, proteja a própria gravação.
Use caminhos estáveis
Inclua um identificador de produto e a versão do ativo e substitua o ponteiro do catálogo somente após verificar a exportação.
Limite as opções
Permita dimensões e variantes conhecidas, em vez de parâmetros arbitrários de transformação enviados pelo navegador.
Proteja as credenciais
Mantenha as credenciais de armazenamento nas credenciais de Template e seu Auth Secret da Transloadit no servidor que envia a Assembly.
Publique a partir de eventos verificados
Um webhook informa à aplicação que uma Assembly mudou de estado; isso, por si só, não torna um produto apto para publicação. Verifique o webhook, obtenha o resultado confiável da Assembly, confira se cada derivado exigido existe com as dimensões e o tipo MIME esperados e só então atualize o registro do catálogo.
As notificações podem ser duplicadas, chegar com atraso ou não chegar. O código de tratamento deve poder ser executado duas vezes com segurança, tolerar eventos que chegam fora de ordem e reconciliar um evento ausente por meio de consultas à API ou de uma verificação periódica de status. Isso evita que uma falha na exportação deixe um produto apontando para um conjunto de imagens gerado pela metade.
Verifique
Verifique as assinaturas, a identidade da Assembly, os caminhos de saída, as dimensões, os tipos MIME e a quantidade esperada de variantes.
Atualize de forma idempotente
Use o ID do produto e a versão do ativo como chave de gravação para que uma nova tentativa não possa duplicar um registro do catálogo nem fazê-lo regredir a um estado anterior.
Reconcilie
Use consultas de status ou uma tarefa de reparo para eventos que chegam com atraso, são duplicados ou nunca são observados.
Meça antes de ampliar o conjunto de variantes
Registre as dimensões dos derivados, o tamanho em bytes, o tempo de processamento, as falhas e os resultados da revisão visual por local de exibição. Compare essas medições com o desempenho da página e as metas de conversão antes de adicionar outro ponto de quebra, formato ou ramificação para marketplace.
Um contrato pequeno que corresponda aos locais reais de exibição é mais fácil de armazenar em cache, migrar e reparar do que uma matriz gerada especulativamente para todo o catálogo. Mantenha a origem e a versão do ativo para que uma alteração posterior de política possa ser reproduzida a partir da mesma entrada.
Meça os bytes
Compare os tamanhos de derivados representativos com os limites de transferência pela rede e de decodificação de cada local de exibição.
Revise a qualidade
Inspecione os recortes e a compressão em produtos representativos antes de incluir um derivado na publicação.
Lance com um Template testado da Transloadit
O exemplo deste guia aceita no máximo uma imagem, cria dois derivados com limites deliberadamente definidos e exporta o original aceito e cada derivado sob uma chave versionada distinta. Seu filtro encaminha apenas os tipos MIME JPEG, PNG e WebP e faz a Assembly falhar para qualquer outro tipo. Todas as exportações ocorrem depois desse filtro no fluxo, portanto um upload recusado não é exportado para o S3. O roteamento por MIME não é uma verificação rigorosa do conteúdo; valide os bytes armazenados na sua aplicação se o seu contrato exigir isso. Teste imagens de produtos representativas e depois ajuste as dimensões, a política de recorte, a qualidade e a retenção com base nos requisitos medidos dos canais antes de adicionar ramificações para zoom ou vídeo.
Crie uma conta na Transloadit e salve as Assembly Instructions como um Template. Crie uma credencial de Template para S3 chamada catalogue-media com key, secret, bucket e bucket_region; consulte credenciais de Template para configurar. Mantenha o bucket privado com Block Public Access ativado; acl: "bucket-default" omite uma ACL de objeto e depende da política de acesso do bucket, portanto não torna os objetos privados por si só. Configure seu servidor de e-commerce para enviar a Assembly com valores autorizados tanto para o ID do produto quanto para a versão do ativo, verifique se cada derivado esperado existe no caminho versionado esperado, registre o resultado de forma idempotente e atualize o catálogo somente após a conclusão da exportação. Consulte os preços da Transloadit quando estiver na hora de estimar o processamento e o armazenamento para seu catálogo.
Salve a configuração de exemplo
Mantenha o grafo de processamento e as credenciais de armazenamento em um Template salvo, em vez de reconstruir os Steps no navegador.
Publique após a verificação
Use os resultados verificados da Assembly e o estado de aprovação do seu catálogo como condição para liberar cada versão do ativo.
Detalhes técnicos que vale a pena conhecer
- Uma imagem maior não é automaticamente um ativo melhor para zoom; as dimensões de saída devem seguir os requisitos reais de exibição e recorte.
- A conversão de formato, o redimensionamento e o recorte podem ser etapas separadas, com diferentes considerações sobre qualidade e falhas.
- As notificações podem ser duplicadas e seu envio só é tentado novamente algumas vezes, portanto a aplicação de e-commerce precisa de verificação de assinaturas, tratamento idempotente dos resultados e reconciliação de eventos ausentes.
- O armazenamento de propriedade do cliente continua sendo o sistema de registro dos arquivos exportados quando um fluxo usa um Robot /s3/store ou outro Robot de armazenamento.
- A geração de variantes pode se multiplicar rapidamente entre localidades, canais, pontos de quebra e campanhas; políticas com limites definidos evitam o crescimento combinatório acidental.
- A origem e cada derivado devem ter uma versão estável para que a substituição de uma imagem de produto não possa misturar saídas antigas e novas.
- Uma miniatura de listagem normalmente precisa de menos dados do que um ativo para detalhes ou zoom; enviar o original para todos os locais de exibição desperdiça transferência de dados e trabalho de decodificação.
- Os caminhos de saída devem ser gerados a partir de identificadores de produto confiáveis e de uma versão validada do ativo, em vez de serem interpolados a partir de entradas arbitrárias do cliente.
- Uma Assembly concluída não é o mesmo que um produto publicado. As atualizações do catálogo devem aguardar exportações verificadas e o estado de aprovação da própria aplicação.
- Quando um canal adicionar um novo derivado, atualize o contrato e os testes em vez de alterar silenciosamente todas as saídas existentes.
Uma abordagem prática
- 1
Defina o contrato dos derivados para cada canal antes de escrever o Template.
- 2
Faça com que o servidor de e-commerce envie o original com os campos product_id e asset_version autorizados e preserve o original aceito.
- 3
Gere o conjunto mínimo de saídas para listagem, detalhe, zoom e vídeo necessário aos canais atuais.
- 4
Publique somente depois que a aplicação receber e registrar de forma idempotente um evento completo de exportação.
Quando a Transloadit é útil
Faça seu servidor de e-commerce criar e enviar uma Assembly a partir de um Template que valida, normaliza, cria ramificações e exporta derivados com limites definidos para o armazenamento de sua propriedade. Se as pessoas fizerem upload pelo Uppy ou por outro cliente de navegador, trate isso como uma etapa separada de recebimento que sua aplicação valida antes de o servidor dela enviar esta configuração de exemplo para exportação. Mantenha o SKU, as configurações regionais e os estados de aprovação e publicação na aplicação de e-commerce.
Limite da arquitetura
A Transloadit prepara mídia de produtos e exporta derivados; ela não fornece catálogo de produtos, PIM, DAM, vitrine de loja, interface de aprovação nem serviço de publicação de anúncios em marketplaces.
Perguntas frequentes
A Transloadit substitui um sistema de gestão de informações de produtos (PIM) ou de gestão de ativos digitais (DAM)?
Não. Ela processa arquivos e exporta derivados. Mantenha os atributos dos produtos, as aprovações, os direitos, o estado do catálogo e a descoberta de ativos no sistema responsável por eles.
Quantas variantes uma imagem de produto deve ter?
Comece pelos locais de exibição que você consegue medir: geralmente listagem, detalhe e apenas as saídas de zoom ou de canais que tenham um consumidor real. Adicione variantes quando evidências sobre dispositivos, layouts ou marketplaces justificarem o custo de processamento e armazenamento delas.
O original deve ser público?
Geralmente, não. Mantenha o original em armazenamento controlado e publique apenas os derivados e caminhos necessários para a experiência do produto.
O que acontece quando uma imagem de produto é substituída?
Crie uma nova versão do ativo, processe-a, verifique todas as saídas necessárias e só então altere o ponteiro do catálogo. Retenha ou retire de uso a versão anterior conforme a política da sua aplicação.