Kontextuelles Anzeigen-Targeting mit Elemental Inference

Elemental Inference analysiert Videoinhalte und erstellt für jede Aufnahme Klassifizierungen zur IAB Inhaltstaxonomie sowie Signale zur Markensicherheit. GARM Durch die Integration MediaTailor mit Elemental Inference können Sie Anzeigenanfragen mit kontextbezogenen Metadaten anreichern. Ihr Ad Decision Server kann dann Anzeigen darauf ausrichten, was im Inhalt passiert.

Bei dieser Integration verwenden Sie den AWS_SERVICE_REQUEST Funktionstyp, um die Elemental Inference GetMetadata API während Werbeunterbrechungen aufzurufen. Weitere Hinweise zum Funktionstyp finden Sie unter. AWS Serviceanfrage

Im Folgenden wird der Integrationsablauf beschrieben:

Voraussetzungen

Bevor Sie diese Integration konfigurieren, benötigen Sie Folgendes:

MediaTailor und Elemental Inference müssen sich nicht in derselben Region befinden. AWS Die unterstützten Kombinationen hängen davon ab, ob sich jeder Dienst in einer Opt-in-Region befindet. Details hierzu finden Sie unter Gewähren Sie MediaTailor Zugriff auf Ihren Elemental Inference-Feed. Informationen zu den Regionen, in denen Elementare Inferenz verfügbar ist, finden Sie unter Endpunkte und Kontingente für Elementare Inferenz.

Gewähren Sie MediaTailor Zugriff auf Ihren Elemental Inference-Feed

MediaTailor ruft GetMetadata mit ihren eigenen Dienstanmeldedaten auf. Der Elemental Inference-Zielfeed muss über eine Ressourcenrichtlinie verfügen, die dem MediaTailor Dienstprinzipal vertraut.

MediaTailor fügt automatisch Sicherheits-Header hinzu, die Ihr Konto und Ihre Wiedergabekonfiguration identifizieren, um sicherzustellen, dass Ihr Elemental Inference-Feed überprüfen kann, ob die Anfrage von Ihren Ressourcen stammt. MediaTailor

Die folgende Tabelle zeigt, welcher Service Principal für Ihr Bereitstellungsszenario verwendet werden sollte.

