# dfgoogletryon: módulo de prova virtual com IA (Google Vertex AI)

> Apresentação O dfgoogletryon acrescenta um widget de prova virtual às suas fichas de produto PrestaShop 8 e 9. O cliente carrega uma foto (ou usa a sua câmara) e vê-se…

- Página: <https://www.datafirefly.com/pt/documentation/dfgoogletryon/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfgoogletryon/index.md), [en](https://www.datafirefly.com/en/documentation/dfgoogletryon/index.md), [es](https://www.datafirefly.com/es/documentation/dfgoogletryon/index.md), [de](https://www.datafirefly.com/de/documentation/dfgoogletryon/index.md), [it](https://www.datafirefly.com/it/documentation/dfgoogletryon/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfgoogletryon/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgoogletryon/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Apresentação

O dfgoogletryon acrescenta um widget de prova virtual às suas fichas de produto PrestaShop 8 e 9. O cliente carrega uma foto (ou usa a sua câmara) e vê-se a vestir a peça da ficha, graças ao modelo generativo **Google Vertex AI Virtual Try-On**. Todas as chamadas à Google são feitas por proxy do lado do servidor: a chave da conta de serviço nunca chega ao navegador. O módulo integra o consentimento RGPD, o não armazenamento das fotos, a marca de água SynthID e salvaguardas contra custos excessivos.

Os textos do widget (botão « Try it on », « Generate try-on », mensagens de limite) e o texto de consentimento por defeito são fornecidos em inglês e francês. Numa loja em português, traduza as cadeias em Internacional → Traduções → Traduções dos módulos instalados e reescreva o texto de consentimento em português na configuração, com menção à transferência da foto para a Google.

## Em que é que difere do try-on do Google Shopping?

A Google propõe duas coisas distintas, que não devem ser confundidas:

- **A prova de vestuário do Merchant Center**: um badge que aparece apenas na pesquisa Google e no Google Shopping. _Não_ é integrável na sua loja e não oferece nenhuma API para a sua ficha de produto.
- **Vertex AI Virtual Try-On**: a API generativa que este módulo usa. É a única peça que permite um widget de prova diretamente nas suas páginas de produto.

O dfgoogletryon assenta exclusivamente no Vertex AI. É um serviço generativo **pago à imagem**: cada prova gera uma ou várias imagens faturadas pela Google.

## Pré-requisitos

- PrestaShop 8.0 a 9.x
- PHP 8.1, 8.2, 8.3 ou 8.4
- Extensões PHP: `curl`, `openssl`, `gd`
- Um projeto **Google Cloud** com a faturação ativada
- A **API Vertex AI** ativada nesse projeto
- Uma **conta de serviço** com o papel _Utilizador do Vertex AI_ e a sua chave JSON

## Passo 1: preparar o Google Cloud

