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

Use a API de ativação ad-hoc para ativar públicos-alvo sob demanda para destinos baseados em arquivo em lote e, começando com a v4, para destinos baseados em API e streaming. Consulte Acionar uma execução de ativação ad-hoc mais abaixo neste tutorial.

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 no Experience Platform a cada 24 horas.

Casos de uso use-cases

Vendas ou promoções rápidas flash-sales

Uma retailer online está preparando uma venda rápida limitada e deseja notificar os clientes em 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 current-events

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 integration-testing

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.

Atualização de público para destinos de streaming audience-refresh-streaming

Um destino com base em API ou transmissão aplica um TTL (time-to-live) à associação de público que ele recebe de Adobe Experience Platform. Quando esse TTL expira no lado do destino, os perfis qualificados anteriormente são tratados como inativos, mesmo que permaneçam qualificados no Experience Platform. A equipe de marketing pode usar a versão v4 da API de ativação ad-hoc para reenviar a associação atual completa de um público-alvo sob demanda, sem esperar pela próxima atualização programada. Consulte Acionar uma execução de ativação ad-hoc mais abaixo neste tutorial.

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

Adobe Experience Platform executa trabalhos de segmentação agendados 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 você atende aos seguintes pré-requisitos:

Etapa 2: Coletar credenciais credentials

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

Os recursos no Experience Platform podem ser isolados em sandboxes virtuais específicas. Em solicitações para APIs do Experience 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:

Documentação de referência da API api-reference-documentation

Você pode encontrar a documentação de referência de acompanhamento para todas as operações de API neste tutorial. Consulte a Referência da API de ativação ad hoc.

Etapa 3: Criar fluxo de ativação na interface do usuário do Experience 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 do Experience 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-alvo está na propriedade id, conforme mostrado abaixo.

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

Adobe Experience Platform executa trabalhos de segmentação agendados 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 um status de 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

Para públicos-alvo de serviço que não sejam de segmentação (por exemplo, públicos-alvo de upload externos ou personalizados), você deve especificar a ID de público-alvo gerada pelo Experience Platform em sua solicitação, não a ID de público-alvo externa. Você pode encontrar a ID gerada pelo sistema na parte superior do painel de resumo do público-alvo, exibida como ID# seguida de uma UUID, ao abrir a página de detalhes do público-alvo na interface do usuário de públicos-alvo.

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. É possível obter essas IDs na interface do usuário do Experience 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 Experience 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 na interface do usuário de 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 do Destination SDK seguem os princípios gerais de mensagem de erro da API do Experience Platform. Consulte códigos de status da API e erros no cabeçalho da solicitação no guia de solução de problemas do Experience 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.

(Beta) Acionar uma execução de ativação ad-hoc streaming-destinations

Use a v4 da API de ativação ad-hoc para acionar Ativar agora, uma atualização sob demanda de associação completa de um público-alvo para um destino de transmissão ou baseado em API.

Muitos destinos com base em API e transmissão aplicam um TTL (time-to-live) à associação de público que recebem de Adobe Experience Platform. Quando esse TTL expira no lado do destino, os perfis qualificados anteriormente são tratados como inativos, mesmo que permaneçam qualificados no Experience Platform. Acione uma execução de ativação ad-hoc v4 para reenviar todos os perfis qualificados no momento por meio do pipeline de ativação de transmissão existente, sem esperar pela próxima atualização agendada.

Você também pode acionar essa atualização na interface do usuário do Experience Platform. Leia Ativar agora para destinos de streaming.

Medidas de proteção de transmissão streaming-guardrails

A ativação ad-hoc para destinos de streaming impõe o seguinte limite:

Solicitação de transmissão streaming-request

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}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

Resposta de transmissão streaming-response

Uma resposta bem-sucedida retorna o status HTTP 202 (Accepted) e cria um trabalho de streaming por público solicitado.

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

Se o mesmo público-alvo já tiver sido acionado para esse fluxo de dados nas últimas 24 horas, a solicitação será rejeitada com HTTP 409 e um cabeçalho Retry-After indicando quantos segundos até que você possa tentar novamente.

Informações relacionadas related-information