Tokens de atribuição

Os tokens de atribuição são IDs exclusivos gerados pela Vertex AI para Pesquisa de comércio e retornados com cada solicitação de pesquisa. Eles permitem que a Vertex AI para Pesquisa no comércio associe uma solicitação de pesquisa ao evento de pesquisa correspondente, o que permite que os modelos de reclassificação melhorem a qualidade das respostas de pesquisa. Os tokens de atribuição também são necessários nos eventos de pesquisa da Vertex AI para Pesquisa no comércio para gerar relatórios precisos.

Como os tokens de atribuição funcionam

Você coleta o attributionToken da resposta da API da pesquisa de um usuário. Envie de volta o token gerado pelo visitante dessa interação específica nos eventos do usuário.

Comportamento do token de atribuição

Os tokens de atribuição são:

  • Específico do visitante: o attributionToken é associado a uma resposta de pesquisa específica enviada para um visitorId específico. Portanto, o token que você recebeu na resposta a uma pesquisa feita por visitorId 'A' precisa ser enviado de volta com os eventos subsequentes originados do mesmo visitorId 'A' que são uma consequência direta dessa pesquisa.

  • Associado a eventos diretamente após a pesquisa: o attributionToken é particularmente importante para eventos de usuário que representam uma interação direta com os resultados da pesquisa específica.

    Isso inclui:

    • Eventos de pesquisa subsequentes: se o mesmo usuário fizer outra pesquisa logo após a inicial (como refinar a consulta), o attributionToken da primeira resposta de pesquisa precisa ser incluído no evento do usuário para a segunda pesquisa, se ela for uma continuação da primeira.
    • Eventos de visualização da página de detalhes: quando o usuário clica em um produto nos resultados da pesquisa e visualiza os detalhes dele, o attributionToken da resposta da pesquisa que continha esse produto precisa ser incluído no evento de visualização da página de detalhes do usuário. Isso geralmente é feito transmitindo o attributionToken como um parâmetro de URL para a página do produto.
    • Eventos de adição ao carrinho: se o usuário adicionar um produto ao carrinho diretamente dos resultados da pesquisa ou depois de conferir os detalhes de um produto encontrado nessa pesquisa, o attributionToken da resposta de pesquisa de origem vai ser incluído no evento add-to-cart.
    • Eventos de compra concluída: se ocorrerem interações intermediárias já atribuídas, como ações detail-page-views ou add-to-cart, o attributionToken não será enviado com o evento purchase-complete. A compra ainda está vinculada pelos IDs de produtos e visitorId.

  • Facilitação do mapeamento de eventos de pesquisa e solicitações: incluir o attributionToken em eventos de usuário subsequentes é crucial para mapear com precisão o comportamento do usuário de volta ao pedido de pesquisa específico e aos resultados veiculados pela Vertex AI para Pesquisa no comércio.

    Essa vinculação permite que a Vertex AI para Pesquisa entenda:

    • Quais consultas e resultados de pesquisa geraram engajamento do usuário (cliques, visualizações, adições ao carrinho, compras).
    • A relevância e a eficácia da classificação da pesquisa.
    • Se é necessário gerar exemplos positivos e negativos para treinar o modelo de classificação.
    • Como calcular métricas por pesquisa, como taxa de cliques (CTR), taxa de conversão (CVR) e receita por pesquisa.
    • Como atribuir conversões à pesquisa específica que as gerou, especialmente em cenários de teste A/B.

Tokens de atribuição na API Search

Cada resposta retornada pelo método de pesquisa para comércio da Vertex AI inclui um attributionToken exclusivo no final do corpo da resposta da pesquisa. Exemplo:

