Gestione dei metadati del pubblico
Utilizza i modelli di metadati del pubblico per creare, aggiornare o eliminare in modo programmatico i tipi di pubblico nella tua destinazione. Adobe fornisce un modello estensibile di metadati per il pubblico, che puoi configurare in base alle specifiche della tua API di marketing. Dopo aver definito, testato e inviato la configurazione, questa verrà utilizzata da Adobe per strutturare le chiamate API alla destinazione.
È possibile configurare la funzionalità descritta in questo documento utilizzando l'endpoint API /authoring/audience-templates. Leggi crea un modello di metadati per un elenco completo delle operazioni che puoi eseguire sull'endpoint.
Quando utilizzare l’endpoint di gestione dei metadati dell’audience when-to-use
A seconda della configurazione API, potrebbe essere necessario utilizzare o meno l’endpoint di gestione dei metadati dell’audience durante la configurazione della destinazione in Experience Platform. Utilizza il diagramma dell’albero decisionale seguente per capire quando utilizzare l’endpoint dei metadati del pubblico e come configurare un modello di metadati del pubblico per la tua destinazione.
Casi d’uso supportati dalla gestione dei metadati dell’audience use-cases
Con il supporto dei metadati del pubblico in Destination SDK, quando configuri la destinazione di Experience Platform, puoi offrire agli utenti di Platform una di più opzioni quando mappano e attivano i tipi di pubblico nella destinazione. Puoi controllare le opzioni disponibili per l'utente tramite i parametri nella sezione Configurazione metadati pubblico della configurazione di destinazione.
Caso d’uso 1: disponi di un’API di terze parti e gli utenti non devono immettere ID di mappatura
Se disponi di un endpoint API per creare/aggiornare/eliminare tipi di pubblico o tipi di pubblico, puoi utilizzare i modelli di metadati del pubblico per configurare Destination SDK in modo che corrisponda alle specifiche dell’endpoint creazione/aggiornamento/eliminazione del pubblico. Experience Platform può creare, aggiornare o eliminare a livello di programmazione tipi di pubblico e sincronizzare nuovamente i metadati con Experience Platform.
Quando si attivano dei tipi di pubblico nella destinazione nell'interfaccia utente di Experience Platform, gli utenti non devono compilare manualmente un campo ID di mappatura pubblico nel flusso di lavoro di attivazione.
Caso d’uso 2: gli utenti devono prima creare un’audience nella destinazione e devono inserire manualmente l’ID della mappatura
Se i tipi di pubblico e altri metadati devono essere creati manualmente dai partner o dagli utenti nella tua destinazione, gli utenti devono compilare manualmente il campo ID mappatura pubblico nel flusso di lavoro di attivazione per sincronizzare i metadati del pubblico tra la destinazione e l’Experience Platform.
Caso d’uso 3: la destinazione accetta l’ID del pubblico Experience Platform e gli utenti non devono inserire manualmente l’ID della mappatura
Se il sistema di destinazione accetta l'ID pubblico Experience Platform, puoi configurarlo nel modello di metadati del pubblico. Gli utenti non devono compilare un ID di mappatura del pubblico quando attivano un segmento.
Modello di pubblico generico ed estensibile generic-and-extensible
Per supportare i casi d’uso elencati sopra, Adobe fornisce un modello generico che può essere personalizzato per adattarsi alle specifiche API.
Puoi utilizzare il modello generico per creare un nuovo modello di pubblico se l'API supporta:
- I metodi HTTP: POST, GET, PUT, DELETE, PATCH
- Tipi di autenticazione: OAuth 1, OAuth 2 con token di aggiornamento, OAuth 2 con token bearer
- Funzioni: crea un pubblico, aggiorna un pubblico, ottieni un pubblico, elimina un pubblico, convalida le credenziali.
Se necessario, il team di progettazione Adobe può collaborare con te per espandere il modello generico con campi personalizzati.
Esempi di configurazione configuration-examples
Questa sezione include tre esempi di configurazioni di metadati di pubblico generici, come riferimento, insieme alle descrizioni delle sezioni principali della configurazione. Osserva come l’URL, le intestazioni, la richiesta e il corpo della risposta differiscono tra le tre configurazioni di esempio. Ciò è dovuto alle diverse specifiche delle tre piattaforme di esempio nell’API di marketing.
Si noti che in alcuni esempi i campi macro come {{authData.accessToken}} o {{segment.name}} vengono utilizzati nell'URL, mentre in altri esempi vengono utilizzati nelle intestazioni o nel corpo della richiesta. Dipende davvero dalle specifiche API di marketing.
createupdatedeletevalidatenotifyEsempio di streaming 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"
}
}
Esempio di streaming 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"
}
]
}
}
}
Esempio di streaming 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"
}
}
Esempio basato su file 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"
}
}
Trova le descrizioni di tutti i parametri nel modello nel riferimento API Crea un modello di pubblico.
Macro utilizzate nei modelli di metadati del pubblico macros
Per trasmettere informazioni quali ID pubblico, token di accesso, messaggi di errore e altro ancora tra Experience Platform e l’API, i modelli di pubblico includono macro che è possibile utilizzare. Di seguito è riportata una descrizione delle macro utilizzate nei tre esempi di configurazione riportati in questa pagina:
{{segment.alias}}{{segment.name}}{{segment.id}}{{customerData.accountId}}{{oauth2ServiceAccessToken}}{{authData.accessToken}}{{authData.accessToken}} se Experience Platform deve utilizzare token senza scadenza per la connessione alla destinazione, altrimenti utilizza {{oauth2ServiceAccessToken}} per generare un token di accesso.{{body.segments[0].segment.id}}externalAudienceId.{{error.message}}