MediaTailor variabili pubblicitarie dinamiche - AWS Elemental MediaTailor
MediaTailor riferimento ai parametriMediaTailor alias di configurazioneMediaTailor passaggio dei parametri ADSMediaTailorrisoluzione dei problemi relativi agli alias

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

MediaTailor variabili pubblicitarie dinamiche

AWS Elemental MediaTailor la richiesta all'ad decision server (ADS) include informazioni sulla sessione di visualizzazione corrente. Queste informazioni aiutano l'ADS a scegliere gli annunci migliori da fornire nella sua risposta. Quando configuri il modello ADS nella tua MediaTailor configurazione, puoi includere variabili dinamiche, note anche come macro. Le variabili dinamiche sono stringhe sostituibili.

Le variabili dinamiche possono assumere le seguenti forme:

  • Valori statici: valori che non cambiano da una sessione all'altra. Ad esempio, il tipo di risposta che MediaTailor si aspetta dall'ADS.

  • Variabili di dominio: variabili dinamiche che possono essere utilizzate per i domini URL, ad esempio la parte my-ads-server.com dell'URL http://my-ads-server.com. Per informazioni dettagliate, consultare MediaTailor variabili di dominio.

  • Dati di sessione: valori dinamici forniti da MediaTailor per ogni sessione, ad esempio l'ID di sessione. Per informazioni dettagliate, consultare MediaTailor variabili di sessione.

  • Dati del giocatore: valori dinamici forniti dal giocatore per ogni sessione. Questi descrivono il visualizzatore di contenuti e aiutano l'ADS a determinare quali annunci MediaTailor devono essere inseriti nello stream. Per informazioni dettagliate, consultare MediaTailor variabili del giocatore.

MediaTailor riferimento ai parametri e limitazioni

AWS Elemental MediaTailor fornisce informazioni complete sulle restrizioni relative ai caratteri dei parametri, sui limiti di lunghezza e sui formati supportati sia per i parametri di query manifest che per i parametri ADS.

restrizioni relative ai caratteri dei parametri di interrogazione manifesta

I parametri delle query manifeste supportano caratteri specifici e hanno limiti di lunghezza definiti.

Caratteri supportati (senza codifica URL)

È possibile utilizzare i seguenti caratteri direttamente nei parametri di query del manifesto:

  • Caratteri alfanumerici (A-Z, a-z, 0-9)

  • Periodi (.)

  • Trattini (-)

  • Sottolineature (_)

  • Barre rovesciate (\)

Caratteri supportati con codifica URL

I seguenti caratteri speciali sono supportati quando la codifica URL è codificata:

  • periodo (.) = %2E

  • trattino (-) = %2D

  • carattere di sottolineatura (_) = %5F

  • percentuale (%) = %25

  • tilde (~) = %7E

  • barra in avanti (/) = %2F

  • asterisco (*) = %2A

  • è uguale a (=) = %3D

  • domanda (?) = %3 F

Supporto per la codifica degli URL

MediaTailor supporta il segno di percentuale (%) quando lo si utilizza nella codifica URL (ad esempio, hello%20world = hello world). È possibile utilizzare qualsiasi carattere con codifica URL, purché si tratti di codifiche URL valide in base alla specifica HTTP.

Caratteri non supportati

Non è possibile utilizzare i seguenti caratteri nei parametri di query del manifesto senza la codifica URL::,,,?, & =%, / (barra diretta).

Importante

MediaTailor non supporta caratteri doppi come%%% o ==. Non è possibile utilizzare full URLs come valori dei parametri di query manifest a causa delle restrizioni relative ai caratteri.

Limiti di lunghezza

La lunghezza totale di tutti i parametri di query del manifesto (chiavi e valori combinati) non deve superare i 2000 caratteri.

Limiti alla lunghezza dei parametri ADS

Le seguenti limitazioni di lunghezza si applicano ai parametri utilizzati nelle richieste all'ADS:

  • Nome del parametro ADS: massimo 10.000 caratteri

  • Valore del parametro ADS: massimo 25.000 caratteri

  • URL ADS: massimo 25.000 caratteri

MediaTailor alias di configurazione e sostituzione dinamica delle variabili

AWS Elemental MediaTailor gli alias di configurazione consentono la sostituzione dinamica delle variabili nei domini URL e in altri campi supportati. Utilizzate questa funzionalità per utilizzare più domini e URLs configurarli dinamicamente durante l'inizializzazione della sessione.

Campi supportati per la sostituzione dinamica delle variabili

