Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Varejo. Para usar a pesquisa de varejo na fase GA restrita, entre em contato com a equipe de vendas do Cloud.

Se você estiver usando apenas o Recommendations AI, permaneça no Console do Recommendations e consulte a documentação do Recommendations AI.

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 a configuração está funcionando conforme o esperado.

Primeiro, crie uma configuração de exibição para o Recommendations AI.

Para visualizar as recomendações retornadas pela configuração de veiculação:

  1. Acesse a página "Avaliar varejo" no Console do Google Cloud.

    Acessar a página "Avaliar"

  2. Selecione a configuração de veiculação que você quer visualizar.

  3. Insira um ID de visitante para visualizar as recomendações do usuário.

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

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 SERVING_CONFIG_ID pela configuração de exibição em que você usará as previsões. Saiba mais

  • 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/SERVING_CONFIG_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.

Java

public static PredictResponse predictWithNextPageToken(UserEvent userEvent, int pageSize,
    String nextPageToken)
    throws IOException, InterruptedException {
  PredictionServiceClient predictionClient = getPredictionServiceClient();

  PredictRequest request = PredictRequest.newBuilder()
      .setPlacement(HOME_PAGE_PLACEMENT_NAME)
      .setUserEvent(userEvent)
      .setPageSize(pageSize)
      .setPageToken(nextPageToken)
      .setValidateOnly(true)
      .build();

  PredictResponse response = predictionClient.predict(request);

  predictionClient.shutdownNow();
  predictionClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

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 uma configuração de exibição no Console do Cloud, essa configuração se aplica a todas as recomendações exibidas por essa configuração, sem que você precise realizar mais ações de dados.

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 da configuração 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 uma configuração de exibição no Console do Cloud, essa configuração se aplica por padrão a todas as recomendações veiculadas por essa configuração, sem precisar realizar mais ação.

Se você precisa controlar a diversidade de uma recomendação específica, use a API Retail usando o campo PredictRequest.params. Isso substitui qualquer configuração de diversificação no nível da configuração que se aplicaria a essa recomendação. Veja 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"