Implementar lances personalizados

Rede de Display e A API Video 360 permite gerenciar totalmente os lances personalizados e implementações. É possível criar algoritmos de lances personalizados, fazer upload e verificar scripts individuais e atribuir um algoritmo específico a um recurso como seu lance estratégia.

Beta :os algoritmos de lances personalizados com base 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 as campanhas de display API Video 360. Cada seção fornece um exemplo de código.

Criar um algoritmo de lances personalizados

Um objeto CustomBiddingAlgorithm representa um indivíduo algoritmo que você pode atribuir a um item de linha para usar na estratégia de lances. Isso tem detalhes sobre o algoritmo, como customBiddingAlgorithmType e entityStatus, assim como readinessState e suspensionState para o modelo gerado por cada anunciante relevante. É possível criar CustomBiddingScript e Objetos CustomBiddingAlgorithmRules como recursos filhos da algoritmo a ser usado.

Observação :este guia se concentra nos algoritmos de lances personalizados com base em scripts e regras. Algoritmos criados no Ads Data Hub ou pelas campanhas de display Meta da interface do Video 360 A ferramenta Builder pode ser recuperada e atribuída, mas não totalmente gerenciada.

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 do algoritmo

Os algoritmos de lances personalizados podem ser de propriedade de um parceiro ou anunciante. Algoritmos de propriedade de um parceiro pode ser acessado e modificado por esse parceiro e qualquer filho anunciantes listados no campo sharedAdvertiserIds. Algoritmos de propriedade de um anunciante podem ser acessados e modificados por ele anunciante e seu parceiro principal, mas não pode ser compartilhado com outros anunciantes.

Observação :ao criar um algoritmo de lances personalizados, você precisa ter acesso de leitura/gravação. ao parceiro ou anunciante que você atribuir como proprietário.

Se você usar o algoritmo apenas para um único anunciante, atribua o anunciante como o proprietário no campo advertiserId. Caso contrário, atribua o parceiro pai dos anunciantes como o proprietário com o partnerId e conceder acesso aos anunciantes com o sharedAdvertiserIds.

Fazer upload da lógica do algoritmo

Dependendo do tipo do seu algoritmo de lances personalizados, você precisará criar um script ou um objeto rules em que é possível fornecem a lógica a ser usada pelo algoritmo.

Fazer upload de um script

Os algoritmos de lances personalizados com base em script empregam dados scripts para avaliar o valor de uma impressão. Exemplos de scripts simples e uma lista de campos avançados estão disponíveis no Display e Central de Ajuda do Video 360.

As seções a seguir ensinam como adicionar um script novo ou atualizado a uma algoritmo de lances.

Recuperar um local do recurso de script

Primeiro, recupere um local de recurso disponível nos lances personalizados recurso de algoritmo com os método customBiddingAlgorithms.uploadScript. Isso solicitação retorna um objeto CustomBiddingScriptRef com um nome do recurso. Você pode faça o upload do seu arquivo de script no local determinado pelo nome do recurso. Em seguida, use o objeto de referência do script de lances personalizados para Crie o 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 o upload do arquivo de script nele local no menu Video 360 com o método media.upload. Esse método oferece suporte a uma upload simples que exige o parâmetro de consulta uploadType=media

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

Este é um exemplo de como fazer o upload de um arquivo de script com base em uma string objeto de referência do script de lances:

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

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. A O objeto CustomBiddingScript transmitido na solicitação só pode incluir o objeto CustomBiddingScriptRef como o do campo script. Isso associa o conteúdo enviado com o novo recurso de script.

Aviso: se o arquivo de script enviado tiver um erro de sintaxe, o A solicitação customBiddingAlgorithms.scripts.create vai falhar e retorna detalhes sobre o erro de sintaxe encontrado. Para fazer o upload de um arquivo de script fixo, precisa reiniciar esse processo até como recuperar um novo local de recurso de script.

Confira 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, as campanhas O Video 360 processa script para garantir que ele possa ser usado para pontuar as impressões. Recupere o estado deste processamento por meio do objeto de script state. Depois que o novo script for aceito, o algoritmo de lances começa a usar o script para pontuar os valores de impressão. Isso ocorre imediatamente. Portanto, certifique-se de que você quer atualizar o algoritmo antes criar um novo recurso de script.

Regras de upload

Os algoritmos de lances personalizados com base em regras empregam a lógica fornecida em uma AlgorithmRules para avaliar o valor de uma impressão.

Os objetos AlgorithmRules são enviados em um arquivo JSON e, em seguida, associadas a um algoritmo de lances personalizados objeto CustomBiddingAlgorithmRules.

Recuperar um local do recurso de regras

Primeiro, recupere um local de recurso disponível nos lances personalizados recurso de algoritmo com os método customBiddingAlgorithms.uploadRules. Isso A solicitação retorna um objeto CustomBiddingAlgorithmsRulesRef. por um nome de recurso. Você pode fazer o upload das suas regras file para o local determinado pelo nome do recurso. Depois, use o objeto de referência de regras do algoritmo de lances personalizados para criar suas regras. recurso.

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

Faça upload de um arquivo AlgorithmRules

Depois de recuperar um local de recurso disponível, faça o upload do seu arquivo de regras para ele local no menu Video 360 com o método media.upload. Esse método oferece suporte a uma upload simples que exige o parâmetro de consulta uploadType=media

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

Veja um exemplo de como fazer upload de um arquivo AlgorithmRules com base em um Objeto de referência das regras do algoritmo de lances personalizados:

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

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 que o arquivo JSON AlgorithmRules for enviado, crie um lance personalizado recurso de regras de algoritmo com a customBiddingAlgorithms.rules.create. A O objeto CustomBiddingAlgorithmRules transmitido na solicitação precisa inclua apenas o objeto CustomBiddingAlgorithmRulesRef como o valor atribuído do campo rules. Isso associa o fez o upload do arquivo JSON AlgorithmRules com o novo recurso de regras.

Confira 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, as categorias O Video 360 processa o conjunto de regras para criar que ele pode ser usado para pontuar as impressões. Extrair 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 usar o para pontuar os valores de impressão imediatamente.

Se as regras forem rejeitadas, recupere o motivo da rejeição nas regras error do objeto. Em caso de rejeição, atualize o Objeto AlgorithmRules para corrigir o erro e repetir o processo de upload. da recuperação do objeto de referência de regras.

Atribuir um algoritmo de lances personalizados

Depois de criar um algoritmo de lances personalizados, faça o upload da lógica aceita e atenda a os requisitos necessários, é possível atribuir algoritmo de lances à estratégia de um item de linha ou pedido de inserção.

É possível usar algoritmos de lances personalizados maximizar o gasto e estratégias de lances de meta de performance atribuindo BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO e o ID do algoritmo de lances personalizados ao performanceGoalType e customBiddingAlgorithmId, respectivamente. Dependendo da estratégia de lances, outros parâmetros de lance podem estar disponíveis ou obrigatórios.

Este é um exemplo de como atualizar um item de linha para usar um lance de maximizar gasto estratégia 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']
);