Benutzerdefinierte Gebotseinstellung implementieren

Mit der Display & Video 360 API können Sie Implementierungen der benutzerdefinierten Gebotseinstellung verwalten. Sie können benutzerdefinierte Gebotsalgorithmen erstellen, einzelne Scripts hochladen und überprüfen und einer Ressource einen bestimmten Algorithmus als Gebotsstrategie zuweisen.

Auf dieser Seite wird beschrieben, wie Sie mit der Display & Video 360 API Algorithmen für die benutzerdefinierte Gebotseinstellung erstellen, aktualisieren und zuweisen. Jeder Abschnitt enthält ein Codebeispiel.

Algorithmus für benutzerdefinierte Gebote erstellen

Ein CustomBiddingAlgorithm-Objekt stellt einen einzelnen Algorithmus dar, den Sie einer Werbebuchung zur Verwendung in der Gebotsstrategie zuweisen können. Dieses Objekt enthält Details zum Algorithmus, z. B. customBiddingAlgorithmType, entityStatus und customBiddingAlgorithmState. Sie können CustomBiddingScript-Objekte als untergeordnete Ressourcen für den Algorithmus erstellen.

Hinweis :In diesem Leitfaden geht es um benutzerdefinierte Gebotseinstellungen, die auf Skripten basieren. Algorithmen, die in Ads Data Hub oder über das Tool „Zielerstellung“ in der Display & Video 360-Benutzeroberfläche erstellt wurden, können abgerufen und zugewiesen, aber nicht vollständig verwaltet werden.

Hier sehen Sie ein Beispiel für das Erstellen eines skriptbasierten benutzerdefinierten Gebotsalgorithmus:

Python

# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

Algorithmuszugriff verwalten

Algorithmen für die benutzerdefinierte Gebotseinstellung können einem Partner oder einem Werbetreibenden gehören. Auf Algorithmen, die einem Partner gehören, kann von diesem Partner und allen untergeordneten Werbetreibenden, die im Feld sharedAdvertiserIds aufgeführt sind, zugegriffen und sie können von diesen bearbeitet werden. Auf Algorithmen, die einem Werbetreibenden gehören, kann von diesem und seinem übergeordneten Partner zugegriffen und sie können von diesen bearbeitet werden. Sie können jedoch nicht für andere Werbetreibende freigegeben werden.

Hinweis :Wenn Sie einen benutzerdefinierten Gebotsalgorithmus erstellen, benötigen Sie Lese-/Schreibzugriff auf den Partner oder Werbetreibenden, den Sie als Inhaber zuweisen.

Wenn Sie den Algorithmus nur für einen einzelnen Werbetreibenden verwenden, weisen Sie den Werbetreibenden mit dem Feld advertiserId als Inhaber zu. Weisen Sie andernfalls den übergeordneten Partner der Werbetreibenden als Inhaber mit dem Feld partnerId zu und gewähren Sie den Werbetreibenden Zugriff mit dem Feld sharedAdvertiserIds.

Skript hochladen

Nachdem Sie einen Algorithmus für die benutzerdefinierte Gebotseinstellung erstellt haben, müssen Sie ein Script für diesen Algorithmus erstellen. Bei skriptbasierten Algorithmen für die benutzerdefinierte Gebotseinstellung werden von Nutzern bereitgestellte Scripts verwendet, um den Wert einer Impression zu ermitteln. Beispiele für einfache Scripts und eine Liste mit erweiterten Feldern finden Sie in der Display & Video 360-Hilfe.

In den folgenden Abschnitten erfahren Sie, wie Sie einem benutzerdefinierten Gebotsalgorithmus ein neues oder aktualisiertes Skript hinzufügen.

Speicherort einer Scriptressource abrufen

