Com a API Display & Video 360, é possível gerenciar totalmente as implementações de lances personalizados. É possível criar algoritmos de lances personalizados, fazer upload e verificar scripts individuais e atribuir um algoritmo específico a um recurso como estratégia de lances.
Esta página descreve como criar, atualizar e atribuir algoritmos de lances personalizados com a API Display & Video 360. Cada seção fornece um exemplo de código.
Criar um algoritmo de lances personalizados
Um objeto CustomBiddingAlgorithm
representa um algoritmo individual que pode ser atribuído a um item de linha para uso na estratégia de lances dele. Esse
objeto tem detalhes sobre o algoritmo, como o
customBiddingAlgorithmType
e o
entityStatus
, bem como o
readinessState
e o suspensionState
do
modelo gerado pelo anunciante relevante. É possível criar
objetos
CustomBiddingScript
e
CustomBiddingAlgorithmRules
como recursos filhos para o
algoritmo usar.
Confira um exemplo de como criar um algoritmo de lances personalizados com base em 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']);
Gerenciar o acesso ao algoritmo
Os algoritmos de lances personalizados podem ser de propriedade de um parceiro ou anunciante. Algoritmos
que pertencem a um parceiro podem ser acessados e modificados por ele e por qualquer anunciante
filho listado no campo sharedAdvertiserIds
.
Algoritmos de um anunciante podem ser acessados e modificados por ele e pelo parceiro pai, mas não podem ser compartilhados com outros anunciantes.
Se você estiver usando o algoritmo para apenas um anunciante, atribua o
anunciante como proprietário com o campo advertiserId
.
Caso contrário, atribua o parceiro pai dos anunciantes como o proprietário com o campo
partnerId
e conceda acesso aos anunciantes com o campo
sharedAdvertiserIds
.
Fazer upload da lógica do algoritmo
Dependendo do tipo do seu algoritmo de lances personalizados, você precisa criar um script ou um objeto rules em que possa fornecer a lógica a ser usada pelo algoritmo.
Fazer upload de um script
Os algoritmos de lances personalizados com base em scripts usam scripts fornecidos pelo usuário para avaliar o valor de uma impressão. Exemplos de scripts simples e uma lista de campos avançados estão disponíveis na Central de Ajuda do Display & Video 360.
As seções a seguir ensinam como adicionar um script novo ou atualizado a um algoritmo de lances personalizados.
Recuperar o local de um recurso de script
Primeiro, recupere um local de recurso disponível no recurso de algoritmo de lances personalizados com o método customBiddingAlgorithms.uploadScript
. Essa
solicitação retorna um objeto CustomBiddingScriptRef
com um
nome de recurso. É possível fazer upload do arquivo de script para o local determinado pelo nome do recurso. Em seguida, use o objeto de referência do script de lances personalizados para criar seu recurso de script.
Confira um exemplo de como recuperar um local de recurso disponível:
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()
);
Fazer upload de um arquivo de script
Depois de recuperar um local de recurso disponível, faça upload do seu arquivo de script para esse
local no sistema do Display & Video 360 com o
método media.upload
. Esse método é compatível com um
upload simples que requer o parâmetro de consulta
uploadType=media
.
Veja um exemplo de como fazer o upload de um arquivo de script considerando um objeto de referência de script de lances personalizados recuperado:
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
Criar um objeto de script
Depois do upload do arquivo de script, crie um recurso de script de lances personalizados com o método customBiddingAlgorithms.scripts.create
. O objeto
CustomBiddingScript
transmitido na solicitação só precisa
incluir o objeto CustomBiddingScriptRef
como o valor atribuído
do campo script
. Isso associa o arquivo de script enviado ao novo recurso de script.
Veja um exemplo de como criar um recurso 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());
Depois de criar um recurso de script de lances personalizados, o Display & Video 360 processa o script para garantir que ele possa ser usado para pontuar impressões.
Recupere o estado desse processamento por meio do campo state
do objeto de script. Depois que o novo script é aceito, o algoritmo de lances personalizados começa a usá-lo para pontuar valores de impressão. Isso acontece imediatamente, portanto, não se esqueça de atualizar o algoritmo antes de criar um novo recurso de script.
Regras de upload
Os algoritmos de lances personalizados com base em regras usam a lógica fornecida em um objeto
AlgorithmRules
para avaliar o valor de uma impressão.
Objetos AlgorithmRules
são enviados em um arquivo JSON e
associados a um algoritmo de lances personalizados por um objeto
CustomBiddingAlgorithmRules
.
Recuperar o local de um recurso de regras
Primeiro, recupere um local de recurso disponível no recurso de algoritmo de lances personalizados com o método customBiddingAlgorithms.uploadRules
. Essa
solicitação retorna um objeto CustomBiddingAlgorithmsRulesRef
com um nome de recurso. É possível fazer upload do arquivo de regras para o local determinado pelo nome do recurso. Em seguida, use o objeto de referência de regras do algoritmo de lances personalizados para criar seu recurso de regras.
Confira um exemplo de como recuperar um local de recurso disponível:
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()
);
Fazer upload de um arquivo AlgorithmRules
Depois de recuperar um local de recurso disponível, faça upload do seu arquivo de regras para esse
local no sistema do Display & Video 360 com o
método media.upload
. Esse método é compatível com um
upload simples que requer o parâmetro de consulta
uploadType=media
.
Confira um exemplo de como fazer upload de um arquivo AlgorithmRules
considerando um objeto de referência recuperado de regras de algoritmo de lances personalizados:
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
Criar um objeto de regras
Depois do upload do arquivo JSON AlgorithmRules
, crie um recurso de regras de algoritmo de lances personalizados com o método customBiddingAlgorithms.rules.create
. O objeto
CustomBiddingAlgorithmRules
transmitido na solicitação precisa
incluir apenas o objeto CustomBiddingAlgorithmRulesRef
como
o valor atribuído do campo rules
. Isso associa o arquivo JSON AlgorithmRules
enviado ao novo recurso de regras.
Veja um exemplo de como criar um recurso de regras:
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());
Depois de criar um recurso de regras, o Display & Video 360 processa o conjunto de regras para garantir que ele possa ser usado para pontuar impressões. Recupere o estado
desse processamento por meio do campo state
do objeto de regras.
Depois que as novas regras são aceitas, o algoritmo de lances personalizados começa a usá-las para pontuar os valores de impressão imediatamente.
Se as regras forem rejeitadas, recupere o motivo da rejeição no error
do objeto de regras. Em caso de rejeição, atualize o
objeto AlgorithmRules
para corrigir o erro e repita o processo de upload a partir da
recuperação do objeto de referência de regras.
Atribuir um algoritmo de lances personalizados
Depois de criar um algoritmo de lances personalizados, fazer upload da lógica aceita e atender aos requisitos necessários, é possível atribuir seu algoritmo de lances personalizados à estratégia de lances de um item de linha ou pedido de inserção.
É possível usar algoritmos de lances personalizados nas estratégias de lances Maximizar gastos e meta de performance atribuindo BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO
e o ID do algoritmo de lances personalizados aos campos performanceGoalType
e customBiddingAlgorithmId
, respectivamente.
Dependendo da estratégia de lances, outros parâmetros de lance podem estar disponíveis ou necessários.
Confira um exemplo de como atualizar um item de linha para usar uma estratégia de lances "Maximizar gastos" com um determinado algoritmo de lances personalizados:
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']
);