MediaTailor dynamische Anzeigenvariablen - AWS Elemental MediaTailor
MediaTailor ParameterreferenzMediaTailor Aliase für KonfigurationenMediaTailor Übergabe von ADS-ParameternMediaTailorFehlerbehebung bei Aliasnamen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

MediaTailor dynamische Anzeigenvariablen

AWS Elemental MediaTailor Eine Anfrage an den Ad Decision Server (ADS) enthält Informationen über die aktuelle Anzeigesitzung. Diese Informationen helfen dem ADS bei der Auswahl der Anzeigen, die für seine Antwort am besten geeignet sind. Wenn Sie die ADS-Vorlage in Ihrer MediaTailor Konfiguration konfigurieren, können Sie dynamische Variablen, auch Makros genannt, einbeziehen. Dynamische Variablen sind austauschbare Zeichenketten.

Dynamische Variablen können die folgenden Formen annehmen:

  • Statische Werte — Werte, die sich von einer Sitzung zur nächsten nicht ändern. Beispiel: Der Antworttyp, den MediaTailor von ADS erwartet.

  • Domain-Variablen — Dynamische Variablen, die für URL-Domains verwendet werden können, wie z. B. der my-ads-server.com-Teil der URL http://my-ads-server.com. Details hierzu finden Sie unter MediaTailor Domain-Variablen.

  • Sitzungsdaten — Dynamische Werte, die von MediaTailor für jede Sitzung bereitgestellt werden, z. B. die Sitzungs-ID. Details hierzu finden Sie unter MediaTailor Sitzungsvariablen.

  • Spielerdaten — Dynamische Werte, die vom Spieler für jede Sitzung bereitgestellt werden. Diese beschreiben den Inhaltsbetrachter und helfen dem ADS dabei, zu bestimmen, welche Anzeigen in den Stream eingefügt werden MediaTailor sollen. Details hierzu finden Sie unter MediaTailor Spielervariablen.

MediaTailor Parameterreferenz und Einschränkungen

AWS Elemental MediaTailor bietet umfassende Informationen zu Zeichenbeschränkungen und Längenbeschränkungen für Parameter sowie zu unterstützten Formaten sowohl für Manifestabfrageparameter als auch für ADS-Parameter.

Zeichenbeschränkungen für Manifest-Abfrageparameter

Manifest-Abfrageparameter unterstützen bestimmte Zeichen und haben definierte Längenbeschränkungen.

Unterstützte Zeichen (ohne URL-Kodierung)

Sie können die folgenden Zeichen direkt in Manifest-Abfrageparametern verwenden:

  • Alphanumerische Zeichen (A-Z, a-z, 0-9)

  • Perioden (.)

  • Bindestriche (-)

  • Unterstriche (_)

  • Backslashes (\)

Unterstützte Zeichen mit URL-Kodierung

Die folgenden Sonderzeichen werden unterstützt, wenn sie URL-kodiert sind:

  • Zeitraum (.) = %2E

  • Gedankenstrich (-) = %2D

  • Unterstrich (_) = %5F

  • Prozent (%) = %25

  • Tilde (~) = %7E

  • Schrägstrich (/) = %2F

  • Sternchen (*) = %2A

  • entspricht (=) = %3D

  • Frage (?) = %3F

Unterstützung für URL-Kodierung

MediaTailor unterstützt das Prozentzeichen (%), wenn Sie es in der URL-Kodierung verwenden (z. B. hello%20world = hello world). Sie können beliebige URL-kodierte Zeichen verwenden, sofern es sich um gültige URL-Kodierungen gemäß der HTTP-Spezifikation handelt.

Nicht unterstützte Zeichen

Sie können die folgenden Zeichen nicht in Manifest-Abfrageparametern ohne URL-Kodierung verwenden::,,,?, & =%, / (Schrägstrich).

Wichtig

MediaTailor unterstützt keine Doppelzeichen wie%%% oder ==. Aufgrund von Zeichenbeschränkungen können Sie keine vollständigen Abfrageparameterwerte URLs als Manifest verwenden.

