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

Visão geral overview

A API de ativação ad-hoc permite que os profissionais de marketing ativem programaticamente os públicos-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 públicos-alvo 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 use-cases

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 públicos-alvo 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 públicos-alvo 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 públicos-alvo 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 guardrails

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

Considerações de segmentação segmentation-considerations

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 prerequisites

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

Etapa 2: Coletar credenciais credentials

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:

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.

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

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

Antes de ativar públicos-alvo 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 públicos, configurar um agendamento e ativá-los. Você pode usar a interface ou a API para criar um fluxo de ativação:

Etapa 4: Obter a ID de trabalho de exportação de público mais recente (Não obrigatório na v2) segment-export-id

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 público-alvo 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 público-alvo.

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 público está na variável id como mostrado abaixo.

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

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 público-alvo agendado para seus públicos-alvo 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 público-alvo for concluído, você poderá acionar a ativação.

Solicitação request

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"
      ]
   }
}'

Propriedade

Descrição

• destinationId1
• destinationId2

As IDs das instâncias de destino para as quais você deseja ativar públicos. Você pode obter essas IDs na interface do usuário da Platform navegando até Destinos > Procurar e clicando na linha de destino desejada para exibir a ID de destino no painel direito. Para obter mais informações, leia a documentação do espaço de trabalho de destinos.

• segmentId1
• segmentId2
• segmentId3

As IDs dos públicos-alvo que você deseja ativar para o destino selecionado. Você pode usar a API ad-hoc para exportar públicos gerados pela Platform, bem como públicos externos (upload personalizado). Ao ativar públicos externos, use a ID gerada pelo sistema em vez da ID de público-alvo. Você pode encontrar a ID gerada pelo sistema na exibição de resumo de público-alvo na interface do usuário para públicos-alvo.
{width="100" modal="regular"}
{width="100" modal="regular"}

Solicitação com IDs de exportação request-export-ids

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 response

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 api-error-handling

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 specific-error-messages

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 related-information