È possibile utilizzare variabili dinamiche nei seguenti campi di configurazione:

  • VideoContentSourceUrl

  • AdDecisionServerUrl

  • LivePreroll.AdDecisionServerUrl

  • AdSegmentUrlPrefix

  • ContentSegmentUrlPrefix

  • TranscodeProfileName

  • SlateAdUrl

  • StartUrl

  • EndUrl

Regole dei parametri a livello di dominio

Quando si utilizzano variabili dinamiche in porzioni di dominio di URLs, si applicano le seguenti restrizioni:

  • Tutte le variabili dinamiche utilizzate nei domini devono essere specificate come ConfigurationAliases

  • Può solo essere player_params

  • L'elenco dei valori con alias deve essere esaustivo

  • Gli alias non validi o mancanti generano errori HTTP 400

ConfigurationAliases Struttura dei parametri API

Il ConfigurationAliases parametro utilizza la seguente struttura JSON: 

{
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
            "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        }
    }
}
Coerenza delle API

playerParamsè ora supportato come alternativa ads e adsParams per una migliore coerenza delle API.

Comportamento di riserva per gli alias mancanti

Quando gli alias di configurazione non vengono trovati o non sono validi, MediaTailor implementa il seguente comportamento di fallback:

  • Variabili di dominio: se un alias di variabile di dominio è mancante o non valido, la richiesta ha esito negativo con il codice di stato HTTP 400. Tutte le variabili di dominio devono avere alias validi definiti.

  • Variabili non di dominio: per le variabili utilizzate in parti non di dominio URLs (come elementi di percorso o parametri di query), gli alias mancanti comportano la sostituzione di stringhe vuote.

  • Convalida della configurazione: MediaTailor verifica che tutti gli alias richiesti siano presenti durante le operazioni di creazione e aggiornamento della configurazione.

Casi d'uso avanzati con configurazioni multiple

Gli alias di configurazione consentono architetture sofisticate a più configurazioni per i seguenti scenari:

Esempio Configurazione completa con alias

L'esempio seguente mostra una configurazione completa che include alias di configurazione e variabili di dominio dinamiche: 

PUT /playbackConfiguration
{
    "Name": "aliasedConfig",
    "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
    "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.id]",
    
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc",
            "iad": "xyz"
        },
        "player_params.region": {
            "pdx": "us-west-2",
            "iad": "us-east-1"
        },
        "player_params.endpoint_id": {
            "pdx": "abcd",
            "iad": "wxyz"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}
Esempio Inizializzazione della sessione con alias

Utilizzando la configurazione precedente, create una richiesta di inizializzazione della sessione specificando le variabili e gli alias del player: 

POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}
Esempio Flusso di elaborazione dei parametri

MediaTailor sostituisce le stringhe di alias con i valori mappati negli alias di configurazione. L'elaborazione genera le seguenti richieste:

  • Richiesta ADS:

    https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

  • VideoContentSource richiesta:

    https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd

  • AdSegmentUrlPrefix:

    https://ads-west.cdn.example.com/ads/

  • ContentSegmentUrlPrefix:

    https://content-west.cdn.example.com/content/

  • TranscodeProfileName:

    mobile_optimized

  • SlateAdUrl:

    https://slate-west.example.com/slate/brand_slate.mp4

  • StartUrl:

    https://tracking-west.example.com/start?session=[session.id]

  • EndUrl:

    https://tracking-west.example.com/end?session=[session.id]

MediaTailor passaggio di parametri all'ADS

AWS Elemental MediaTailor supporta l'impostazione di variabili dinamiche nelle MediaTailor richieste all'ADS utilizzando i seguenti passaggi.

Metodi di inizializzazione della sessione

MediaTailor supporta diversi metodi per l'inizializzazione della sessione e il passaggio dei parametri:

  1. POST con Request Body:

    POST <master>.m3u8
{
    "adsParams": {"param1": "value1", "param2": "value2"},
    "playerParams": {"param3": "value3"}
}

  2. Parametri di interrogazione nell'URL:

    GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3
Importante

È possibile specificare i parametri una sola volta, al momento dell'inizializzazione. Gli alias di configurazione si risolvono in valori effettivi prima dell'inoltro.