Längenbeschränkungen

Die Gesamtlänge aller Manifest-Abfrageparameter (Schlüssel und Werte zusammen) darf 2000 Zeichen nicht überschreiten.

Längenbeschränkungen für ADS-Parameter

Die folgenden Längenbeschränkungen gelten für Parameter, die in Anfragen an das ADS verwendet werden:

  • ADS-Parametername: Maximal 10.000 Zeichen

  • ADS-Parameterwert: Maximal 25.000 Zeichen

  • ADS-URL: Maximal 25.000 Zeichen

MediaTailor Konfigurationsaliase und dynamische Variablenersetzung

AWS Elemental MediaTailor Konfigurationsaliase ermöglichen den dynamischen Variablenersatz in URL-Domänen und anderen unterstützten Feldern. Verwenden Sie diese Funktion, um mehrere Domänen zu verwenden und sie URLs während der Sitzungsinitialisierung dynamisch zu konfigurieren.

Unterstützte Felder für den dynamischen Variablenersatz

Sie können dynamische Variablen in den folgenden Konfigurationsfeldern verwenden:

  • VideoContentSourceUrl

  • AdDecisionServerUrl

  • LivePreroll.AdDecisionServerUrl

  • AdSegmentUrlPrefix

  • ContentSegmentUrlPrefix

  • TranscodeProfileName

  • SlateAdUrl

  • StartUrl

  • EndUrl

Parameterregeln auf Domänenebene

Wenn Sie dynamische Variablen in Domänenteilen von verwenden URLs, gelten die folgenden Einschränkungen:

  • Alle in Domänen verwendeten dynamischen Variablen müssen als angegeben werden ConfigurationAliases

  • Kann nur sein player_params

  • Die Liste der Aliaswerte muss vollständig sein

  • Ungültige oder fehlende Aliase führen zu HTTP 400-Fehlern

ConfigurationAliases Struktur der API-Parameter

Der ConfigurationAliases Parameter verwendet die folgende JSON-Struktur: 

{
    "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"
        }
    }
}
API-Konsistenz

playerParamswird jetzt als Alternative zur ads und adsParams für eine verbesserte API-Konsistenz unterstützt.

Fallback-Verhalten für fehlende Aliase

Wenn Konfigurationsaliase nicht gefunden werden oder ungültig sind, MediaTailor implementiert das folgende Fallback-Verhalten:

  • Domain-Variablen: Wenn ein Domainvariablen-Alias fehlt oder ungültig ist, schlägt die Anfrage mit dem HTTP 400-Statuscode fehl. Für alle Domänenvariablen müssen gültige Aliase definiert sein.

  • Nicht-Domain-Variablen: Bei Variablen, die in Teilen verwendet werden, die nicht zur Domäne gehören URLs (wie Pfadelemente oder Abfrageparameter), führen fehlende Aliase dazu, dass leere Zeichenketten ersetzt werden.

  • Konfigurationsvalidierung: MediaTailor Überprüft, ob alle erforderlichen Aliase bei der Erstellung und Aktualisierung der Konfiguration vorhanden sind.

Fortgeschrittene Anwendungsfälle mit mehreren Konfigurationen

Konfigurationsaliase ermöglichen ausgeklügelte Architekturen mit mehreren Konfigurationen für die folgenden Szenarien:

Beispiel Vollständige Konfiguration mit Aliasnamen

Das folgende Beispiel zeigt eine vollständige Konfiguration, die Konfigurationsaliase und dynamische Domänenvariablen umfasst: 

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"
        }
    }
}
Beispiel Initialisierung der Sitzung mit Aliasen

Erstellen Sie mit der vorherigen Konfiguration eine Anfrage zur Sitzungsinitialisierung, in der Sie die Spielervariablen und Aliase angeben: 

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"
    }
}
Beispiel Ablauf der Parameterverarbeitung

