Aktivieren von Zielgruppen bei Bedarf für Batch-Ziele über die Ad-hoc-Aktivierungs-API

Überblick overview

Mit der Ad-hoc-Aktivierungs-API können Marketing-Experten Zielgruppen programmgesteuert und schnell für Ziele aktivieren, wenn eine sofortige Aktivierung erforderlich ist.

Verwenden Sie die Ad-hoc-Aktivierungs-API, um vollständige Dateien in Ihr gewünschtes Dateiempfangssystem zu exportieren. Die Ad-hoc-Zielgruppenaktivierung wird nur von Batch-dateibasierten Zielen unterstützt.

Die folgende Abbildung zeigt den kompletten Workflow zum Aktivieren von Zielgruppen über die Ad-hoc-Aktivierungs-API, einschließlich der Segmentierungsaufträge, die alle 24 Stunden in Experience Platform stattfinden.

Anwendungsfälle use-cases

Flash-Verkäufe oder -Promotions

Ein Online-retailer bereitet einen begrenzten Flash-Verkauf vor und möchte die Kunden kurzfristig benachrichtigen. Über die Ad-hoc-Aktivierungs-API von Experience Platform kann das Marketing-Team Zielgruppen bei Bedarf exportieren und schnell Werbe-E-Mails an den Kundenstamm senden.

Aktuelle Ereignisse oder aktuelle Nachrichten

Ein Hotel erwartet in den nächsten Tagen ungünstiges Wetter und das Team möchte die ankommenden Gäste schnell informieren, damit sie entsprechend planen können. Das Marketing-Team kann die Ad-hoc-Aktivierungs-API von Experience Platform verwenden, um Zielgruppen bei Bedarf zu exportieren und die Gäste zu benachrichtigen.

Integrationstests

IT-Manager können die Ad-hoc-Aktivierungs-API von Experience Platform verwenden, um Zielgruppen bei Bedarf zu exportieren, sodass sie ihre benutzerdefinierte Integration mit Adobe Experience Platform testen und sicherstellen können, dass alles ordnungsgemäß funktioniert.

Leitlinien guardrails

Beachten Sie die folgenden Leitplanken bei der Verwendung der Ad-hoc-Aktivierungs-API.

Überlegungen zur Segmentierung segmentation-considerations

Adobe Experience Platform führt geplante Segmentierungsaufträge alle 24 Stunden aus. Die Ad-hoc-Aktivierungs-API wird auf der Grundlage der neuesten Segmentierungsergebnisse ausgeführt.

Schritt 1: Voraussetzungen prerequisites

Bevor Sie die Adobe Experience Platform-APIs aufrufen können, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllen:

Schritt 2: Sammeln von Anmeldeinformationen credentials

Um Experience Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Im Rahmen des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Kopfzeilen in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Ressourcen in Experience Platform lassen sich in spezifischen virtuellen Sandboxes isolieren. Bei Anfragen an Experience Platform-APIs können Sie den Namen und die ID der Sandbox angeben, in der der Vorgang ausgeführt werden soll. Dies sind optionale Parameter.

Bei allen Anfragen, die eine Payload enthalten (POST, PUT, PATCH), ist eine zusätzliche Medientyp-Kopfzeile erforderlich:

Schritt 3: Erstellen eines Aktivierungsflusses in der Experience Platform-Benutzeroberfläche activation-flow

Bevor Sie Zielgruppen über die Ad-hoc-Aktivierungs-API aktivieren können, muss zunächst in der Experience Platform-Benutzeroberfläche ein Aktivierungsfluss für das ausgewählte Ziel konfiguriert worden sein.

Dazu gehören der Einstieg in den Aktivierungs-Workflow, die Auswahl Ihrer Zielgruppen, die Konfiguration eines Zeitplans und die Aktivierung. Sie können die Benutzeroberfläche oder API verwenden, um einen Aktivierungsfluss zu erstellen:

Schritt 4: Abrufen der neuesten Zielgruppen-Exportvorgangs-ID (in Version 2 nicht erforderlich) segment-export-id

