Implémentez les enchères personnalisées

L'API Display & Video 360 vous permet de gérer entièrement la mise en œuvre des enchères personnalisées. Vous pouvez créer des algorithmes d'enchères personnalisées, importer et vérifier des scripts, et attribuer un algorithme spécifique à une ressource en tant que stratégie d'enchères.

Cette page explique comment créer, mettre à jour et attribuer des algorithmes d'enchères personnalisées avec l'API Display & Video 360. Chaque section fournit un exemple de code.

Créer un algorithme d'enchères personnalisées

Un objet CustomBiddingAlgorithm représente un algorithme que vous pouvez attribuer à un élément de campagne afin de l'utiliser dans sa stratégie d'enchères. Cet objet contient des informations sur l'algorithme, telles que customBiddingAlgorithmType et entityStatus, ainsi que les readinessState et suspensionState pour le modèle généré par l'annonceur concerné. Vous pouvez créer des objets CustomBiddingScript et CustomBiddingAlgorithmRules en tant que ressources enfants pour l'algorithme.

Voici un exemple de création d'un algorithme d'enchères personnalisées basé sur un script:

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']);

Gérer l'accès à l'algorithme

Les algorithmes d'enchères personnalisées peuvent appartenir à un partenaire ou à un annonceur. Les algorithmes détenus par un partenaire peuvent être consultés et modifiés par ce partenaire et par tous les annonceurs enfants répertoriés dans le champ sharedAdvertiserIds. Les algorithmes appartenant à un annonceur sont accessibles et modifiés par cet annonceur et son partenaire parent, mais ne peuvent pas être partagés avec d'autres annonceurs.

Si vous n'utilisez l'algorithme que pour un seul annonceur, définissez l'annonceur en tant que propriétaire à l'aide du champ advertiserId. Sinon, désignez le partenaire parent des annonceurs en tant que propriétaire avec le champ partnerId et accordez l'accès aux annonceurs avec le champ sharedAdvertiserIds.

Importer la logique de l'algorithme

Selon le type de votre algorithme d'enchères personnalisées, vous devez ensuite créer un objet script ou rules, dans lequel vous pouvez fournir la logique à utiliser par l'algorithme.

Importer un script

Les algorithmes d'enchères personnalisées basés sur des scripts utilisent des scripts fournis par l'utilisateur pour évaluer la valeur d'une impression. Des exemples de scripts simples et une liste de champs avancés sont disponibles dans le Centre d'aide Display & Video 360.

Les sections suivantes expliquent comment ajouter un script nouveau ou mis à jour à un algorithme d'enchères personnalisées.

Récupérer l'emplacement d'une ressource de script

Commencez par récupérer un emplacement de ressource disponible sous la ressource d'algorithme d'enchères personnalisées à l'aide de la méthode customBiddingAlgorithms.uploadScript. Cette requête renvoie un objet CustomBiddingScriptRef avec un nom de ressource. Vous pouvez importer votre fichier de script à l'emplacement indiqué par le nom de la ressource. Utilisez ensuite l'objet de référence du script d'enchères personnalisées pour créer une ressource de script.

Voici un exemple de récupération d'un emplacement de ressource disponible:

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

Importer un fichier de script

Après avoir récupéré un emplacement de ressource disponible, importez votre fichier de script vers cet emplacement dans le système Display & Video 360 à l'aide de la méthode media.upload. Cette méthode permet d'effectuer une importation simple nécessitant le paramètre de requête uploadType=media.

Voici un exemple d'importation d'un fichier de script à partir d'un objet de référence de script d'enchères personnalisées récupéré:

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

Créer un objet de script

Une fois le fichier de script importé, créez une ressource de script d'enchères personnalisées avec la méthode customBiddingAlgorithms.scripts.create. L'objet CustomBiddingScript transmis dans la requête ne doit inclure que l'objet CustomBiddingScriptRef en tant que valeur attribuée du champ script. Le fichier de script importé est alors associé à la nouvelle ressource de script.

Voici un exemple de création d'une ressource de script:

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