MediaTailor ersetzt die Aliaszeichenfolgen durch die zugewiesenen Werte in den Konfigurationsaliasen. Die Verarbeitung führt zu den folgenden Anfragen:

  • ADS-Anfrage:

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

  • VideoContentSource Anfrage:

    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 Übergabe von Parametern an das ADS

AWS Elemental MediaTailor unterstützt die Einrichtung dynamischer Variablen in MediaTailor Anfragen an das ADS mithilfe der folgenden Schritte.

Methoden zur Sitzungsinitialisierung

MediaTailor unterstützt mehrere Methoden zur Sitzungsinitialisierung und Parameterübergabe:

  1. POST mit dem Hauptteil der Anfrage:

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

  2. Abfrageparameter in der URL:

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

Sie können Parameter bei der Initialisierung nur einmal angeben. Konfigurationsaliase werden vor der Weiterleitung in tatsächliche Werte aufgelöst.

So übergeben Sie Sitzungs- und Player-Informationen an den ADS

  1. Ermitteln Sie gemeinsam mit dem ADS, welche Informationen benötigt werden, um auf eine Anzeigenanfrage von AWS Elemental MediaTailor zu antworten.

  2. Erstellen Sie eine Konfiguration MediaTailor , die eine ADS-Vorlagen-URL verwendet, die die ADS-Anforderungen erfüllt. Schließen Sie in die URL statische Parameter und Platzhalter für dynamische Parameter ein. Geben Sie Ihre Vorlagen-URL in das Feld Ad decision server (Entscheidungsserver für Werbung) ein.

    In der folgenden Beispielvorlagen-URL bietet correlation Sitzungsdaten und deviceType bietet Player-Daten: 

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

  3. Konfigurieren Sie auf dem Player die Sitzungsinitiierungs-Anforderung für AWS Elemental MediaTailor , um Parameter für die Player-Daten bereitzustellen. Sie brauchen die Parameter nur in die Sitzungsinitiierungs-Anforderung einzuschließen und können sie in nachfolgenden Anforderungen für die Sitzung weglassen.

    Die Art des Aufrufs, den der Player zur Initialisierung der Sitzung tätigt, bestimmt, ob der Player (Client) oder MediaTailor (Server) Werbeverfolgungsberichte für die Sitzung bereitstellt. Weitere Informationen zu diesen beiden Optionen finden Sie unter Daten zur Berichterstattung und Nachverfolgung .

    Führen Sie je nachdem, ob Sie an server- oder clientseitigen Werbenachverfolgungs-Berichten interessiert sind, den jeweiligen der folgenden Aufrufe durch. Bei beiden Beispielaufrufen ist userID für den ADS und auth_token für den Ursprungs-Server vorgesehen:

    • (Option) Aufruf für serverseitiges Ad-Tracking-Reporting — Stellen Sie den Parametern, die Sie an das ADS senden MediaTailor möchten, ein Präfix voran. ads Lassen Sie das Präfix bei Parametern weg, die MediaTailor an den Ursprungs-Server senden soll:

      Die folgenden Beispiele zeigen eingehende Anfragen für HLS und DASH an. AWS Elemental MediaTailor MediaTailor verwendet das deviceType in seiner Anfrage an das ADS und das auth_token in seiner Anfrage an den Ursprungsserver.

      HLS-Beispiel:

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

      DASH-Beispiel:

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

    • (Option) Aufruf für clientseitiges Ad-Tracking-Reporting — Geben Sie Parameter für das ADS innerhalb eines Objekts an. adsParams

      HLS-Beispiel:

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

      DASH-Beispiel:

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

Wenn der Player eine Sitzung initiiert, werden die Variablen in der ADS-Anforderungs-URL der Vorlage durch die Sitzungsdaten und die Parameter des Players AWS Elemental MediaTailor ersetzt. ads Die verbleibenden Parameter werden vom Player an den Ursprungs-Server übergeben.

Beispiel MediaTailor Anfragen mit Anzeigenvariablen

