Attivare i tipi di pubblico on-demand nelle destinazioni batch tramite l’API di attivazione ad hoc

Panoramica overview

L’API di attivazione ad hoc consente agli addetti al marketing di attivare in modo programmatico il pubblico nelle destinazioni, in modo rapido ed efficiente, per le situazioni in cui è richiesta l’attivazione immediata.

Utilizza l’API di attivazione ad hoc per esportare file completi nel sistema di ricezione dei file desiderato. L'attivazione di un pubblico ad hoc è supportata solo da destinazioni basate su file batch.

Il diagramma seguente illustra il flusso di lavoro end-to-end per l’attivazione dei tipi di pubblico tramite l’API di attivazione ad-hoc, inclusi i processi di segmentazione che si svolgono in Platform ogni 24 ore.

Casi d’uso use-cases

Vendite o promozioni Flash

Un rivenditore online sta preparando una vendita flash limitata e desidera avvisare i clienti con un breve preavviso. Tramite l’API di attivazione ad hoc di Experience Platform, il team di marketing può esportare i tipi di pubblico on-demand e inviare rapidamente e-mail promozionali alla base clienti.

Attualità o ultime notizie

Un hotel si aspetta un tempo inclemente nei giorni successivi e il team vuole informare rapidamente gli ospiti in arrivo, in modo che possano pianificare di conseguenza. Il team marketing può utilizzare l’API di attivazione ad hoc di Experience Platform per esportare i tipi di pubblico on-demand e avvisare gli ospiti.

Test di integrazione

I responsabili IT possono utilizzare l’API di attivazione ad hoc di Experience Platform per esportare i tipi di pubblico on-demand, in modo da testare la loro integrazione personalizzata con Adobe Experience Platform e garantire il corretto funzionamento di tutto.

Guardrail guardrails

Quando utilizzi l’API di attivazione ad hoc, tieni presenti le seguenti protezioni.

Considerazioni sulla segmentazione segmentation-considerations

Adobe Experience Platform esegue processi di segmentazione pianificati una volta ogni 24 ore. L’API di attivazione ad hoc viene eseguita in base ai risultati di segmentazione più recenti.

Passaggio 1: Prerequisiti prerequisites

Prima di poter effettuare chiamate alle API di Adobe Experience Platform, assicurati di soddisfare i seguenti prerequisiti:

Passaggio 2: raccogliere le credenziali credentials

Per effettuare chiamate alle API di Platform, devi prima completare l'esercitazione di autenticazione. Il completamento del tutorial di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

Le risorse di Experience Platform possono essere isolate in specifiche sandbox virtuali. Nelle richieste alle API di Platform, puoi specificare il nome e l’ID della sandbox in cui verrà eseguita l’operazione. Si tratta di parametri facoltativi.

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione di tipo multimediale aggiuntiva:

Passaggio 3: creare un flusso di attivazione nell’interfaccia utente di Platform activation-flow

Prima di poter attivare i tipi di pubblico tramite l’API di attivazione ad hoc, è necessario aver configurato un flusso di attivazione nell’interfaccia utente di Platform, per la destinazione scelta.

Ciò include l’accesso al flusso di lavoro di attivazione, la selezione dei tipi di pubblico, la configurazione di una pianificazione e l’attivazione di questi. Puoi utilizzare l’interfaccia o l’API per creare un flusso di attivazione:

Passaggio 4: ottieni l’ID del processo di esportazione del pubblico più recente (non richiesto nella versione v2) segment-export-id

Dopo aver configurato un flusso di attivazione per la destinazione batch, i processi di segmentazione pianificati iniziano a essere eseguiti automaticamente ogni 24 ore.

Prima di poter eseguire il processo di attivazione ad hoc, è necessario ottenere l’ID del processo di esportazione del pubblico più recente. Devi passare questo ID nella richiesta del processo di attivazione ad hoc.

Segui le istruzioni descritte qui per recuperare un elenco di tutti i processi di esportazione del pubblico.

Nella risposta, cerca il primo record che include la proprietà dello schema seguente.

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

L'ID del processo di esportazione del pubblico si trova nella proprietà id, come illustrato di seguito.

Passaggio 5: eseguire il processo di attivazione ad hoc activation-job

Adobe Experience Platform esegue processi di segmentazione pianificati una volta ogni 24 ore. L’API di attivazione ad hoc viene eseguita in base ai risultati di segmentazione più recenti.

Prima di eseguire un processo di attivazione ad hoc, assicurati che il processo di esportazione pianificato per il pubblico sia stato completato. Per informazioni su come monitorare lo stato dei flussi di attivazione, vedere monitoraggio del flusso di dati di destinazione. Ad esempio, se il flusso di dati di attivazione mostra uno stato Elaborazione, attendi che termini prima di eseguire il processo di attivazione ad hoc per esportare un file completo.

Una volta completato il processo di esportazione del pubblico, puoi attivare l’attivazione.

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

Proprietà

Descrizione

• destinationId1
• destinationId2

Gli ID delle istanze di destinazione a cui desideri attivare i tipi di pubblico. Puoi ottenere questi ID dall'interfaccia utente di Platform, passando a Destinazioni > Sfoglia scheda e facendo clic sulla riga di destinazione desiderata per visualizzare l'ID di destinazione nella barra a destra. Per ulteriori informazioni, consulta la documentazione dell'area di lavoro delle destinazioni.

• segmentId1
• segmentId2
• segmentId3

Gli ID dei tipi di pubblico che desideri attivare nella destinazione selezionata. Puoi utilizzare l’API ad hoc per esportare i tipi di pubblico generati da Platform e quelli esterni (caricamento personalizzato). Quando attivi un pubblico esterno, utilizza l’ID generato dal sistema invece dell’ID del pubblico. L'ID generato dal sistema è disponibile nella visualizzazione di riepilogo del pubblico nell'interfaccia utente dei tipi di pubblico.
{width="100" modal="regular"}
{width="100" modal="regular"}

Richiesta con ID esportazione 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"
   ]
}

Risposta response

Una risposta corretta restituisce lo stato 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"
      }
   ]
}

Gestione degli errori API api-error-handling

Gli endpoint API di Destination SDK seguono i principi generali dei messaggi di errore API di Experience Platform. Consulta Codici di stato API e errori di intestazione della richiesta nella guida alla risoluzione dei problemi di Platform.

Codici di errore API e messaggi specifici per l’API di attivazione ad hoc specific-error-messages

Quando utilizzi l’API di attivazione ad hoc, puoi incontrare messaggi di errore specifici per questo endpoint API. Rivedi la tabella per capire come gestirli quando vengono visualizzati.

Informazioni correlate related-information