Une fois que vous avez créé une ressource de script d'enchères personnalisées, Display & Video 360 traite le script pour s'assurer qu'il peut être utilisé pour évaluer les impressions. Récupérez l'état du traitement via le champ state de l'objet de script. Une fois le nouveau script accepté, l'algorithme d'enchères personnalisées commence à l'utiliser pour évaluer les valeurs d'impression. Cette opération s'effectue immédiatement. Veillez donc à mettre à jour l'algorithme avant de créer une ressource de script.

Règles d'importation

Les algorithmes d'enchères personnalisées basés sur des règles s'appuient sur la logique fournie dans un objet AlgorithmRules pour évaluer la valeur d'une impression.

Les objets AlgorithmRules sont importés dans un fichier JSON, puis associés à un algorithme d'enchères personnalisées via un objet CustomBiddingAlgorithmRules.

Récupérer un emplacement de ressource de règles

Commencez par récupérer un emplacement de ressource disponible sous la ressource d'algorithme d'enchères personnalisées à l'aide de la méthode customBiddingAlgorithms.uploadRules. Cette requête renvoie un objet CustomBiddingAlgorithmsRulesRef avec un nom de ressource. Vous pouvez importer votre fichier de règles à l'emplacement indiqué par le nom de la ressource. Utilisez ensuite l'objet de référence des règles de l'algorithme d'enchères personnalisées pour créer votre ressource de règles.

Voici un exemple de récupération d'un emplacement de ressource disponible:

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

Importer un fichier AlgorithmRules

Après avoir récupéré un emplacement de ressource disponible, importez votre fichier de règles à cet emplacement dans le système Display & Video 360 à l'aide de la méthode media.upload. Cette méthode permet d'effectuer une importation simple nécessitant le paramètre de requête uploadType=media.

Voici un exemple d'importation d'un fichier AlgorithmRules à partir d'un objet de référence de règles de l'algorithme d'enchères personnalisées récupéré:

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

Créer un objet de règles

Une fois le fichier JSON AlgorithmRules importé, créez une ressource de règles d'algorithme d'enchères personnalisées à l'aide de la méthode customBiddingAlgorithms.rules.create. L'objet CustomBiddingAlgorithmRules transmis dans la requête ne doit inclure que l'objet CustomBiddingAlgorithmRulesRef comme valeur attribuée du champ rules. Le fichier JSON AlgorithmRules importé est ainsi associé à la nouvelle ressource de règles.

Voici un exemple de création d'une ressource de règles:

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

Une fois que vous avez créé une ressource de règles, Display & Video 360 traite l'ensemble de règles afin de s'assurer qu'il peut être utilisé pour évaluer les impressions. Récupérez l'état du traitement via le champ state de l'objet de règles. Une fois les nouvelles règles acceptées, l'algorithme d'enchères personnalisées commence à les utiliser pour évaluer immédiatement les valeurs d'impression.

Si les règles sont refusées, récupérez le motif du refus dans le error de l'objet de règles. En cas de refus, mettez à jour votre objet AlgorithmRules pour corriger l'erreur, puis répétez le processus d'importation en commençant par récupérer l'objet de référence des règles.

Attribuer un algorithme d'enchères personnalisées

Une fois que vous avez créé un algorithme d'enchères personnalisées, importé une logique acceptée et rempli les conditions requises, vous pouvez attribuer votre algorithme d'enchères personnalisées à la stratégie d'enchères d'un élément de campagne ou d'un ordre d'insertion.

Vous pouvez utiliser des algorithmes d'enchères personnalisées dans les stratégies d'enchères Maximiser les dépenses et Objectif de performances. Pour ce faire, attribuez respectivement BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO et l'ID de l'algorithme d'enchères personnalisées aux champs performanceGoalType et customBiddingAlgorithmId. Selon la stratégie d'enchères, d'autres paramètres d'enchères peuvent être disponibles ou requis.

Voici un exemple de mise à jour d'un élément de campagne pour utiliser une stratégie d'enchères "Maximiser les dépenses" avec un algorithme d'enchères personnalisées donné:

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']
);
Précédent
Récupérer des éléments de campagne YouTube et partenaires
Suivant
Activer un élément de campagne