Die folgenden Beispiele zeigen die Aufrufe von AWS Elemental MediaTailor an den ADS und den Ursprungs-Server entsprechend den voranstehenden Beispielen für Sitzungsinitialisierungs-Aufrufe des Players:

  • MediaTailor ruft das ADS mit Sitzungsdaten und dem Gerätetyp des Players auf: 

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

  • MediaTailor ruft den Ursprungsserver mit dem Autorisierungstoken des Spielers auf.

    • HLS-Beispiel:

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

    • DASH-Beispiel:

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

Fortgeschrittene Nutzung

Sie können die ADS-Anforderung in vielerlei Hinsicht mit Player- und Sitzungsdaten anpassen. Sie müssen nur den ADS-Hostnamen angeben.

Die folgenden Beispiele zeigen einige der Möglichkeiten, wie Sie Ihre Anforderung anpassen können:

  • Erstellen Sie durch Verketten von Player-Parametern und Sitzungsparametern neue Parameter. Beispiel: 

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

  • Verwenden Sie einen Player-Parameter als Teil eines Pfadelements. Beispiel:

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

  • Verwenden Sie Player-Parameter, um nicht nur die Werte, sondern sowohl Pfadelemente als auch die Schlüssel selbst zu übergeben. Beispiel: 

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

MediaTailor Fehlerbehebung bei Konfigurationsaliasnamen

AWS Elemental MediaTailor bietet systematische Anleitungen zur Fehlerbehebung bei häufigen Problemen mit Konfigurationsaliasen und Fehlerszenarien.

Fehler bei der Validierung von Konfigurations-Alias

Wenn Konfigurationsaliase fehlen oder ungültig sind, werden spezifische Fehlerantworten MediaTailor zurückgegeben, um das Problem zu identifizieren.

Häufige Fehlerszenarien

In der folgenden Tabelle werden häufig auftretende Fehler bei Konfigurationsalias und die Schritte zur Behebung dieser Fehler beschrieben:

Fehler Ursache Auflösung
HTTP 400: Ungültiger Player-Parameter-Alias Der Wert des Spielerparameters wurde nicht gefunden in ConfigurationAliases Stellen Sie sicher, dass der Player-Parameterwert als Schlüssel in der entsprechenden ConfigurationAliases Zuordnung existiert
HTTP 400: Der erforderliche Konfigurationsalias fehlt Die Domänenvariable wurde ohne entsprechenden ConfigurationAliases Eintrag verwendet Fügen Sie den fehlenden Player-Parameter ConfigurationAliases mit allen erforderlichen Aliaszuordnungen hinzu
HTTP 400: Die Überprüfung der Konfiguration ist fehlgeschlagen ConfigurationAliases Die Struktur ist fehlerhaft oder unvollständig Überprüfen Sie die JSON-Struktur und stellen Sie sicher, dass alle Domänenvariablen über entsprechende Aliase verfügen
Ersetzung einer leeren Zeichenfolge in URLs Alias für Nicht-Domain-Variablen wurde nicht gefunden Fügen Sie eine fehlende Aliaszuordnung hinzu oder geben Sie den Standardwert in an ConfigurationAliases
Checkliste für die Validierung

Verwenden Sie die folgende Checkliste, um die Einrichtung Ihrer Konfigurationsaliase zu überprüfen:

  1. Abdeckung von Domänenvariablen: Stellen Sie sicher, dass alle Variablen, die in Domänenteilen von verwendet werden, entsprechende Einträge URLs haben ConfigurationAliases

  2. Vollständigkeit der Alias: Stellen Sie sicher, dass alle möglichen Player-Parameterwerte als Schlüssel in den Aliaszuordnungen enthalten sind

  3. JSON-Struktur: Stellen Sie sicher, dass das ConfigurationAliases JSON richtig formatiert und verschachtelt ist

  4. Benennung der Parameter: Stellen Sie sicher, dass alle Player-Parameter das Präfix verwenden player_params.

  5. Einheitlichkeit der Werte: Stellen Sie sicherURLs, dass Aliaswerte für den vorgesehenen Verwendungszweck (Profilnamen usw.) gültig sind

