Implementar lances personalizados

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.

Beta :os algoritmos de lances personalizados baseados em regras estão disponíveis apenas para um número limitado de usuários.

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.

Observação :o foco deste guia são os algoritmos de lances personalizados baseados em scripts e regras. Os algoritmos criados no Ads Data Hub ou na ferramenta Criador de meta da interface do Display & Video 360 podem ser recuperados e atribuídos, mas não totalmente gerenciados.

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.

Observação :ao criar um algoritmo de lances personalizados, é necessário ter acesso de leitura/gravação ao parceiro ou anunciante atribuído como proprietário.

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.

Aviso :os scripts de lances personalizados têm um tamanho máximo de arquivo de 7 MB.

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:

Dica :se você não estiver usando uma das três linguagens de programação incluídas neste guia, crie sua solicitação media.upload usando o exemplo de comando cURL fornecido.

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.

Aviso :se o arquivo de script enviado tiver um erro de sintaxe, a solicitação customBiddingAlgorithms.scripts.create vai falhar e retornar detalhes sobre o erro de sintaxe encontrado. Para fazer upload de um arquivo de script fixo, reinicie esse processo recuperando um novo local do 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.

Aviso: os arquivos JSON enviados AlgorithmRules têm um tamanho máximo de 7 MB.

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:

Dica :se você não estiver usando uma das três linguagens de programação incluídas neste guia, crie sua solicitação media.upload usando o exemplo de comando cURL fornecido.

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