Per passare le informazioni relative alla sessione e al lettore all'ADS

  1. Collabora con ADS per determinare le informazioni di cui ha bisogno per rispondere a una richiesta di annuncio. AWS Elemental MediaTailor

  2. Crea una configurazione MediaTailor che utilizzi un modello di URL di richiesta ADS che soddisfi i requisiti ADS. Nell'URL, includere parametri statici e segnaposto per i parametri dinamici. Immettere l'URL modello nel campo Ad decision server (Server di annunci) della configurazione.

    Nel seguente URL modello di esempio, correlation fornisce i dati relativi alla sessione e deviceType fornisce i dati relativi al lettore: 

    https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]

  3. Nel lettore, configurare la richiesta di inizializzazione di sessione affinché AWS Elemental MediaTailor fornisca i parametri per i dati del lettore. Includere i parametri nella richiesta di inizializzazione di sessione e ometterli dalle richieste successive per la sessione.

    Il tipo di chiamata che il giocatore effettua per inizializzare la sessione determina se il giocatore (client) o MediaTailor (server) fornisce report sul tracciamento degli annunci per la sessione. Per informazioni su queste due opzioni, consulta Segnalazione e tracciamento dei dati .

    Effettuare uno dei seguenti tipi di chiamata, in base al reporting di tracciamento degli annunci desiderato (lato server o lato client). In entrambe le chiamate di esempio, userID è destinato all'ADS e auth_token è destinato all'origine:

    • (Opzione) Richiedi la segnalazione del tracciamento degli annunci sul lato server: inserisci come prefisso i parametri che desideri inviare all'ADS. MediaTailor ads Omettere il prefisso per i parametri che MediaTailor deve inviare al server di origine:

      I seguenti esempi mostrano le richieste in arrivo per HLS e DASH to. AWS Elemental MediaTailor MediaTailor utilizza il deviceType nella sua richiesta all'ADS e auth_token nella sua richiesta al server di origine.

      Esempio HLS:

      GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh

      Esempio DASH:

      GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh

    • (Opzione) Richiesta di report sul tracciamento degli annunci sul lato client: fornisci i parametri per l'ADS all'interno di un oggetto. adsParams

      Esempio HLS:

      POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }

      Esempio DASH:

      POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }

Quando il giocatore avvia una sessione, AWS Elemental MediaTailor sostituisce le variabili nell'URL della richiesta ADS del modello con i dati della sessione e i parametri del giocatore. ads Passa i parametri rimanenti dal lettore al server di origine.

Esempio MediaTailor richieste con variabili pubblicitarie

Gli esempi seguenti mostrano le chiamate all'ADS e al server di origine da AWS Elemental MediaTailor che corrispondono agli esempi precedenti di chiamate di inizializzazione della sessione del lettore:

  • MediaTailor chiama l'ADS con i dati della sessione e il tipo di dispositivo del giocatore: 

    https://my.ads.server.com/path?correlation=896976764&deviceType=ipad

  • MediaTailor chiama il server di origine con il token di autorizzazione del giocatore.

    • Esempio HLS:

      https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh

    • Esempio DASH:

      https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh

Utilizzo avanzato

È possibile personalizzare la richiesta ADS in molti modi con i dati relativi al lettore e alla sessione. Devi solo includere il nome host ADS.

Di seguito sono forniti alcuni esempi di personalizzazione della richiesta:

  • Concatenare i parametri del lettore e i parametri della sessione per creare nuovi parametri. Esempio: 

    https://my.ads.com?key1=[player_params.value1][session.id]

  • Usare un parametro del lettore come parte di un elemento di percorso. Esempio:

    https://my.ads.com/[player_params.path]?key=value

  • Usare i parametri del lettore per passare sia gli elementi del percorso che le chiavi stesse, anziché solo valori. Esempio: 

    https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]

MediaTailor risoluzione dei problemi relativi agli alias di configurazione

AWS Elemental MediaTailor fornisce una guida sistematica alla risoluzione dei problemi più comuni relativi agli alias di configurazione e agli scenari di errore.

errori di convalida degli alias di configurazione

Quando gli alias di configurazione sono mancanti o non validi, MediaTailor restituisce risposte di errore specifiche per aiutare a identificare il problema.

Scenari di errore comuni

La tabella seguente descrive gli errori più comuni relativi agli alias di configurazione e i relativi passaggi di risoluzione:

