Verwaltung von Zielgruppen-Metadaten
Verwenden Sie Vorlagen für Zielgruppen-Metadaten, um Zielgruppen in Ihrem Ziel programmgesteuert zu erstellen, zu aktualisieren oder zu löschen. Adobe bietet eine erweiterungsfähige Vorlage für Zielgruppen-Metadaten, die Sie anhand der Spezifikationen Ihrer Marketing-API konfigurieren können. Nachdem Sie die Konfiguration definiert, getestet und gesendet haben, wird sie von Adobe zur Strukturierung der API-Aufrufe an Ihr Ziel verwendet.
Sie können die in diesem Dokument beschriebenen Funktionen mithilfe des API-Endpunkts /authoring/audience-templates konfigurieren. Eine vollständige Liste der Vorgänge, die Sie mit dem Endpunkt durchführen können, finden Sie unter Erstellen einer Metadatenvorlage.
Wann Sie den Endpunkt für die Verwaltung von Zielgruppen-Metadaten verwenden sollten when-to-use
Abhängig von Ihrer API-Konfiguration müssen Sie möglicherweise den Endpunkt für die Verwaltung von Zielgruppen-Metadaten verwenden, während Sie Ihr Ziel in Experience Platform konfigurieren. Der unten stehende Entscheidungsbaum verdeutlicht, wann der Endpunkt für Zielgruppen-Metadaten verwendet werden muss und wie Sie eine Vorlage für Zielgruppen-Metadaten für Ihr Ziel konfiguren.
Anwendungsfälle, die durch die Verwaltung von Zielgruppen-Metadaten unterstützt werden use-cases
Dank der Unterstützung von Zielgruppen-Metadaten im Destination SDK können Sie bei der Konfiguration Ihres Experience Platform-Ziels den Benutzerinnen und Benutzern von Platform eine von mehreren Optionen bieten, wenn sie Zielgruppen Ihrem Ziel zuordnen und aktivieren. Sie können die Optionen, die den Benutzerinnen und Benutzern zur Verfügung stehen, über die Parameter im Abschnitt Zielgruppen-Metadatenkonfiguration der Zielkonfiguration steuern.
Anwendungsfall 1: Sie verfügen über eine Drittanbieter-API, und Benutzerinnen und Benutzer müssen keine Zuordnungs-IDs angeben
Wenn Sie über einen API-Endpunkt zum Erstellen, Aktualisieren und Löschen von Zielgruppen verfügen, können Sie Destination SDK mithilfe von Vorlagen für Zielgruppen-Metadaten so konfigurieren, dass es den Spezifikationen Ihres Zielgruppenendpunkts zum Erstellen/Aktualisieren/Löschen entspricht. Experience Platform kann Zielgruppen programmgesteuert erstellen, aktualisieren und löschen sowie Metadaten erneut synchronisieren.
Beim Aktivieren von Zielgruppen für Ihr Ziel in der Benutzeroberfläche von Experience Platform brauchen Benutzerinnen und Benutzer im Aktivierungs-Workflow das Feld für die Zielgruppenzuordnungs-ID nicht manuell auszufüllen.
Anwendungsfall 2: Benutzerinnen und Benutzer müssen zuerst ein Zielgruppe in Ihrem Ziel erstellen und die Zuordnungs-ID manuell eingeben
Wenn Zielgruppen- und andere Metadaten von Partnern oder Benutzerinnen bzw. Benutzern manuell in Ihrem Ziel erstellt werden müssen, müssen die Benutzerinnen und Benutzer das Feld für die Segmentzuordnungs-ID im Aktivierungs-Workflow manuell ausfüllen, um die Zielgruppen-Metadaten zwischen Ihrem Ziel und Experience Platform zu synchronisieren.
Anwendungsfall 3: Ihr Ziel akzeptiert die Zielgruppen-ID von Experience Platform, und Benutzerinnen und Benutzer brauchen die Zuordnungs-ID nicht manuell einzugeben
Wenn Ihr Zielsystem die Zielgruppen-ID von Experience Platform akzeptiert, können Sie diese in der Vorlage Ihrer Zielgruppen-Metadaten konfigurieren. Benutzerinnen und Benutzer müssen beim Aktivieren eines Segments keine Zielgruppen-ID ausfüllen.
Generische und erweiterbare Zielgruppenvorlage generic-and-extensible
Für die oben aufgeführten Anwendungsfälle bietet Ihnen Adobe eine generische Vorlage, die Sie an Ihre API-Spezifikationen anpassen können.
Sie können die generische Vorlage zur Erstellung einer neuen Zielgruppenvorlage verwenden, wenn Ihre API Folgendes unterstützt:
- Die HTTP-Methoden: POST, GET, PUT, DELETE, PATCH
- Die Authentifizierungstypen: OAuth 1, OAuth 2 mit Aktualisierungs-Token, OAuth 2 mit Bearer-Token
- Die Funktionen: Erstellen einer Zielgruppe, Aktualisieren einer Zielgruppe, Abrufen einer Zielgruppe, Löschen einer Zielgruppe, Validieren der Anmeldeinformationen
Das Engineering-Team von Adobe ist Ihnen gern dabei behilflich, die generische Vorlage mit benutzerdefinierten Feldern zu erweitern, wenn dies für Ihre Anwendungsfälle erforderlich ist.
Konfigurationsbeispiele configuration-examples
Dieser Abschnitt enthält drei Beispiele für allgemeine Konfigurationen von Zielgruppen-Metadaten sowie Beschreibungen der wichtigsten Abschnitte der Konfiguration. Beachten Sie, wie sich URL, Kopfzeilen sowie der Aufbau von Anfrage und Antwort zwischen den drei Beispielkonfigurationen unterscheiden. Dies liegt an den unterschiedlichen Spezifikationen der Marketing-API der drei Beispielplattformen.
Beachten Sie, dass in einigen Beispielen Makro-Felder wie {{authData.accessToken}} oder {{segment.name}} in der URL und in anderen Beispielen in den Kopfzeilen oder im Anfragetext verwendet werden. Das hängt von den Spezifikationen Ihrer Marketing-API ab.
createupdatedeletevalidatenotifyStreaming-Beispiel 1 example-1
{
"instanceId":"34ab9cc2-2536-44a5-9dc5-b2fea60b3bd6",
"createdDate":"2021-07-26T19:30:52.012490Z",
"lastModifiedDate":"2021-07-27T21:25:42.763478Z",
"metadataTemplate":{
"create":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments",
"httpMethod":"POST",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"segments":[
{
"name":"{{segment.name}}",
"description":"{{segment.description}}",
"source_type":"FIRST_PARTY",
"ad_account_id":"{{customerData.accountId}}",
"retention_in_days":180
}
]
}
},
"responseFields":[
{
"value":"{{body.segments[0].segment.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"update":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
"httpMethod":"PUT",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"segments":[
{
"id":"{{segment.alias}}",
"name":"{{segment.name}}",
"description":"{{segment.description}}"
}
]
}
},
"responseFields":[
{
"value":"{{body.segments[0].segment.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"delete":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
"httpMethod":"DELETE",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"name":"Moviestar destination audience template - Example 1"
}
}
Streaming-Beispiel 2 example-2
{
"instanceId":"12c78017-5af3-4d4e-8f9c-d330c547c482",
"createdDate":"2021-07-20T13:27:37.029490Z",
"lastModifiedDate":"2021-07-20T18:53:03.622306Z",
"metadataTemplate":{
"create":{
"url":"https://api.moviestar.com/v1.0/{{customerData.accountId}}/customaudiences?fields=name,description,account_id&subtype=CUSTOM&name={{segment.name}}&customer_file_source={{segment.metadata.customer_file_source}}&access_token={{authData.accessToken}}",
"httpMethod":"POST",
"headers":[
{
"value":"application/x-www-form-urlencoded",
"header":"Content-Type"
}
],
"responseFields":[
{
"value":"{{response.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{error.message}}",
"name":"message"
}
]
},
"update":{
"url":"https://api.moviestar.com/v1.0/{{segment.alias}}?field=name,description,account_id&access_token={{authData.accessToken}}&customerAudienceId={{segment.alias}}&&name={{segment.name}}&description={{segment.description}}&customer_file_source={{segment.metadata.customer_file_source}}",
"httpMethod":"POST",
"headers":[
{
"value":"application/x-www-form-urlencoded",
"header":"Content-Type"
}
],
"responseFields":[
{
"value":"{{response.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{error.message}}",
"name":"message"
}
]
},
"delete":{
"url":"https://api.moviestar.com/v1.0/{{segment.alias}}?fields=name,description,account_id&access_token={{authData.accessToken}}&customerAudienceId={{segment.alias}}",
"httpMethod":"DELETE",
"headers":[
{
"value":"application/x-www-form-urlencoded",
"header":"Content-Type"
}
],
"responseErrorFields":[
{
"value":"{{error.message}}",
"name":"message"
}
]
},
"validate":{
"url":"https://api.moviestar.com/v1.0/permissions?access_token={{authData.accessToken}}",
"httpMethod":"GET",
"headers":[
{
"value":"application/x-www-form-urlencoded",
"header":"Content-Type"
}
],
"responseFields":[
{
"value":"{{response.data[0].permission}}",
"name":"Id"
}
],
"responseErrorFields":[
{
"value":"{{error.message}}",
"name":"message"
}
]
}
}
}
Streaming-Beispiel 3 example-3
{
"instanceId":"12a3238f-b509-4a40-b8fb-0a5006e7901d",
"createdDate":"2021-07-20T13:30:30.843054Z",
"lastModifiedDate":"2021-07-21T16:33:05.787472Z",
"metadataTemplate":{
"create":{
"url":"https://api.moviestar.com/v2/dmpSegments",
"httpMethod":"POST",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{authData.accessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"name":"{{segment.name}}",
"type":"USER",
"account":"{{customerData.accountId}}",
"accessPolicy":"PRIVATE",
"destinations":[
{
"destination":"MOVIESTAR"
}
],
"sourcePlatform":"ADOBE"
}
},
"responseFields":[
{
"value":"{{headers.x-moviestar-id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{message}}",
"name":"message"
}
]
},
"update":{
"url":"https://api.moviestar.com/v2/dmpSegments/{{segment.alias}}",
"httpMethod":"POST",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{authData.accessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"patch":{
"$set":{
"name":"{{segment.name}}"
}
}
}
},
"responseErrorFields":[
{
"value":"{{message}}",
"name":"message"
}
]
},
"delete":{
"url":"https://api.moviestar.com/v2/dmpSegments/{{segment.alias}}",
"httpMethod":"DELETE",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{authData.accessToken}}",
"header":"Authorization"
}
],
"responseErrorFields":[
{
"value":"{{message}}",
"name":"message"
}
]
},
"name":"Moviestar audience template - Third example"
}
}
Dateibasiertes Beispiel example-file-based
{
"instanceId":"34ab9cc2-2536-44a5-9dc5-b2fea60b3bd6",
"createdDate":"2021-07-26T19:30:52.012490Z",
"lastModifiedDate":"2021-07-27T21:25:42.763478Z",
"metadataTemplate":{
"create":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments",
"httpMethod":"POST",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"segments":[
{
"name":"{{segment.name}}",
"description":"{{segment.description}}",
"source_type":"FIRST_PARTY",
"ad_account_id":"{{customerData.accountId}}",
"retention_in_days":180
}
]
}
},
"responseFields":[
{
"value":"{{body.segments[0].segment.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"update":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
"httpMethod":"PUT",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"segments":[
{
"id":"{{segment.alias}}",
"name":"{{segment.name}}",
"description":"{{segment.description}}"
}
]
}
},
"responseFields":[
{
"value":"{{body.segments[0].segment.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"notify":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
"httpMethod":"PUT",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"requestBody":{
"json":{
"segments":[
{
"id":"{{segment.alias}}",
"name":"{{segment.name}}",
"description":"{{segment.description}}"
}
]
}
},
"responseFields":[
{
"value":"{{body.segments[0].segment.id}}",
"name":"externalAudienceId"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"delete":{
"url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
"httpMethod":"DELETE",
"headers":[
{
"value":"application/json",
"header":"Content-Type"
},
{
"value":"Bearer {{oauth2ServiceAccessToken}}",
"header":"Authorization"
}
],
"responseErrorFields":[
{
"value":"{{root}}",
"name":"message"
}
]
},
"name":"Moviestar destination audience template - Example 1"
}
}
Beschreibungen aller Parameter in der Vorlage finden Sie in der API-Referenz zum Erstellen einer Zielgruppenvorlage.
Verwendete Makros in Vorlagen für Zielgruppen-Metadaten macros
Um Informationen wie Zielgruppen-IDs, Zugriffs-Token, Fehlermeldungen und mehr zwischen Experience Platform und Ihrer API zu übermitteln, enthalten die Vorlagen für Zielgruppen Makros. Im Folgenden finden Sie eine Beschreibung der Makros, die in den drei Konfigurationsbeispielen auf dieser Seite verwendet werden:
{{segment.alias}}{{segment.name}}{{segment.id}}{{customerData.accountId}}{{oauth2ServiceAccessToken}}{{authData.accessToken}}{{authData.accessToken}}, wenn Experience Platform nicht ablaufende Token verwenden soll, um eine Verbindung zu Ihrem Ziel herzustellen. Andernfalls verwenden Sie {{oauth2ServiceAccessToken}}, um ein Zugriffs-Token zu generieren.{{body.segments[0].segment.id}}externalAudienceId zurück.{{error.message}}