1. Abra [console.cloud.google.com](https://console.cloud.google.com) e crie (ou selecione) um projeto. Anote o seu **ID de projeto**.
2. Ative a **faturação** no projeto (menu Faturação).
3. Ative a **API Vertex AI**: procure « Vertex AI API » (`aiplatform.googleapis.com`) na biblioteca de APIs e clique em Ativar.

## Passo 2: criar a conta de serviço

1. Vá a **IAM e administração > Contas de serviço**.
2. Clique em **Criar uma conta de serviço** e dê-lhe um nome (por exemplo `tryon-prestashop`).
3. Atribua-lhe o papel **Utilizador do Vertex AI** (`roles/aiplatform.user`).
4. Depois de criada, abra-a, separador **Chaves > Adicionar uma chave > Criar uma chave > JSON**. O ficheiro JSON é descarregado.

Esta chave JSON dá acesso ao Vertex AI em seu nome. Nunca a publique nem a coloque num repositório público. O módulo conserva-a do lado do servidor e nunca a expõe ao front-office.

## Passo 3: instalar o módulo

1. Descarregue `dfgoogletryon.zip` a partir da sua conta de cliente.
2. No back-office PrestaShop: **Módulos > Gestor de módulos > Adicionar um novo módulo**.
3. Carregue o ZIP e clique em **Instalar**.
4. Na instalação, o módulo regista as suas definições por defeito e um texto de consentimento, e liga-se aos hooks `displayProductAdditionalInfo` (botão na ficha) e `actionFrontControllerSetMedia` (carregamento dos assets, apenas na página de produto).

## Passo 4: configurar o módulo

Abra a configuração do módulo. Preencha a secção **Google Cloud / Vertex AI**:

- **GCP Project ID**: o ID de projeto anotado no passo 1.
- **Region**: a localização Vertex AI, por exemplo `us-central1`.
- **Model ID**: por defeito `virtual-try-on-preview-08-04` (pode também usar `virtual-try-on-001`).
- **Service-account JSON key**: cole o conteúdo integral do ficheiro JSON descarregado no passo 2.

Clique depois em **Save & test authentication**. O módulo assina um JWT, obtém um token OAuth e confirma « Authentication OK » se tudo estiver correto.

O token OAuth é guardado em cache durante cerca de 55 minutos para evitar regenerá-lo a cada prova. Qualquer alteração das credenciais invalida automaticamente a cache.

## Definições de geração e de segurança

Secção **Generation & safety**:

- **Images per try-on**: de 1 a 4 imagens geradas por prova. Cada imagem é faturada pela Google.
- **SynthID watermark**: acrescenta uma marca de água de IA invisível às imagens geradas (recomendado).
- **Safety setting**: nível de filtragem (`block_low_and_above`, `block_medium_and_above`, `block_only_high`, `block_none`). `block_medium_and_above` por defeito.
- **Person generation**: `allow_adult` recomendado para uma loja de pronto-a-vestir.
- **Max generations per session**: limite anti-abuso por sessão de cliente.
- **Cooldown between generations (seconds)**: intervalo mínimo entre duas provas de uma mesma sessão.

Secção **Display**:

- **Enable widget**: ativa ou desativa o widget globalmente.
- **Restrict to category IDs**: lista de IDs de categorias separados por vírgulas. Deixe vazio para mostrar em todos os produtos, ou preencha as suas categorias de vestuário para só mostrar o widget onde faz sentido.
- **Consent text (GDPR)**: o texto apresentado ao lado da caixa de consentimento obrigatória.

## Funcionamento do lado do cliente

1. Na ficha de produto elegível, aparece um botão **Try it on**.
2. O cliente abre a janela modal, carrega uma foto (JPEG, PNG ou WebP) ou captura a partir da sua webcam.
3. A foto é redimensionada no navegador (máx. 1024 px, JPEG) antes do envio, para reduzir a latência e o custo.
4. O cliente marca a caixa de consentimento e clica em **Generate try-on**.
5. O módulo transmite a foto e a imagem de capa do produto ao Vertex AI e mostra depois a ou as imagens geradas.

## Privacidade e RGPD

A foto do cliente é processada em memória e transmitida à Google para a geração, mas **nunca** é gravada no sistema de ficheiros nem na base de dados da loja. A caixa de consentimento, obrigatória e personalizável, aparece antes de qualquer envio. Adapte o texto de consentimento à sua política de privacidade e mencione a transferência para a Google (dados biométricos potenciais, transferência para fora da UE consoante a região Vertex AI escolhida: a CNPD é a autoridade de controlo competente em Portugal).

## Controlo dos custos

Cada imagem gerada é faturada pela Google segundo a tarifação Vertex AI por imagem. Para manter custos previsíveis:

- Limite **Images per try-on** a 1 se estiver a começar.
- Fixe um **Max generations per session** razoável (5 por defeito).
- Use um **Cooldown** para evitar o spam de geração.
- Restrinja a apresentação às categorias de vestuário através de **Restrict to category IDs**.

Um token por produto e a verificação same-origin desencorajam a utilização do proxy fora das suas páginas. Não é uma autenticação forte, mas uma salvaguarda de custos combinada com os limites acima.

## Boas práticas para a imagem do produto

O módulo envia a **imagem de capa** do produto como referência da peça. A qualidade da prova é muito melhor com um packshot limpo da peça (fundo neutro, peça bem visível) do que com uma foto lifestyle já vestida por um modelo. As partes de cima, partes de baixo e peças únicas (vestidos) dão os melhores resultados.

## Resolução de problemas

- **« Authentication failed » no teste**: verifique o ID de projeto, a validade da chave JSON, a ativação da API Vertex AI e o papel Utilizador do Vertex AI da conta de serviço.
- **Nenhuma imagem gerada**: o pedido pode ter sido filtrado pelas definições de segurança. Experimente outra foto ou alivie o **Safety setting**. Verifique também o saldo de faturação do Google Cloud.
- **O botão não aparece**: verifique que **Enable widget** está ativo e que o produto pertence a uma categoria autorizada (campo **Restrict to category IDs**).
- **Erro de rede / timeout**: certifique-se de que o servidor autoriza ligações HTTPS de saída para `oauth2.googleapis.com` e `REGION-aiplatform.googleapis.com`.
- **« You have reached the maximum number of try-ons »**: o limite por sessão foi atingido; é o comportamento esperado. Ajuste **Max generations per session** se necessário.

## Desinstalação

A desinstalação elimina as definições do módulo, incluindo a chave da conta de serviço e o token em cache. Nenhuma foto de cliente é guardada pelo módulo, pelo que não há mais nada a limpar.