Aliasauflösung der Konfiguration beim Debuggen

Folgen Sie diesem systematischen Ansatz, um Probleme mit der Auflösung von Konfigurationsalias zu debuggen.

Step-by-step Debugging-Methodik

Gehen Sie wie folgt vor, um Probleme mit Konfigurationsalias zu identifizieren und zu lösen:

Verfahren zum Debuggen von Konfigurationsalias

  1. Überprüfen Sie die Konfigurationsstruktur: Stellen Sie sicher, dass Ihre Wiedergabekonfiguration korrekt formatierte Dateien enthält ConfigurationAliases

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

  2. Überprüfen Sie das Format der Player-Parameter: Stellen Sie sicher, dass die Sitzungsinitialisierung die korrekt formatierten Player-Parameter enthält

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

  3. Alias-Zuordnung validieren: Vergewissern Sie sich, dass der Player-Parameterwert („alias1") als Schlüssel in der Zuordnung existiert ConfigurationAliases

  4. Testen Sie mit einer einfachen Konfiguration: Beginnen Sie mit einer Minimalkonfiguration, um das Problem zu isolieren

  5. Überwachen Sie die Fehlerantworten: Überprüfen Sie die MediaTailor Fehlerantworten auf bestimmte Bestätigungsmeldungen

  6. Überprüfen Sie, ob das Problem gelöst wurde URLs: Stellen Sie sicher, dass die endgültigen Lösungen gültig und zugänglich URLs sind

Bewährte Methoden für Konfigurationsaliase

Folgen Sie diesen bewährten Methoden, um eine zuverlässige Implementierung von Konfigurationsalias sicherzustellen.

Sicherheitsüberlegungen

Implementieren Sie die folgenden Sicherheitsmaßnahmen, wenn Sie Konfigurationsaliase verwenden:

  • Eingabevalidierung: Überprüfen Sie alle Player-Parameterwerte, bevor Sie sie bei der Alias-Auflösung verwenden

  • Bereinigung von Aliaswerten: Stellen Sie sicher, dass Aliaswerte nur die erwarteten Zeichen und Formate enthalten

  • Domain-Einschränkungen: Beschränken Sie Domain-Aliase auf vertrauenswürdige, kontrollierte Domains

  • Zugriffskontrolle: Beschränken Sie Konfigurationsänderungen nur auf autorisiertes Personal

Leistungsoptimierung

Optimieren Sie die Leistung von Konfigurationsalias mit diesen Empfehlungen:

  • Minimierung der Aliasanzahl: Verwenden Sie nur die benötigten Aliase, um den Verarbeitungsaufwand zu reduzieren

  • Effiziente Benennung: Verwenden Sie klare, konsistente Benennungskonventionen für Aliase und Parameter

  • Standardwerte: Stellen Sie sinnvolle Standardaliase für allgemeine Anwendungsfälle bereit

  • Konfigurations-Caching: Nutzen Sie MediaTailor das Konfigurations-Caching, um die Leistung zu verbessern

Wartung und Überwachung

Sorgen Sie mit diesen Methoden für zuverlässige Alias-Alias-Operationen bei der Konfiguration:

  • Regelmäßige Überprüfung: Stellen Sie regelmäßig sicher, dass alle Aliaszuordnungen aktuell und funktionsfähig sind

  • Fehlerüberwachung: Achten Sie auf HTTP 400-Fehler, die auf fehlende oder ungültige Aliase zurückzuführen sind

  • Dokumentation: Sorgen Sie für eine klare Dokumentation aller Aliaszuordnungen und ihrer Zwecke

  • Testverfahren: Implementieren Sie umfassende Tests für alle Alias-Kombinationen

Weitere Informationen zur Verwendung dynamischer Domänen-, Sitzungs- und Player-Variablen finden Sie unter dem entsprechenden Thema.

Themen