Esta é a documentação apenas do Recommendations AI. Para testar a pesquisa de varejo e o console unificado de varejo na fase restrita do GA, entre em contato com a equipe de vendas do Cloud. Se você não quiser usar a pesquisa de varejo, permaneça no console de recomendações até novo aviso.

Se você estiver usando a versão v1beta do Recommendations AI, migre para a versão da API Retail.

Como receber recomendações

Nesta página, descrevemos como solicitar recomendações para um usuário e um evento de usuário específicos.

Depois de fazer upload dos produtos e registrar eventos do usuário, é possível solicitar recomendações de produtos para usuários específicos com base nos eventos registrados e na atividade atual deles.

Antes de começar

Para conseguir acessar a API Recommendations AI, você precisa criar um projeto do Google Cloud e configurar a autenticação seguindo as etapas em Antes de começar.

Para conseguir solicitar previsões à Recommendations AI, você precisa de um modelo de recomendação treinado e ajustado, além de uma ou mais colocações ativas.

Visualização da recomendação

Antes de atualizar o código do site para solicitar recomendações, use a visualização de previsão para confirmar se o modelo está funcionando conforme o esperado.

Para visualizar as recomendações retornadas pelo modelo:

  1. Acesse a página "Modelos de Recommendations AI" no Console do Google Cloud.
    Acesse a página Modelos de Recommendations AI.

  2. Clique no nome do modelo para abrir a página de detalhes.

  3. Clique na veiculação que você quer visualizar.

  4. (Opcional) Digite um ID do usuário para visualizar os resultados.

  5. Clique em Visualização da previsão para conferir os resultados.

Visualização da previsão com imagens de amostra retornadas

Como receber uma recomendação

Para detalhes sobre custos de previsão, consulte Preços.

curl

Para receber uma recomendação, faça uma solicitação POST para o método REST predict e forneça o corpo da solicitação apropriado:

  • A conta de serviço usada precisa ter a função "Visualizador de varejo" ou superior.

  • Substitua a colocação PLACEMENT_ID por outra em que você usará as previsões. [Saiba mais][canais].

  • Se você importou os eventos do usuário do Google Analytics 360 usando o BigQuery, defina visitorId como o ID do cliente do Google Analytics. Consulte a documentação do Google Analytics para saber como conseguir o ID do cliente.

  • Se você estiver executando um experimento A/B, defina experimentIds como o ID desse grupo. Saiba mais

  • Forneça um objeto de evento do usuário para as ações do usuário iniciadas com a solicitação de recomendação.

    Saiba que esse evento de usuário não é registrado, ele é usado apenas para fornecer contexto sobre a solicitação de recomendação. Você também precisa gravar o evento de usuário da mesma forma que grava outros eventos do usuário na API Retail.

  • Como opção, forneça um filtro para restringir os produtos em potencial retornados. Saiba mais.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data  '{
          "filter": "FILTER_STRING",
          "validateOnly": false,
          "userEvent": {
              "eventType": "detail-page-view",
              "visitorId": "VISITOR_ID",
              "userInfo": {
                  "userId": "USER_ID",
                  "ipAddress": "IP_ADDRESS",
                  "userAgent": "USER_AGENT"
              },
              "experimentIds": "EXPERIMENT_GROUP",
              "productDetails": [{
                  "product": {
                    "id": "PRODUCT_ID"
                 }
              }]
          }' \
https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/placements/PLACEMENT_ID:predict

Os resultados serão semelhantes aos exibidos abaixo:

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "attribution_token": "sample-atr-token"
}

Você precisa associar o valor attribution_token a qualquer URL exibido como resultado dessa previsão e retorná-lo aos eventos do usuário para esses URLs. Saiba mais.

Reclassificação de preços

A reclassificação de preços organiza, por ordem decrescente de preço, os itens recomendados do catálogo que têm probabilidade similar de serem pedidos. A relevância ainda é usada para solicitar itens. Portanto, ativar a reclassificação de preços não é o mesmo que classificar por preço.

A reclassificação de preços pode ser definida no nível da configuração ou por solicitação de previsão.

Quando você escolhe uma configuração de reclassificação de preços ao criar um modelo no Console do Cloud, essa configuração se aplica a todas as recomendações veiculadas por essa configuração, sem que você precise realizar qualquer outra ação.

Se você precisar controlar a reclassificação de preços de uma recomendação específica, use a API Retail usando o campo PredictRequest.params. Isso substitui qualquer configuração de reclassificação no nível do modelo que se aplicaria a essa recomendação.

Diversidade de recomendações

A diversificação afeta se os resultados retornados de uma única solicitação de previsão são de categorias diferentes do seu catálogo de produtos.

A diversificação pode ser definida no nível da configuração de exibição ou por solicitação de previsão.

Quando você escolhe uma configuração de diversificação ao criar um modelo no Console do Cloud, essa configuração se aplica por padrão a todas as recomendações exibidas por esse modelo, sem precisar realizar outras ações de dadoss

Se você precisa controlar a diversidade de uma recomendação específica, use a API Retail para usar o campo PredictRequest.params. Isso substitui qualquer configuração de diversificação de nível de modelo que se aplicaria a essa recomendação. Consulte a documentação da API para PredictRequest.params para ver os valores aceitos.

Como usar filtros de recomendação

É possível filtrar as recomendações retornadas pelo Recommendations AI usando o campo filter no método predict.

O campo filter aceita duas formas de especificação de filtro:

  • Expressões de tag

    Se você adicionou valores tag aos seus produtos no momento do upload, pode especificar que apenas os produtos que corresponderem a todas as tags filtradas serão retornados como recomendações. Saiba mais

    As expressões de tag podem conter os operadores booleanos OR ou NOT, que precisam ser separados dos valores de tag por um ou mais espaços. Os valores de tag também podem ser precedidos por um traço (-) imediatamente, o que equivale ao operador NOT. As expressões de tag que usam os operadores booleanos precisam ser colocadas entre parênteses.

  • filterOutOfStockItems

    A sinalização filterOutOfStockItems filtra todos os produtos com stockState de OUT_OF_STOCK.

É possível combinar esses dois tipos de filtro: Somente itens que atendam a todas as expressões de filtro especificadas são retornados.

Alguns exemplos de strings de filtro:

"filter": "tag=\"spring-sale\""
"filter": "filterOutOfStockItems"
"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

O exemplo a seguir retorna somente itens que estão em estoque com a tag `spring-sale` ou `unique` (ou ambas) e não têm a tag `items-to-exclude`.

"filter": "tag=(\"spring-sale" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"