Ativar segmentos de público-alvo sob demanda para destinos em lote por meio da API de ativação ad-hoc

Visão geral

A API de ativação ad-hoc permite que os profissionais de marketing ativem programaticamente segmentos de público-alvo para destinos, de forma rápida e eficiente, para situações em que a ativação imediata é necessária.

Use a API de ativação ad-hoc para exportar arquivos completos para o sistema de recepção de arquivos desejado. A ativação de público-alvo ad-hoc é suportada somente pelo destinos baseados em arquivo em lote.

O diagrama abaixo ilustra o fluxo de trabalho completo para ativar segmentos por meio da API de ativação ad-hoc, incluindo os trabalhos de segmentação que ocorrem na Platform a cada 24 horas.

Casos de uso

Vendas ou promoções de Flashes

Um varejista online está preparando uma venda rápida limitada e deseja notificar os clientes em um curto prazo. Por meio da API de ativação ad-hoc do Experience Platform, a equipe de marketing pode exportar segmentos sob demanda e enviar rapidamente emails promocionais para a base de clientes.

Eventos atuais ou últimas notícias

Um hotel espera intempéries nos dias seguintes, e a equipe quer informar os hóspedes que chegam rapidamente, para que possam planejar de acordo. A equipe de marketing pode usar a API de ativação ad-hoc do Experience Platform para exportar segmentos sob demanda e notificar os convidados.

Teste de integração

Os gerentes de TI podem usar a API de ativação ad-hoc do Experience Platform para exportar segmentos sob demanda, para que possam testar a integração personalizada com o Adobe Experience Platform e garantir que tudo esteja funcionando corretamente.

Medidas de proteção

Lembre-se das seguintes medidas de proteção ao usar a API de ativação ad-hoc.

• Atualmente, cada trabalho de ativação ad-hoc pode ativar até 80 segmentos. Tentar ativar mais de 80 segmentos por trabalho causará falha no trabalho. Esse comportamento está sujeito a alterações em versões futuras.
• Os trabalhos de ativação ad-hoc não podem ser executados em paralelo ao agendado trabalhos de exportação de segmento. Antes de executar um trabalho de ativação ad-hoc, verifique se o trabalho de exportação de segmento agendado foi concluído. Consulte monitoramento do fluxo de dados de destino para obter informações sobre como monitorar o status dos fluxos de ativação. Por exemplo, se o fluxo de dados de ativação mostrar uma variável Processando aguarde a conclusão antes de executar o trabalho de ativação ad-hoc.
• Não execute mais de um trabalho de ativação ad-hoc simultâneo por segmento.

Considerações de segmentação

O Adobe Experience Platform executa tarefas de segmentação programadas uma vez a cada 24 horas. A API de ativação ad-hoc é executada com base nos resultados de segmentação mais recentes.

Etapa 1: Pré-requisitos

Antes de fazer chamadas para as APIs do Adobe Experience Platform, verifique se os seguintes pré-requisitos são atendidos:

• Você tem uma conta de organização com acesso ao Adobe Experience Platform.
• Sua conta Experience Platform tem o developer e user funções habilitadas para o perfil de produto API do Adobe Experience Platform. Entre em contato com Admin Console administrador para habilitar essas funções para sua conta.
• Você tem uma Adobe ID. Se você não tiver uma Adobe ID, acesse o Console do Adobe Developer e criar uma nova conta.

Etapa 2: Coletar credenciais

Para fazer chamadas para APIs da Platform, 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 de Experience Platform, conforme mostrado abaixo:

• Autorização: Portador {ACCESS_TOKEN}
• x-api-key: {API_KEY}
• x-gw-ims-org-id: {ORG_ID}

Os recursos no Experience Platform podem ser isolados em sandboxes virtuais específicas. Em solicitações para APIs da Platform, é possível especificar o nome e a ID da sandbox em que a operação ocorrerá. Esses parâmetros são opcionais.

• x-sandbox-name: {SANDBOX_NAME}

Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho de tipo de mídia adicional:

• Tipo de conteúdo: application/json

Etapa 3: Criar fluxo de ativação na interface do usuário da Platform

Antes de ativar segmentos por meio da API de ativação ad-hoc, primeiro é necessário ter um fluxo de ativação configurado na interface do usuário da Platform para o destino escolhido.

Isso inclui acessar o fluxo de trabalho de ativação, selecionar os segmentos, configurar um agendamento e ativá-los. Você pode usar a interface ou a API para criar um fluxo de ativação:

• Use a interface do Platform para criar um fluxo de ativação para destinos de exportação de perfil em lote
• Use a API do Serviço de fluxo para se conectar aos destinos de exportação do perfil de lote e ativar dados

Etapa 4: obter a ID de trabalho de exportação de segmento mais recente (Não obrigatório na v2)

Após configurar um fluxo de ativação para o destino em lote, os trabalhos de segmentação programados começam a ser executados automaticamente a cada 24 horas.

Antes de executar o trabalho de ativação ad-hoc, obtenha a ID do trabalho de exportação de segmento mais recente. Você deve passar essa ID na solicitação de trabalho de ativação ad-hoc.

Siga as instruções descritas aqui para recuperar uma lista de todos os trabalhos de exportação de segmento.

Na resposta, procure o primeiro registro que inclui a propriedade de schema abaixo.

"schema":{
   "name":"_xdm.context.profile"
}

A ID do trabalho de exportação de segmento está na id como mostrado abaixo.

Etapa 5: Executar o trabalho de ativação ad-hoc

O Adobe Experience Platform executa tarefas de segmentação programadas uma vez a cada 24 horas. A API de ativação ad-hoc é executada com base nos resultados de segmentação mais recentes.

Antes de executar um trabalho de ativação ad-hoc, verifique se o trabalho de exportação de segmento agendado para os seus segmentos foi concluído. Consulte monitoramento do fluxo de dados de destino para obter informações sobre como monitorar o status dos fluxos de ativação. Por exemplo, se o fluxo de dados de ativação mostrar uma variável Processando aguarde a conclusão antes de executar o trabalho de ativação ad-hoc para exportar um arquivo completo.

Depois que o trabalho de exportação de segmento for concluído, você poderá acionar a ativação.

Solicitação

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

Solicitação com IDs de exportação (a ser descontinuada)

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

Resposta

Uma resposta bem-sucedida retorna o status HTTP 200.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

Manipulação de erros de API

Os endpoints da API Destination SDK seguem os princípios gerais de mensagem de erro da API Experience Platform. Consulte Códigos de status da API e erros no cabeçalho da solicitação no guia de solução de problemas da Platform.

Códigos de erro de API e mensagens específicas para a API de ativação ad-hoc

Ao usar a API de ativação ad-hoc, você pode encontrar mensagens de erro específicas para esse endpoint da API. Revise a tabela para entender como abordá-los quando eles forem exibidos.

Informações relacionadas

• Conectar-se a destinos em lote e ativar dados usando a API do Serviço de fluxo
• (Beta) Exportar arquivos sob demanda para destinos em lote usando a interface do Experience Platform

Recursos do Business.Adobe.com