Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Retail.

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.

A API Retail retorna uma lista de identificadores de produto classificados. Você é responsável por renderizar os resultados no seu site com imagens e texto.

Nunca armazene em cache os resultados personalizados de um usuário final e nunca retorne resultados personalizados para um usuário final diferente.

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.

Avaliar recomendações

Antes de atualizar o código do seu site para solicitar recomendações, use os resultados da previsão de visualização para confirmar se o modelo e a configuração de exibição estão funcionando conforme o esperado.

Para mais informações sobre configurações de exibição, consulte Configurações de exibição.

É possível visualizar os resultados da configuração de exibição na página Avaliar ou acessando a página Detalhes da configuração de exibição no console e clicando na guia Avaliar. As etapas a seguir mostram como visualizar a página Avaliar.

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

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

    Acessar a página "Avaliar"

  2. Clique na guia Recomendações se ela não estiver selecionada.

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

  4. (Opcional) Digite um ID de visitante para visualizar as recomendações desse usuário.

  5. Se a seção Itens associados for exibida, clique em Adicionar item e insira um ID do produto para receber recomendações associadas a esse item. É possível adicionar vários itens associados.

    Só é possível adicionar itens se o tipo de modelo de configuração de exibição selecionado exigir produtos como entrada para recomendações. Modelos recomendados para você não exigem a inserção de itens associados.

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

Para ver a página Detalhes da configuração de exibição que você está visualizando, clique em Ver configuração de exibição no campo Selecionar configuração de exibição.

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ço ao criar uma configuração de exibição no console, ela se aplica a todas as recomendações exibidas por essa configuração, sem que você precise fazer mais nada.

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, ela é aplicada por padrão a todas as recomendações exibidas por essa configuração, sem que você precise fazer mais nada.

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.

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. Consulte a documentação de referência da API para ver o campo Product.tags[].

    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"

Monitore e resolva problemas de recomendações

Depois de configurar seu site para receber recomendações, recomendamos que você configure alertas. Consulte Configurar um alerta para erros de previsão.

Para resolver erros, consulte Monitorar e resolver problemas.