Das folgende Beispiel für eine Ressourcenrichtlinie gewährt die Erlaubnis, einen Feed abzurufen. MediaTailor GetMetadata

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "mediatailor.amazonaws.com"
            },
            "Action": "elemental-inference:GetMetadata",
            "Resource": "arn:aws:elemental-inference:us-west-2:123456789012:feed/my-contextual-feed",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:mediatailor:us-west-2:123456789012:playbackConfiguration/*"
                }
            }
        }
    ]
}

Ersetzen Sie us-west-2 und my-contextual-feed durch Ihre Region, Konto-ID und Feed-ID. 123456789012

Diese aws:SourceAccount Bedingung stellt sicher, dass nur MediaTailor Personen, die im Namen Ihres Kontos tätig sind, auf den Feed zugreifen können. Die aws:SourceArn Bedingung schränkt den Zugriff auf bestimmte Wiedergabekonfigurationen weiter ein. Ersetzen Sie den Platzhalter durch einen bestimmten Namen für die Wiedergabekonfiguration, um den Umfang genauer festzulegen.

Das folgende Beispiel zeigt eine Ressourcenrichtlinie für eine Opt-in-Region, in der der Service Principal den Namen der Region eingibt.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "mediatailor.af-south-1.amazonaws.com"
            },
            "Action": "elemental-inference:GetMetadata",
            "Resource": "arn:aws:elemental-inference:us-west-2:123456789012:feed/my-contextual-feed",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:mediatailor:af-south-1:123456789012:playbackConfiguration/*"
                }
            }
        }
    ]
}

Konfiguration mithilfe der Konsole MediaTailor

Die MediaTailor Konsole bietet eine Anleitung zur Konfiguration der kontextbezogenen Metadatenfunktionen von Elemental Inference. Das Rezept erstellt automatisch die URL, erstellt Vorlagen für den Anforderungstext und generiert Ausgabeausdrücke.

Bevor Sie beginnen

Führen Sie die Schritte unter Voraussetzungen aus. Sie benötigen einen Elemental Inference-Feed mit einer kontextbezogenen Metadatenausgabe, einer Ressourcenrichtlinie, die den MediaTailor Zugriff gewährt, und einen MediaLive Kanal, in dem die kontextbezogene Metadatenanreicherung aktiviert ist.

Erstellen der Funktion

An eine Wiedergabekonfiguration anhängen

Nachdem Sie die Funktion erstellt haben, fügen Sie sie am PRE_ADS_REQUEST Lifecycle-Hook einer Wiedergabekonfiguration hinzu. Sie können es direkt oder als Schritt innerhalb einer SEQUENTIAL_EXECUTOR Funktion anhängen.

Konfiguration mit der API oder CLI

Um genaue Zeitinformationen für Elemental Inference-Abfragen bereitzustellen, aktivieren Sie die MediaLive kontextbezogene Metadatenanreicherung. In den folgenden Abschnitten wird die empfohlene Produktionskonfiguration unter Verwendung von SCTE-35 Markern von MediaLive sowie eine manuelle Konfigurationsoption zu Testzwecken beschrieben.

Verwendung von SCTE-35 Markern aus MediaLive (Produktion)

Wenn es für die kontextbezogene Metadatenanreicherung konfiguriert MediaLive ist, bettet es Elemental Inference-Abfrageparameter direkt in Werbeblockmarkierungen ein. SCTE-35 MediaTailoranalysiert diese automatisch und stellt sie als Variablen zur Verfügung. inference.* Die vollständige Liste der verfügbaren Variablen finden Sie unter. Kontextuelle Metadatenvariablen für Elementare Inferenz (Inferenz.*)

Verwenden Sie diesen Ansatz aus den folgenden Gründen für Produktionsbereitstellungen:

Eine Anleitung zur Aktivierung der kontextbezogenen Metadatenanreicherung auf deinem MediaLive Kanal findest du im Elemental User Guide unter Einrichten der kontextbezogenen Metadatenanreicherung. AWS MediaLive

Das folgende Beispiel zeigt eine vollständige Funktionskonfiguration mithilfe der Anreicherung. SCTE-35

{
    "FunctionId": "eiContextualMetadata",
    "FunctionType": "AWS_SERVICE_REQUEST",
    "AwsServiceRequestConfiguration": {
        "Runtime": "JSONATA",
        "TargetService": "elemental-inference",
        "TargetRegion": "{%inference.region%}",
        "MethodType": "POST",
        "Url": "{%inference.dataEndpoint & '/v1/feed/' & inference.feedId & '/input/0/metadata'%}",
        "Headers": {
            "Content-Type": "application/json"
        },
        "Body": "{%'{\"outputName\": \"my-contextual-output\", \"timeSpecification\": {\"ptsBased\": {\"startPts\": ' & $string(($exists(inference.previousBreakEndPts) and inference.previousBreakEndPts > inference.pts - 30 * inference.timescale ? inference.previousBreakEndPts : inference.pts - 30 * inference.timescale)) & ', \"endPts\": ' & $string(inference.pts + 1) & ', \"timescale\": ' & $string(inference.timescale) & '}}, \"parameters\": {\"contextualMetadata\": {}}}' %}",
        "RequestTimeoutMilliseconds": 2000,
        "Output": {
            "player_params.iabCategories": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), ',') : ''%}",
            "player_params.garmExcluded": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].category), ',') : ''%}"
        }
    }
}

In der folgenden Liste werden die wichtigsten Felder des vorherigen Beispiels erläutert:

{ "FunctionId": "eiContextualMetadata", "RunCondition": "{%inference.enriched = true%}" }

Manuelle Konfiguration (nur zum Testen)

Verwenden Sie diese Konfiguration nur zum Testen. Ohne SCTE-35 Anreicherung von MediaLive müssen Sie die PTS-Werte manuell ermitteln und können nicht von einer dynamischen Zeitabstimmung profitieren. Dieser Modus hat eingeschränkte Funktionen. Wir unterstützen ihn nicht für Produktionsabläufe.

{
    "FunctionId": "eiContextualMetadataManual",
    "FunctionType": "AWS_SERVICE_REQUEST",
    "AwsServiceRequestConfiguration": {
        "Runtime": "JSONATA",
        "TargetService": "elemental-inference",
        "TargetRegion": "us-west-2",
        "MethodType": "POST",
        "Url": "https://abc123.elemental-inference-data.us-west-2.amazonaws.com/v1/feed/my-feed-id/input/0/metadata",
        "Headers": {
            "Content-Type": "application/json"
        },
        "Body": "{%'{\"outputName\": \"my-contextual-output\", \"timeSpecification\": {\"ptsBased\": {\"startPts\": 6300001, \"endPts\": 9000001, \"timescale\": 90000}}, \"parameters\": {\"contextualMetadata\": {}}}' %}",
        "RequestTimeoutMilliseconds": 2000,
        "Output": {
            "player_params.iabCategories": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), ',') : ''%}"
        }
    }
}

An eine Wiedergabekonfiguration anhängen

Nachdem Sie die Funktion erstellt haben, hängen Sie sie mithilfe der PutPlaybackConfiguration API am PRE_ADS_REQUEST Lifecycle-Hook an eine Wiedergabekonfiguration an. Fügen Sie die Funktions-ID in die Funktionszuordnung ein:

{
    "FunctionMappings": {
        "PRE_ADS_REQUEST": {
            "FunctionId": "eiContextualMetadata"
        }
    }
}

Sie können es auch in eine SEQUENTIAL_EXECUTOR To-Kette mit anderen Funktionen einbinden. Weitere Informationen finden Sie unter Kette mit anderen Funktionen.

Verstehe das Zeitfenster

Der Body-Ausdruck erstellt ein PTS-based Zeitfenster für die GetMetadata Anfrage. Die folgende Liste beschreibt die Lookback-Logik:

Verwenden Sie die Antwort in Anzeigenanfragen

In der folgenden Tabelle werden die verfügbaren Präfixe für Ausgabeziele und ihr Verhalten beschrieben.

Weitere Rezepte für Ausgabeausdrücke finden Sie unterBeispiel 3: Kontextuelle Metadaten.

Kette mit anderen Funktionen

Um den Elemental Inference-Aufruf mit anderen Funktionen zu kombinieren, schließen Sie sie in eine ein. SEQUENTIAL_EXECUTOR Das folgende Beispiel zeigt eine Pipeline, in der die zweite Funktion nur ausgeführt wird, wenn Elemental Inference erfolgreich Kategorien zurückgegeben hat.

{
    "FunctionId": "contextualAdPipeline",
    "FunctionType": "SEQUENTIAL_EXECUTOR",
    "SequentialExecutorConfiguration": {
        "Runtime": "JSONATA",
        "FunctionList": [
            { "FunctionId": "eiContextualMetadata" },
            {
                "FunctionId": "buildEnrichedAdsRequest",
                "RunCondition": "{%$exists(player_params.iabCategories) and player_params.iabCategories != ''%}"
            }
        ],
        "TimeoutMilliseconds": 3000
    }
}

Die RunCondition stellt sicher, dass sie buildEnrichedAdsRequest nur ausgeführt wird, wenn die Elemental Inference-Funktion Daten erzeugt. Anschließend können Sie die Ad Decision Server-Anfrage mithilfe der Kontextdaten erstellen.

Fehlerbehebung

In der folgenden Tabelle werden häufig auftretende Probleme und deren Lösungen beschrieben.