Benutzerdefinierte Gebotseinstellung implementieren

Display- und Die Video 360 API ermöglicht die vollständige Verwaltung der benutzerdefinierten Gebote. Implementierungen. Sie können Algorithmen für die benutzerdefinierte Gebotseinstellung erstellen, und einer Ressource einen bestimmten Algorithmus als Gebot .

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

Benutzerdefinierten Gebotsalgorithmus erstellen

Ein CustomBiddingAlgorithm-Objekt steht für eine Einzelperson Algorithmus, den Sie einer Werbebuchung zur Verwendung in ihrer Gebotsstrategie zuweisen können. Dieses enthält Details zum Algorithmus, z. B. customBiddingAlgorithmType und entityStatus sowie die readinessState und suspensionState für das Modell jedes relevanten Werbetreibenden zu testen. Sie können CustomBiddingScript und CustomBiddingAlgorithmRules-Objekte als untergeordnete Ressourcen für die den jeweiligen Algorithmus.

Hier sehen Sie ein Beispiel, wie Sie einen skriptbasierten Algorithmus für die benutzerdefinierte Gebotseinstellung erstellen:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithm customBiddingAlgorithm =
    new CustomBiddingAlgorithm()
        .setAdvertiserId(advertiser-id)
        .setDisplayName(display-name)
        .setEntityStatus("ENTITY_STATUS_ACTIVE")
        .setCustomBiddingAlgorithmType("SCRIPT_BASED");

// Configure the create request.
CustomBiddingAlgorithms.Create request =
    service.customBiddingAlgorithms().create(customBiddingAlgorithm);

// Create the custom bidding algorithm.
CustomBiddingAlgorithm response = request.execute();

// Display the new custom bidding algorithm name.
System.out.printf(
    "Custom bidding algorithm %s was created.%n",
    response.getName()
);

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=custom_bidding_algorithm_obj
).execute()

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

PHP

// Create a custom bidding algorithm object.
$customBiddingAlgorithm =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithm();
$customBiddingAlgorithm->setAdvertiserId(advertiser-id);
$customBiddingAlgorithm->setDisplayName(display-name);
$customBiddingAlgorithm->setEntityStatus('ENTITY_STATUS_ACTIVE');
$customBiddingAlgorithm->setCustomBiddingAlgorithmType('SCRIPT_BASED');

// Create the custom bidding algorithm.
$result =
    $this->service->customBiddingAlgorithms->create($customBiddingAlgorithm);

// Display the new custom bidding algorithm name.
printf('Custom Bidding Algorithm %s was created.\n', $result['name']);

Zugriff auf den Algorithmus verwalten

Die Algorithmen für die benutzerdefinierte Gebotseinstellung können einem Partner oder Werbetreibenden gehören. Algorithmen die einem Partner gehören und von diesem und jedem untergeordneten Partner aufgerufen und geändert werden können Werbetreibende, die im Feld sharedAdvertiserIds aufgeführt sind. Algorithmen eines Werbetreibenden können über dieses Konto aufgerufen und geändert werden. Werbetreibenden und seinem übergeordneten Partner zugeordnet, kann jedoch nicht für andere Werbetreibende freigegeben werden.

Wenn Sie den Algorithmus nur für einen einzelnen Werbetreibenden verwenden, Werbetreibenden als Inhaber mit dem Feld advertiserId hinzufügen. Andernfalls weisen Sie den übergeordneten Partner des Werbetreibenden als Inhaber mit der partnerId ein und gewähren Sie den Werbetreibenden Zugriff über das sharedAdvertiserIds.

Logik des Upload-Algorithmus

Je nach Art des Algorithmus für die benutzerdefinierte Gebotseinstellung müssen Sie als Nächstes ein script- oder rules-Objekt, in dem Sie und geben die Logik für den Algorithmus an.

Script hochladen

Bei skriptbasierten Algorithmen für die benutzerdefinierte Gebotseinstellung werden von Nutzern bereitgestellte Skripts verwenden, um den Wert einer Impression zu bewerten. Beispiele für einfache Skripts und eine Liste der erweiterte Felder sind in der Display- und Video 360-Hilfe.

In den folgenden Abschnitten erfahren Sie, wie Sie einem benutzerdefinierten Gebotsalgorithmus.

Speicherort einer Skriptressource abrufen