Nachdem Sie einen Aktivierungsfluss für Ihr Batch-Ziel konfiguriert haben, werden geplante Segmentierungsaufträge automatisch alle 24 Stunden ausgeführt.

Bevor Sie den Ad-hoc-Aktivierungsauftrag ausführen können, müssen Sie die ID des neuesten Zielgruppen-Exportauftrags abrufen. Sie müssen diese ID in der Ad-hoc-Aktivierungsanfrage übergeben.

Befolgen Sie die hier beschriebenen Anweisungen, um eine Liste aller Zielgruppenexportvorgänge abzurufen.

Suchen Sie in der Antwort nach dem ersten Datensatz, der die folgende Schemaeigenschaft enthält.

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

Die Auftrags-ID des Zielgruppenexports befindet sich in der id-Eigenschaft, wie unten dargestellt.

Schritt 5: Ad-hoc-Aktivierungsauftrag ausführen activation-job

Adobe Experience Platform führt geplante Segmentierungsaufträge alle 24 Stunden aus. Die Ad-hoc-Aktivierungs-API wird auf der Grundlage der neuesten Segmentierungsergebnisse ausgeführt.

Stellen Sie vor der Ausführung eines Ad-hoc-Aktivierungsauftrags sicher, dass der geplante Zielgruppenexportauftrag für Ihre Zielgruppen abgeschlossen ist. Informationen Überwachen des StatusAktivierungsflüsse finden Sie unter „Ziel-Datenflussüberwachung“. Wenn Ihr Aktivierungsdatenfluss beispielsweise den Status Verarbeitung läuft aufweist, warten Sie, bis er abgeschlossen ist, bevor Sie den Ad-hoc-Aktivierungsauftrag ausführen, um eine vollständige Datei zu exportieren.

Nachdem der Zielgruppenexport abgeschlossen ist, können Sie einen Trigger für die Aktivierung erstellen.

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

Eigenschaft

Beschreibung

• destinationId1
• destinationId2

Die IDs der Zielinstanzen, für die Sie Zielgruppen aktivieren möchten. Sie können diese IDs über die Experience Platform-Benutzeroberfläche abrufen, indem Sie zur Registerkarte Ziele > Durchsuchen navigieren und auf die gewünschte Zielzeile klicken, um die Ziel-ID in der rechten Leiste aufzurufen. Weitere Informationen finden Sie in der Dokumentation zum Arbeitsbereich „Ziele.

• segmentId1
• segmentId2
• segmentId3

Die IDs der Zielgruppen, die Sie für das ausgewählte Ziel aktivieren möchten. Mit der Ad-hoc-API können Sie Experience Platform-generierte Zielgruppen sowie externe (benutzerdefinierte Upload-)Zielgruppen exportieren. Verwenden Sie beim Aktivieren externer Zielgruppen die systemgenerierte ID anstelle der Zielgruppen-ID. Die systemgenerierte ID finden Sie in der Ansicht „Zielgruppenzusammenfassung“ in der Benutzeroberfläche „Zielgruppen“.
{width="100" modal="regular"}
{width="100" modal="regular"}

Anfrage mit Export-IDs 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"
   ]
}

Antwort response

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück.

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

Umgang mit API-Fehlern api-error-handling

Destination SDK-API-Endpunkte folgen den allgemeinen Grundsätzen von Experience Platform API-Fehlermeldungen. Siehe API-StatusCodes und Fehler in der Anfragekopfzeile im Handbuch zur Fehlerbehebung bei Experience Platform.

API-Fehler-Codes und Meldungen, die spezifisch für die Ad-hoc-Aktivierungs-API sind specific-error-messages

Bei Verwendung der Ad-hoc-Aktivierungs-API können Sie auf Fehlermeldungen stoßen, die für diesen API-Endpunkt spezifisch sind. Überprüfen Sie die Tabelle, um zu verstehen, wie Sie darauf reagieren, wenn sie angezeigt werden.

Verwandte Informationen related-information