Errore Causa Risoluzione
HTTP 400: alias del parametro del giocatore non valido Valore del parametro del giocatore non trovato in ConfigurationAliases Verifica che il valore del parametro player esista come chiave nella ConfigurationAliases mappatura corrispondente
HTTP 400: alias di configurazione richiesto mancante Variabile di dominio utilizzata senza voce corrispondente ConfigurationAliases Aggiungi il parametro player mancante a ConfigurationAliases con tutte le mappature degli alias richieste
HTTP 400: convalida della configurazione non riuscita ConfigurationAliases la struttura è malformata o incompleta Convalida la struttura JSON e assicurati che tutte le variabili di dominio abbiano alias corrispondenti
Sostituzione di stringhe vuote in URLs Alias variabile non di dominio non trovato Aggiungi la mappatura degli alias mancante o fornisci il valore predefinito in ConfigurationAliases
Lista di controllo per la convalida

Utilizza la seguente lista di controllo per convalidare la configurazione degli alias di configurazione:

  1. Copertura delle variabili di dominio: assicurati che tutte le variabili utilizzate nelle porzioni del URLs dominio abbiano voci corrispondenti ConfigurationAliases

  2. Completezza degli alias: verifica che tutti i possibili valori dei parametri del giocatore siano inclusi come chiavi nelle mappature degli alias

  3. Struttura JSON: verifica che il JSON sia formattato e annidato correttamente ConfigurationAliases

  4. Denominazione dei parametri: conferma che tutti i parametri del giocatore utilizzino il prefisso player_params.

  5. Coerenza dei valori: assicurati che i valori degli alias siano validi per l'uso previsto (nomi di profiloURLs, ecc.)

Risoluzione degli alias di configurazione per il debug

Segui questo approccio sistematico per eseguire il debug dei problemi di risoluzione degli alias di configurazione.

Step-by-step metodologia di debug

Utilizza i seguenti passaggi per identificare e risolvere i problemi relativi agli alias di configurazione:

Procedura di debug degli alias di configurazione

  1. Verifica della struttura di configurazione: verifica che la configurazione di riproduzione includa una formattazione corretta ConfigurationAliases

    {
    "ConfigurationAliases": {
        "player_params.example_param": {
            "alias1": "value1",
            "alias2": "value2"
        }
    }
}

  2. Controlla il formato dei parametri del lettore: assicurati che l'inizializzazione della sessione includa i parametri del lettore formattati correttamente

    {
    "playerParams": {
        "example_param": "alias1"
    }
}

  3. Convalida la mappatura degli alias: conferma che il valore del parametro player («alias1") esista come chiave nella mappatura ConfigurationAliases

  4. Esegui il test con una configurazione semplice: inizia con una configurazione minima per isolare il problema

  5. Monitora le risposte agli errori: controlla le risposte MediaTailor di errore per messaggi di convalida specifici

  6. Verifica risoluzione URLs: verifica che le risoluzioni finali URLs siano valide e accessibili

Procedure consigliate per gli alias di configurazione

Segui queste best practice per garantire un'implementazione affidabile degli alias di configurazione.

Considerazioni relative alla sicurezza

Implementa le seguenti misure di sicurezza quando utilizzi gli alias di configurazione:

  • Convalida dell'input: convalida tutti i valori dei parametri del giocatore prima di utilizzarli nella risoluzione degli alias

  • Eliminazione dei valori degli alias: assicurati che i valori degli alias contengano solo i caratteri e i formati previsti

  • Restrizioni relative al dominio: limita gli alias di dominio a domini affidabili e controllati

  • Controllo degli accessi: limita la modifica della configurazione solo al personale autorizzato

Ottimizzazione delle prestazioni

Ottimizza le prestazioni degli alias di configurazione con questi consigli:

  • Riduci al minimo il numero di alias: utilizza solo gli alias necessari per ridurre il sovraccarico di elaborazione

  • Denominazione efficiente: utilizza convenzioni di denominazione chiare e coerenti per alias e parametri

  • Valori predefiniti: forniscono alias predefiniti ragionevoli per casi d'uso comuni

  • Memorizzazione nella cache della configurazione: sfrutta la memorizzazione nella cache MediaTailor della configurazione per migliorare le prestazioni

Manutenzione e monitoraggio

Mantieni operazioni affidabili sugli alias di configurazione con queste pratiche:

  • Convalida regolare: verifica periodicamente che tutti i mapping degli alias siano aggiornati e funzionanti

  • Monitoraggio degli errori: monitora gli errori HTTP 400 relativi ad alias mancanti o non validi

  • Documentazione: mantieni una documentazione chiara di tutte le mappature degli alias e dei relativi scopi

  • Procedure di test: implementa test completi per tutte le combinazioni di alias

Per ulteriori informazioni sull'utilizzo delle variabili dinamiche di dominio, sessione e giocatore, seleziona l'argomento pertinente.

Argomenti