Zuerst rufen Sie unter der benutzerdefinierten Gebotseinstellung einen verfügbaren Ressourcenstandort ab. Algorithmusressource mit dem customBiddingAlgorithms.uploadScript-Methode. Dieses -Anfrage ein CustomBiddingScriptRef-Objekt mit einem Ressourcenname. Sie können Laden Sie Ihre Skriptdatei an den Speicherort hoch, der vom Ressourcenname. Verwenden Sie dann das Referenzobjekt des Skripts für die benutzerdefinierte Gebotseinstellung, Erstellen Sie Ihre Skriptressource.

Hier ein Beispiel für das Abrufen eines verfügbaren Ressourcenstandorts:

Java

// Retrieve a usable custom bidding script
// reference.
CustomBiddingScriptRef scriptRef =
    service
        .customBiddingAlgorithms()
        .uploadScript(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the custom bidding script reference resource path.
System.out.printf(
    "The script can be uploaded to the following resource path: %s%n",
    scriptRef.getResourceName()
);

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}')

PHP

// Set parent advertiser ID of custom bidding
// algorithm in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding script reference.
$scriptRefResponse = $this->service->customBiddingAlgorithms->uploadScript(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding script reference object.
printf(
    'The script can be uploaded to the following resource path: %s\n',
    $scriptRefResponse->getResourceName()
);

Skriptdatei hochladen

Laden Sie nach dem Abrufen eines verfügbaren Ressourcenspeicherorts Ihre Skriptdatei dorthin hoch. im Display- und Video 360-System mit dem media.upload-Methode. Diese Methode unterstützt ein einfacher Upload, für den der Suchparameter erforderlich ist uploadType=media

Hier ein Beispiel für das Hochladen einer Skriptdatei anhand einer abgerufenen benutzerdefinierten Referenzobjekt für das Gebotsskript:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the script file.
InputStreamContent scriptFileStream =
    new InputStreamContent(
        null, new FileInputStream(script-path));

// Create media.upload request.
Media.Upload uploadRequest =
        service
            .media()
            .upload(
                resource-name,
                media,
                scriptFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

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()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(script-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload script file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @script-path

Skriptobjekt erstellen

Sobald die Skriptdatei hochgeladen ist, erstellen Sie eine Skriptressource für die benutzerdefinierte Gebotseinstellung mit Methode customBiddingAlgorithms.scripts.create Die Das in der Anfrage übergebene Objekt CustomBiddingScript sollte nur das Objekt CustomBiddingScriptRef als zugewiesenes Objekt Wert des Felds script. Dadurch werden die hochgeladenen Script-Datei mit der neuen Script-Ressource.

Hier ein Beispiel für das Erstellen einer Skriptressource:

Java

// Create the custom bidding script structure.
CustomBiddingScript customBiddingScript =
    new CustomBiddingScript()
        .setScript(custom-bidding-script-ref);

// Create the custom bidding script.
CustomBiddingScript response =
    service
        .customBiddingAlgorithms()
        .scripts()
        .create(custom-bidding-algorithm-id, customBiddingScript)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new script resource name
System.out.printf(
    "The following script was created: %s%n",
    response.getName());

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}')

PHP

// Create the custom bidding script object.
$customBiddingScript =
    new Google_Service_DisplayVideo_CustomBiddingScript();
$customBiddingScript->setScript(custom-bidding-script-ref);

// Set parameters for create script request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding script.
$result = $this->service->customBiddingAlgorithms_scripts->create(
    custom-bidding-algorithm-id,
    $customBiddingScript,
    $optParams
);

// Display the new script resource name.
printf('The following script was created: %s.\n', $result->getName());

Sobald Sie eine Skriptressource für die benutzerdefinierte Gebotseinstellung erstellt haben, Video 360 verarbeitet die um sicherzustellen, dass mit diesem Skript Impressionen erfolgreich bewertet werden können. Rufen Sie den Verarbeitungsstatus über die Methode state-Feld. Sobald das neue Skript akzeptiert wurde, wird für den Gebotsalgorithmus das Skript verwendet, um Impressionswerte zu bewerten. Dieses der Algorithmus sofort aktualisiert wird. Erstellen einer neuen Skriptressource.

Upload-Regeln

Bei regelbasierten Algorithmen für die benutzerdefinierte Gebotseinstellung wird die Logik eines AlgorithmRules-Objekt, um den Wert einer Impression zu bewerten.

AlgorithmRules-Objekte werden in einer JSON-Datei hochgeladen. die mit einem Algorithmus für die benutzerdefinierte Gebotseinstellung CustomBiddingAlgorithmRules-Objekt.

Speicherort einer Regelressource abrufen

Zuerst rufen Sie unter der benutzerdefinierten Gebotseinstellung einen verfügbaren Ressourcenstandort ab. Algorithmusressource mit dem customBiddingAlgorithms.uploadRules-Methode. Dieses Die Anfrage gibt ein CustomBiddingAlgorithmsRulesRef-Objekt zurück. durch einen Ressourcennamen. Sie können Ihre Regeln hochladen Datei an den Speicherort, der durch den Ressourcennamen vorgegeben ist. Dann Referenzobjekt für Algorithmusregeln für die benutzerdefinierte Gebotseinstellung verwenden, um Regeln zu erstellen Ressource.

Hier ein Beispiel für das Abrufen eines verfügbaren Ressourcenstandorts:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithmRulesRef rulesRef =
    service
        .customBiddingAlgorithms()
        .uploadRules(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

System.out.printf(
    "The rules can be uploaded to the following resource path: %s%n",
    rulesRef.getResourceName()
);

Python

# Retrieve a usable custom bidding algorithm rules reference
# object.
custom_bidding_algorithm_rules_ref = service.customBiddingAlgorithms().uploadRules(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

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

PHP

// Set parent advertiser ID of custom bidding algorithm
// in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding algorithm rules reference.
$rulesRefResponse = $this->service->customBiddingAlgorithms->uploadRules(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding algorithm rules reference object resource path.
printf(
    'The rules can be uploaded to the following resource path: %s\n',
    $rulesRefResponse->getResourceName()
);

AlgorithmRules-Datei hochladen

Laden Sie nach dem Abrufen eines verfügbaren Ressourcenstandorts Ihre Regeldatei dorthin hoch. im Display- und Video 360-System mit dem media.upload-Methode. Diese Methode unterstützt ein einfacher Upload, für den der Suchparameter erforderlich ist uploadType=media

Hier ein Beispiel für das Hochladen einer AlgorithmRules-Datei anhand eines abgerufenen Referenzobjekt für Algorithmusregeln für die benutzerdefinierte Gebotseinstellung:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the rules file.
InputStreamContent rulesFileStream =
    new InputStreamContent(
        null, new FileInputStream(rules-file-path));

// Create media.upload request.
 Media.Upload uploadRequest =
    service
        .media()
        .upload(
            resource-name,
            media,
            rulesFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(rules-file-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 rules file to resource location given in retrieved custom bidding
# algorithm rules reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(rules-file-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload rules file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @rules-file-path

Regelobjekt erstellen

Sobald die JSON-Datei AlgorithmRules hochgeladen ist, können Sie eine benutzerdefinierte Gebotseinstellung erstellen Ressource für Algorithmusregeln mit dem customBiddingAlgorithms.rules.create-Methode. Die Das in der Anfrage übergebene Objekt CustomBiddingAlgorithmRules sollte das Objekt CustomBiddingAlgorithmRulesRef nur als dem zugewiesenen Wert des Felds rules Dadurch wird das Ereignis hat AlgorithmRules JSON-Datei mit der neuen Regelressource hochgeladen.

Hier ein Beispiel für das Erstellen einer Regelressource:

Java

// Create the custom bidding algorithm rules structure.
CustomBiddingAlgorithmRules customBiddingAlgorithmRules =
    new CustomBiddingAlgorithmRules()
        .setRules(custom-bidding-algorithm-rules-ref);

// Create the rules resource.
CustomBiddingAlgorithmRules response =
    service
        .customBiddingAlgorithms()
        .rules()
        .create(custom-bidding-algorithm-id, customBiddingAlgorithmRules)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new rules resource name.
System.out.printf(
    "The following custom bidding algorithm rules object was created: %s%n",
    response.getName());

Python

# Create the custom bidding algorithm rules object.
rules_obj = {
    'rules': custom-bidding-algorithm-rules-ref
}

# Create the rules resource.
response = service.customBiddingAlgorithms().rules().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=rules_obj).execute()

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

PHP

// Create the custom bidding algorithm rules object.
$customBiddingAlgorithmRules =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithmRules();
$customBiddingAlgorithmRules->setRules(custom-bidding-algorithm-rules-ref);

// Set parameters for create rules request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding algorithm rules resource.
$result = $this->service->customBiddingAlgorithms_rules->create(
    custom-bidding-algorithm-id,
    $customBiddingAlgorithmRules,
    $optParams
);

// Display the new custom bidding algorithm rules resource name.
printf('The following rules resource was created: %s.\n', $result->getName());

Nachdem Sie eine Regelressource erstellt haben, Video 360 verarbeitet den Regelsatz, um damit Impressionen erfolgreich bewertet werden können. Status abrufen dieser Verarbeitung über das Feld state des Regelobjekts. Sobald die neuen Regeln akzeptiert wurden, wird für den Algorithmus für die benutzerdefinierte Gebotseinstellung um Impressionswerte sofort zu bewerten.

Wenn die Regeln abgelehnt werden, rufen Sie den Grund für die Ablehnung in den Regeln ab error des Objekts. Im Falle einer Ablehnung aktualisieren Sie AlgorithmRules-Objekt, um den Fehler zu beheben und den Uploadvorgang zu wiederholen vom Abrufen des Regelreferenzobjekts.

Benutzerdefinierten Gebotsalgorithmus zuweisen

Nachdem Sie einen Algorithmus für die benutzerdefinierte Gebotseinstellung erstellt haben, laden Sie die akzeptierte Logik hoch und Anforderungen erfüllt sind, können Sie Ihren benutzerdefinierten Gebotsalgorithmus der Gebotsstrategie einer Werbebuchung oder eines Anzeigenauftrags hinzu.

Sie können Algorithmen für die benutzerdefinierte Gebotseinstellung Ausgaben optimieren und Gebotsstrategien für Leistungsziel durch Zuweisen von BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO und die ID des Algorithmus für die benutzerdefinierte Gebotseinstellung zur performanceGoalType und customBiddingAlgorithmId-Felder. Je nach Gebotsstrategie sind weitere Gebotsparameter verfügbar oder erforderlich.

Hier ein Beispiel dafür, wie Sie eine Werbebuchung aktualisieren, um ein Gebot zum Maximieren der Ausgaben zu verwenden mit einem bestimmten Algorithmus für die benutzerdefinierte Gebotseinstellung:

Java

// Create the line item structure.
LineItem lineItem = new LineItem();

// Create and set the bidding strategy structure.
BiddingStrategy biddingStrategy = new BiddingStrategy();
MaximizeSpendBidStrategy maxSpendBidStrategy =
    new MaximizeSpendBidStrategy()
        .setPerformanceGoalType(
            "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO")
        .setCustomBiddingAlgorithmId(custom-bidding-algorithm-id);
biddingStrategy.setMaximizeSpendAutoBid(maxSpendBidStrategy);
lineItem.setBidStrategy(biddingStrategy);

// Configure the patch request and set update mask to only update
// the bid strategy.
LineItems.Patch request =
    service
        .advertisers()
        .lineItems()
        .patch(advertiser-id, line-item-id, lineItem)
        .setUpdateMask("bidStrategy");

// Update the line item.
LineItem response = request.execute();

// Display the custom bidding algorithm ID used in the new
// bid strategy.
System.out.printf(
    "LineItem %s now has a bid strategy utilizing custom "
        + "bidding algorithm %s%n",
    response.getName(),
    response
        .getBidStrategy()
        .getMaximizeSpendAutoBid()
        .getCustomBiddingAlgorithmId());

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"]}.')

PHP

// Create the line item structure.
$lineItem = new Google_Service_DisplayVideo_LineItem();

// Create and set the bidding strategy structure.
$biddingStrategy =  new Google_Service_DisplayVideo_BiddingStrategy();
$maximizeSpendBidStrategy =
    new Google_Service_DisplayVideo_MaximizeSpendBidStrategy();
$maximizeSpendBidStrategy->setPerformanceGoalType(
    'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO'
);
$maximizeSpendBidStrategy->setCustomBiddingAlgorithmId(
    custom-bidding-algorithm-id
);
$biddingStrategy->setMaximizeSpendAutoBid($maximizeSpendBidStrategy);
$lineItem->setBidStrategy($biddingStrategy);

// Set update mask.
$optParams = array('updateMask' => 'bidStrategy');

// Update the line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

// Display the custom bidding algorithm ID used in the new bid strategy.
printf(
    'Line Item %s now has a bid strategy utilizing custom bidding algorithm %s.\n',
    $result['name'],
    $result['bidStrategy']['maximizeSpendBidStrategy']['customBiddingAlgorithmId']
);