{
  "results": [
    {
      "id": "727121",
      "product": {
…
     }
  ],
  "totalSize": 19600,
  "attributionToken": "dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB",
  "nextPageToken": "AM1MDZiNWOyQjM4UTLlNGN50iMwYjMtADMwATLwIGMhBzY2YDJaIw-bCbxQYAt1PJgIwgExEgC"
…

Esse token precisa ser incluído no evento de pesquisa seguinte:

{
"eventType": "search",
"searchQuery":"red t-shirt", 
"productDetails":[
  {"product":{"id":"727121"}}, {"product":{"id":  …
  }
] ,
"visitorId":"GA1.1.1383176924.1721324981",
"attributionToken":"dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB"
}

A Vertex AI Search para comércio usa os dados de eventos para treinar os modelos. O token de atribuição oferece uma maneira de vincular o evento à solicitação, codificando a solicitação e a resposta de pesquisa completa com os filtros, facetas e IDs de produtos de resposta solicitados. Sem um token presente nos eventos de pesquisa, eles são tratados como se não fossem da Pesquisa da Vertex AI do Google e podem ser usados incorretamente como se fossem de outro provedor de pesquisa.

É normal (e esperado) ter eventos de pesquisa sem tokens se eles forem veiculados por outro provedor de pesquisa, durante um experimento A/B, por exemplo. No entanto, normalmente há um mapeamento 1:1 para as solicitações da API de pesquisa para pesquisar eventos com tokens.

Efeito adverso de tokens ausentes

Se o attributionToken não estiver nos eventos de usuário subsequentes relevantes do mesmo visitante, a Vertex AI para Pesquisa para Commerce vai tratar esses eventos como se não tivessem origem no serviço de pesquisa.

Isso pode gerar:

  • Treinamento de modelo impreciso.
  • Métricas e análise de desempenho incorretas.
  • Possíveis problemas para alcançar níveis de performance mais altos (como o Nível 3), que exigem eventos atribuíveis suficientes.
  • Erros informados no Painel de qualidade de dados na Pesquisa para comércio se a porcentagem de eventos com tokens de atribuição for inferior a 95%.

Para aprender com o comportamento do usuário e otimizar os resultados da pesquisa, a Vertex AI para Pesquisa para Commerce precisa de uma atribuição precisa. Verifique se o attributionToken de uma resposta de pesquisa está associado ao visitante específico que fez a pesquisa. Ele precisa estar nos eventos do usuário da interação de pesquisa gerada, especialmente nos eventos search, detail-page-view e add-to-cart.

Qualidade dos dados do token de atribuição

O Painel de qualidade de dados no console de Pesquisa para comércio vai mostrar um Status de erro crítico ou de não conformidade de bloqueio se a porcentagem de eventos com tokens de atribuição for inferior a 95%. Caso contrário, o Status vai aparecer como "Em conformidade":

Texto alternativo

A qualidade dos dados no nível 3, que é o modelo otimizado para receita, geralmente não é treinado sem eventos atribuíveis suficientes. Não é recomendável implantar a Vertex AI para Pesquisa para Commerce na produção, a menos que ela esteja exibindo resultados nos níveis 3 ou 4. Para mais informações, consulte a seção "Qualidade de dados" sobre como destravar níveis de performance na página Qualidade de dados desta documentação.

Tokens de atribuição para recomendações

Como não há um evento de usuário específico para recomendações, não inclua tokens de atribuição de respostas predict em nenhum evento. No entanto, é altamente recomendável incluir o PredictResponse.attribution_token em eventos de usuário subsequentes resultantes de uma recomendação (como detail-page-view ou add-to-cart).

A implementação exige a transmissão do token de atribuição do produto recomendado em um parâmetro de URL para o URL da página do produto. Em seguida, use esse parâmetro para preencher o campo attributionToken do evento do usuário correspondente.

As recomendações da Vertex AI para Pesquisa criam automaticamente tokens sintéticos para eventos atribuíveis a solicitações predict. Adicionar os tokens explicitamente pode melhorar um pouco a precisão dos relatórios de análise. No entanto, isso não é estritamente necessário e terá pouco impacto nos modelos de recomendações.