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 maneira rápida e eficiente, para situações em que a ativação imediata é necessária.

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 plataforma a cada 24 horas.

Casos de uso

Vendas ou promoções de Flashes

Uma varejista online está preparando uma venda flash 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 do cliente.

Acontecimentos atuais ou notícias de última hora

Um hotel espera tempo de inclinação nos dias seguintes e a equipe quer informar os convidados que chegam rapidamente, para que possam se planejar adequadamente. 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 sua 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 na tarefa. 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 com o agendado tarefas de exportação de segmento. Antes de executar um trabalho de ativação ad-hoc, verifique se o trabalho de exportação do segmento agendado foi concluído. Consulte monitoramento de fluxo de dados de destino para obter informações sobre como monitorar o status dos fluxos de ativação. Por exemplo, se o seu fluxo de dados de ativação mostrar uma Processamento , aguarde até que ele seja concluído 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 agendadas 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 poder fazer chamadas para as APIs do Adobe Experience Platform, verifique se você atende aos seguintes pré-requisitos:

• Você tem uma conta da Organização IMS com acesso à Adobe Experience Platform.
• Sua conta do Experience Platform tem a variável developer e user funções ativadas para o perfil de produto da API do Adobe Experience Platform. Entre em contato com seu Admin Console para ativar essas funções em sua conta.
• Você tem uma Adobe ID. Caso não tenha uma Adobe ID, acesse Console do Adobe Developer e criar uma nova conta.

Etapa 2: Obter credenciais

Para fazer chamadas para APIs da plataforma, primeiro conclua o tutorial de autenticação. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API do 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 para sandboxes virtuais específicas. Em solicitações para APIs da plataforma, é possível especificar o nome e a ID da sandbox em que a operação ocorrerá. Esses são parâmetros opcionais.

• x-sandbox-name: {SANDBOX_NAME}

Todas as solicitações que contêm uma carga útil (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 plataforma

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

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

• Use a interface do usuário da plataforma 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 de perfis em lote e ativar dados

Etapa 4: Obter a ID de trabalho de exportação de segmento mais recente (Não é necessário na v2)

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

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

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

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

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

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

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

O Adobe Experience Platform executa tarefas de segmentação agendadas 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 segmentos agendados para seus segmentos foi concluído. Consulte monitoramento de fluxo de dados de destino para obter informações sobre como monitorar o status dos fluxos de ativação. Por exemplo, se o seu fluxo de dados de ativação mostrar uma Processamento , aguarde até que ele seja concluído antes de executar o trabalho de ativação ad-hoc.

Depois que o trabalho de exportação de segmento for concluído, é possível 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"
      }
   ]
}

Tratamento de erros da API

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

Códigos de erro de API e mensagens específicos da API de ativação ad-hoc

Ao usar a API de ativação ad-hoc, você pode encontrar mensagens de erro específicas a esse endpoint da API. Revise a tabela para entender como resolvê-las quando elas forem exibidas.

Informações relacionadas

• Conecte-se a destinos em lote e ative dados usando a API do Serviço de Fluxo