Rufen Sie zuerst einen verfügbaren Ressourcenstandort unter der benutzerdefinierten Gebotsalgorithmusressource mit der Methode customBiddingAlgorithms.uploadScript ab. Diese Anfrage gibt ein CustomBiddingScriptRef-Objekt mit einem Ressourcennamen zurück. Sie können Ihre Scriptdatei an den Speicherort hochladen, der durch den Ressourcennamen vorgegeben ist. Verwenden Sie dann das Referenzobjekt für das Script für die benutzerdefinierte Gebotseinstellung, um Ihre Scriptressource zu erstellen.

Hier ist ein Beispiel dafür, wie Sie den Standort einer verfügbaren Ressource abrufen:

Python

# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')

Skriptdatei hochladen

Nachdem Sie einen verfügbaren Ressourcenpfad abgerufen haben, laden Sie Ihre Scriptdatei mit der Methode media.upload an diesen Pfad im Display & Video 360-System hoch. Diese Methode unterstützt einen einfachen Upload, für den der Abfrageparameter uploadType=media erforderlich ist.

Warnung :Benutzerdefinierte Gebotsskripts dürfen maximal 7 MB groß sein.

Hier sehen Sie ein Beispiel dafür, wie Sie eine Scriptdatei hochladen, wenn Sie ein abgerufenes benutzerdefiniertes Gebotsscript-Referenzobjekt haben:

Python

# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()

Skriptobjekt erstellen

Nachdem die Scriptdatei hochgeladen wurde, erstellen Sie mit der Methode customBiddingAlgorithms.scripts.create eine Ressource für das Script für benutzerdefinierte Gebote. Das in der Anfrage übergebene CustomBiddingScript-Objekt sollte nur das CustomBiddingScriptRef-Objekt als zugewiesenen Wert des Felds script enthalten. Dadurch wird die hochgeladene Skriptdatei der neuen Skriptressource zugeordnet.

Warnung :Wenn Ihre hochgeladene Skriptdatei einen Syntaxfehler enthält, schlägt Ihre customBiddingAlgorithms.scripts.create-Anfrage fehl und es werden Details zum gefundenen Syntaxfehler zurückgegeben. Wenn Sie eine korrigierte Skriptdatei hochladen möchten, müssen Sie diesen Vorgang neu starten, indem Sie einen neuen Speicherort für die Skriptressource abrufen.

Hier ein Beispiel für das Erstellen einer Skriptdatei:

Python

# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')

Nachdem Sie eine Ressource für ein Skript für die benutzerdefinierte Gebotseinstellung erstellt haben, wird das Skript in Display & Video 360 verarbeitet, um sicherzustellen, dass es zum Bewerten von Impressionen verwendet werden kann. Rufen Sie den Status dieser Verarbeitung über das Feld state des Skriptobjekts ab. Sobald das neue Skript akzeptiert wurde, wird es vom Algorithmus für die benutzerdefinierte Gebotseinstellung verwendet, um die Werte von Impressionen zu bewerten. Das geschieht sofort. Sie sollten also sicher sein, dass Sie den Algorithmus aktualisieren möchten, bevor Sie eine neue Skriptressource erstellen.

Algorithmus für benutzerdefinierte Gebote zuweisen

Nachdem Sie einen Algorithmus für die benutzerdefinierte Gebotseinstellung erstellt, ein akzeptiertes Skript hochgeladen und die erforderlichen Voraussetzungen erfüllt haben, können Sie den Algorithmus der Gebotsstrategie einer Werbebuchung oder eines Anzeigenauftrags zuweisen.

Sie können Algorithmen für die benutzerdefinierte Gebotseinstellung in den Gebotsstrategien Ausgaben maximieren und Leistungsziel verwenden, indem Sie BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO und die ID des Algorithmus für die benutzerdefinierte Gebotseinstellung den Feldern performanceGoalType bzw. customBiddingAlgorithmId zuweisen. Je nach Gebotsstrategie sind möglicherweise andere Gebotsparameter verfügbar oder erforderlich.

Hier ist ein Beispiel dafür, wie Sie eine Werbebuchung aktualisieren, damit sie eine Gebotsstrategie vom Typ „Ausgaben maximieren“ mit einem bestimmten benutzerdefinierten Gebotsalgorithmus verwendet:

Python

# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')