Implémentez les enchères personnalisées

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

Bêta :Les algorithmes d'enchères personnalisées basés sur des règles ne sont disponibles que pour un nombre limité des utilisateurs.

Cette page explique comment créer, modifier et attribuer des algorithmes d'enchères personnalisées avec les campagnes display et l'API Video 360. Chaque section fournit un exemple de code.

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

Un objet CustomBiddingAlgorithm représente un individu que vous pouvez attribuer à un élément de campagne pour l'utiliser dans sa stratégie d'enchères. Ce comporte des détails sur l'algorithme, comme customBiddingAlgorithmType et entityStatus, ainsi que readinessState et suspensionState pour par le modèle généré par chaque annonceur pertinent. Vous pouvez créer CustomBiddingScript et des objets CustomBiddingAlgorithmRules en tant que ressources enfants pour la à utiliser.

Remarque :Ce guide se concentre sur les algorithmes d'enchères personnalisées basés sur des scripts et des règles. Les algorithmes créés dans Ads Data Hub ou via Display & Objectif de l'interface utilisateur Video 360 L'outil de création peut être récupéré et attribué, mais n'est pas entièrement géré.

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. Algorithmes appartenant à un partenaire peuvent être consultés et modifiés par ce partenaire et tout enfant annonceurs répertoriés dans le champ sharedAdvertiserIds. Il peut accéder aux algorithmes d'un annonceur et les modifier et son partenaire parent, mais il ne peut pas être partagé avec d'autres annonceurs.

Remarque :Lorsque vous créez un algorithme d'enchères personnalisées, vous devez disposer d'un accès en lecture/écriture. au partenaire ou à l'annonceur que vous désignez comme propriétaire.

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

Logique de l'algorithme d'importation

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

Importer un script

Les algorithmes d'enchères personnalisées basés sur des scripts utilisent scripts pour évaluer la valeur d'une impression. Des exemples de scripts simples et une liste de les champs avancés sont disponibles dans la Écran et Centre d'aide Video 360

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

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

Commencez par récupérer un emplacement de ressource disponible sous le ressource d'algorithme avec customBiddingAlgorithms.uploadScript. Ce la requête renvoie un objet CustomBiddingScriptRef avec une nom de la ressource. Vous pouvez importez votre fichier de script à l'emplacement indiqué par la nom de la ressource. Utilisez ensuite l'objet de référence du script d'enchères personnalisées pour créez votre 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 à cet emplacement emplacement dans le Display & un système Video 360 avec media.upload. Cette méthode accepte importation simple nécessitant le paramètre de requête uploadType=media

Avertissement :La taille de fichier maximale des scripts d'enchères personnalisées est de 7 Mo.

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

Conseil :Si vous n'utilisez pas l'un des trois langages de programmation inclus dans ce guide, créez votre requête media.upload à l'aide de la requête cURL fournie exemple de commande.

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. La L'objet CustomBiddingScript transmis dans la requête ne doit inclure l'objet CustomBiddingScriptRef en tant que du champ script. Cela permet d'associer les avec la nouvelle ressource de script.

Avertissement :Si le fichier de script que vous avez importé contient une erreur de syntaxe, votre La requête customBiddingAlgorithms.scripts.create échouera et renvoyer des détails sur l'erreur de syntaxe détectée. Pour importer un fichier de script corrigé, vous devez vous devez relancer ce processus récupérer un nouvel emplacement pour les ressources 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, Video 360 traite le pour s'assurer qu'il peut être utilisé pour évaluer les impressions. Récupérez l'état de ce traitement via la classe state. Une fois le nouveau script accepté, le script L'algorithme d'enchères commence à utiliser le script pour évaluer les valeurs d'impression. Ce se produit immédiatement, alors assurez-vous de vouloir mettre à jour l'algorithme avant en créant une ressource de script.

Règles d'importation

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

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

Récupérer l'emplacement d'une ressource de règles

Commencez par récupérer un emplacement de ressource disponible sous le ressource d'algorithme avec customBiddingAlgorithms.uploadRules. Ce La requête renvoie un objet CustomBiddingAlgorithmsRulesRef avec un nom de ressource. Vous pouvez importer vos règles fichier à l'emplacement dicté par le nom de la ressource. Ensuite, utilisez l'objet de référence des règles de l'algorithme d'enchères personnalisées pour créer vos règles ressource.

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 dans ce fichier. emplacement dans le Display & un système Video 360 avec media.upload. Cette méthode accepte importation simple nécessitant le paramètre de requête uploadType=media

Avertissement :La taille des fichiers JSON importés AlgorithmRules ne doit pas dépasser 7 Mo.

Voici un exemple d'importation d'un fichier AlgorithmRules à partir d'une requête Objet de référence des règles de l'algorithme d'enchères personnalisées:

Conseil :Si vous n'utilisez pas l'un des trois langages de programmation inclus dans ce guide, créez votre requête media.upload à l'aide de la commande cURL fournie exemple de commande.

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 enchère personnalisée. de règles d'algorithme avec le paramètre customBiddingAlgorithms.rules.create. La L'objet CustomBiddingAlgorithmRules transmis dans la requête doit n'incluez que l'objet CustomBiddingAlgorithmRulesRef en tant que la valeur attribuée au champ rules. Cela permet d'associer importé le fichier JSON AlgorithmRules avec 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, Video 360 traite l'ensemble de règles pour créer s'assurer qu'elle peut être utilisée pour évaluer les impressions. Récupérer l'état ce 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 à utiliser pour évaluer immédiatement les valeurs d'impression.

Si les règles sont refusées, récupérez le motif du refus. error de l'objet. En cas de refus, mettez à jour votre Objet AlgorithmRules pour corriger l'erreur et répéter le processus d'importation en commençant de la récupération de l'objet de référence aux règles.

Attribuer un algorithme d'enchères personnalisées

Après avoir créé un algorithme d'enchères personnalisées, importez la logique acceptée et respectez les conditions requises, vous pouvez attribuer vos rôles à 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 maximiser les dépenses et stratégies d'enchères avec objectif de performances en attribuant BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO et l'ID de l'algorithme d'enchères personnalisées au performanceGoalType et customBiddingAlgorithmId, respectivement. Selon la stratégie d'enchères, d'autres paramètres d'enchères peuvent être disponibles ou obligatoire.

Voici un exemple de mise à jour d'un élément de campagne pour utiliser une enchère de type "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']
);