Criar uma definição de segmento usando a API do serviço de segmentação

Este documento fornece um tutorial para desenvolver, testar, visualizar e salvar uma definição de segmento usando o Adobe Experience Platform Segmentation Service API.

Para obter informações sobre como criar definições de segmento usando a interface do usuário, consulte o Guia do Construtor de segmentos.

Introdução

Este tutorial requer um entendimento prático dos vários Adobe Experience Platform serviços envolvidos na criação de definições de segmento. Antes de iniciar este tutorial, revise a documentação dos seguintes serviços:

As seções a seguir fornecem informações adicionais que você precisará saber para fazer chamadas com êxito para o Platform APIs.

Leitura de chamadas de API de amostra

Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e conteúdos de solicitação formatados corretamente. Também fornece exemplos de JSON retornado nas respostas da API. Para obter informações sobre as convenções usadas na documentação para chamadas de API de exemplo, consulte a seção sobre como ler chamadas de API de exemplo no Experience Platform guia de solução de problemas.

Coletar valores para cabeçalhos necessários

Para fazer chamadas para Platform APIs, primeiro conclua o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API da Experience Platform, conforme mostrado abaixo:

Todos os recursos em Experience Platform são isolados em sandboxes virtuais específicas. Todas as solicitações para Platform As APIs exigem um cabeçalho que especifique o nome da sandbox em que a operação ocorrerá:

Todas as solicitações que contêm um conteúdo (POST, PUT, PATCH) exigem um cabeçalho adicional:

Desenvolver uma definição de segmento

A primeira etapa na segmentação é definir uma definição de segmento. Uma definição de segmento é um objeto que encapsula uma consulta gravada em Profile Query Language (PQL). Esse objeto também é chamado de predicado PQL. Os predicados de PQL definem as regras para a definição de segmento com base nas condições relacionadas a qualquer registro ou dados de série de tempo fornecidos a Real-Time Customer Profile. Consulte a Guia de PQL para obter mais informações sobre como gravar consultas PQL.

Você pode criar uma nova definição de segmento fazendo uma solicitação POST para o /segment/definitions endpoint na variável Segmentation API. O exemplo a seguir descreve como formatar uma solicitação de definição, incluindo quais informações são necessárias para que uma definição de segmento seja definida com sucesso.

Para obter uma explicação detalhada sobre como definir uma definição de segmento, leia o guia do desenvolvedor de definição de segmento.

Estimar e visualizar um público-alvo estimate-and-preview-an-audience

À medida que desenvolve a definição do segmento, é possível usar as ferramentas de estimativa e visualização no Real-Time Customer Profile para exibir informações de resumo para ajudar a garantir que você esteja isolando o público-alvo esperado. As estimativas fornecem informações estatísticas sobre uma definição de segmento, como o tamanho do público projetado e o intervalo de confiança. As visualizações fornecem listas paginadas de perfis qualificados para uma definição de segmento, permitindo comparar os resultados com o que você espera.

Ao estimar e visualizar seu público-alvo, você pode testar e otimizar seus predicados de PQL até que eles produzam um resultado desejado, em que possam ser usados em uma definição de segmento atualizada.

Há duas etapas necessárias para visualizar ou obter uma estimativa da definição do segmento:

Como as estimativas são geradas

Como os dados ativados para o Perfil do cliente em tempo real são assimilados na Platform, eles são armazenados no armazenamento de dados do Perfil. Quando a assimilação de registros no armazenamento de Perfil aumenta ou diminui a contagem total de perfis em mais de 5%, um trabalho de amostragem é acionado para atualizar a contagem. Se a contagem de perfis não for alterada em mais de 5%, o trabalho de amostragem será executado automaticamente uma vez por semana.

O modo como a amostra é acionada depende do tipo de ingestão sendo usado:

O tamanho da amostra depende do número geral de entidades no armazenamento de perfis. Esses tamanhos de amostra são representados na tabela a seguir:

As estimativas geralmente duram de 10 a 15 segundos, começando com uma estimativa aproximada e refinando à medida que mais registros são lidos.

Criar um trabalho de visualização

Você pode criar um novo trabalho de visualização fazendo uma solicitação POST para a /preview terminal.

Instruções detalhadas sobre como criar um trabalho de visualização podem ser encontradas na guia de visualizações e estimativas de endpoints.

Exibir uma estimativa ou visualização

Os processos de estimativa e pré-visualização são executados de forma assíncrona, pois consultas diferentes podem levar períodos diferentes para serem concluídas. Depois que um query for iniciado, você poderá usar chamadas de API para recuperar (GET) o estado atual da estimativa ou pré-visualização conforme avança.

Usar o Segmentation Service , você pode pesquisar o estado atual de um trabalho de visualização pela respectiva ID. Se o estado for "RESULT_READY", você poderá exibir os resultados. Para pesquisar o estado atual de um trabalho de visualização, leia a seção sobre recuperação de uma seção do trabalho de visualização no guia de endpoints de visualizações e estimativas. Para pesquisar o estado atual de um trabalho estimado, leia a seção sobre recuperação de um trabalho estimado no guia de endpoints de visualizações e estimativas.

Próximas etapas

Depois de desenvolver, testar e salvar a definição do segmento, é possível criar um trabalho de segmento para criar um público-alvo usando o Segmentation Service API. Veja o tutorial sobre avaliação e acesso aos resultados do segmento para obter etapas detalhadas sobre como fazer isso.