Implemente ofertas personalizadas

La API de Display & Video 360 te permite administrar completamente las implementaciones de ofertas personalizadas. Puedes crear algoritmos de ofertas personalizadas, subir y verificar secuencias de comandos individuales y asignar un algoritmo específico a un recurso como su estrategia de oferta.

Beta: Los algoritmos de ofertas personalizadas basadas en reglas solo están disponibles para una cantidad limitada de usuarios.

En esta página, se describe cómo crear, actualizar y asignar algoritmos de ofertas personalizadas con la API de Display & Video 360. Cada sección proporciona una muestra de código.

Crea un algoritmo de ofertas personalizadas

Un objeto CustomBiddingAlgorithm representa un algoritmo individual que puedes asignar a una línea de pedido para usar en su estrategia de ofertas. Este objeto tiene detalles sobre el algoritmo, como customBiddingAlgorithmType y entityStatus, así como readinessState y suspensionState para el modelo generado por cada anunciante relevante. Puedes crear objetos CustomBiddingScript y CustomBiddingAlgorithmRules como recursos secundarios para que los use el algoritmo.

Nota: Esta guía se centra en los algoritmos de ofertas personalizadas basadas en secuencias de comandos y en reglas. Los algoritmos creados en el Centro de Datos de Anuncios o a través de la herramienta Creador de objetivos de la IU de Display & Video 360 se pueden recuperar y asignar, pero no se pueden administrar por completo.

A continuación, presentamos un ejemplo de cómo crear un algoritmo de ofertas personalizadas basadas en secuencias de comandos:

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

Administra el acceso al algoritmo

Los algoritmos de ofertas personalizadas pueden ser propiedad de un socio o un anunciante. Tanto ese socio como cualquier anunciante secundario que aparezca en el campo sharedAdvertiserIds pueden acceder a los algoritmos que son propiedad de un socio y modificarlos. Tanto el anunciante como su socio superior pueden acceder a los algoritmos que son propiedad de un anunciante y modificarlos, pero no pueden compartirlos con otros anunciantes.

Nota: Cuando creas un algoritmo de ofertas personalizadas, debes tener acceso de lectura o escritura al socio o anunciante que asignas como propietario.

Si solo usas el algoritmo para un solo anunciante, asígnale como propietario el campo advertiserId. De lo contrario, asigna al socio superior de los anunciantes como propietario con el campo partnerId y otorga acceso a los anunciantes con el campo sharedAdvertiserIds.

Subir lógica del algoritmo

Según el tipo de tu algoritmo de ofertas personalizadas, debes crear un objeto script o rules en el que puedas proporcionar la lógica que usará el algoritmo.

Subir una secuencia de comandos

Los algoritmos de ofertas personalizadas basadas en secuencias de comandos emplean secuencias de comandos proporcionadas por el usuario para evaluar el valor de una impresión. Las muestras de secuencias de comandos simples y una lista de campos avanzados están disponibles en el Centro de ayuda de Display & Video 360.

En las siguientes secciones, se explica cómo agregar una secuencia de comandos nueva o actualizada a un algoritmo de ofertas personalizadas.

Recupera la ubicación de un recurso de secuencia de comandos

Primero, recupera una ubicación de recurso disponible en el recurso del algoritmo de ofertas personalizadas con el método customBiddingAlgorithms.uploadScript. Esta solicitud muestra un objeto CustomBiddingScriptRef con un nombre de recurso. Puedes subir tu archivo de secuencia de comandos a la ubicación que determine el nombre del recurso. Luego, utiliza el objeto de referencia de secuencia de comandos de ofertas personalizadas para crear tu recurso de secuencia de comandos.

Este es un ejemplo de cómo recuperar una ubicación de recurso 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()
);

Subir un archivo de secuencia de comandos

Después de recuperar una ubicación de recursos disponible, sube el archivo de secuencia de comandos a esa ubicación en el sistema de Display & Video 360 con el método media.upload. Este método admite una carga simple que requiere el parámetro de consulta uploadType=media.

Advertencia: Las secuencias de comandos de ofertas personalizadas tienen un tamaño de archivo máximo de 7 MB.

A continuación, se muestra un ejemplo de cómo subir un archivo de secuencia de comandos a partir de un objeto de referencia de secuencia de comandos de ofertas personalizadas recuperado:

Sugerencia: Si no usas uno de los tres lenguajes de programación que se incluyen en esta guía, crea tu solicitud media.upload con la muestra del comando cURL proporcionada.

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

Crea un objeto de secuencia de comandos

Una vez que se suba el archivo de secuencia de comandos, crea un recurso de secuencia de comandos de ofertas personalizadas con el método customBiddingAlgorithms.scripts.create. El objeto CustomBiddingScript que se pasa en la solicitud solo debe incluir el objeto CustomBiddingScriptRef como valor asignado del campo script. Esto asocia el archivo de secuencia de comandos que se subió con el nuevo recurso de secuencia de comandos.

Advertencia: Si el archivo de secuencia de comandos que subiste tiene un error de sintaxis, la solicitud customBiddingAlgorithms.scripts.create fallará y mostrará detalles sobre el error de sintaxis encontrado. Para subir un archivo de secuencia de comandos corregido, debes reiniciar este proceso mediante la recuperación de una nueva ubicación de recurso de secuencia de comandos.

Este es un ejemplo de cómo crear un recurso de secuencia de comandos:

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

Una vez que creas un recurso de secuencia de comandos de ofertas personalizadas, Display & Video 360 procesa la secuencia de comandos a fin de asegurarse de que se pueda usar correctamente para calificar las impresiones. Recupera el estado de este procesamiento a través del campo state del objeto de la secuencia de comandos. Una vez que se acepta la secuencia de comandos nueva, el algoritmo de ofertas personalizadas comienza a usarla para puntuar los valores de impresión. Esto sucede de inmediato, así que asegúrate de que deseas actualizar el algoritmo antes de crear un nuevo recurso de secuencia de comandos.

Reglas de carga

Los algoritmos de ofertas personalizadas basadas en reglas emplean la lógica proporcionada en un objeto AlgorithmRules para evaluar el valor de una impresión.

Los objetos AlgorithmRules se suben en un archivo JSON y, luego, se asocian con un algoritmo de ofertas personalizadas a través de un objeto CustomBiddingAlgorithmRules.

Recuperar la ubicación de un recurso de reglas

Primero, recupera una ubicación de recurso disponible en el recurso del algoritmo de ofertas personalizadas con el método customBiddingAlgorithms.uploadRules. Esta solicitud muestra un objeto CustomBiddingAlgorithmsRulesRef con un nombre de recurso. Puedes subir tu archivo de reglas a la ubicación que determina el nombre del recurso. Luego, utiliza el objeto de referencia de las reglas del algoritmo de ofertas personalizadas para crear tu recurso de reglas.

Este es un ejemplo de cómo recuperar una ubicación de recurso 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()
);

Subir un archivo AlgorithmRules

Después de recuperar una ubicación de recursos disponible, sube el archivo de reglas a esa ubicación en el sistema de Display & Video 360 con el método media.upload. Este método admite una carga simple que requiere el parámetro de consulta uploadType=media.

Advertencia: Los archivos JSON subidos AlgorithmRules tienen un tamaño máximo de 7 MB.

A continuación, se muestra un ejemplo de cómo subir un archivo AlgorithmRules según un objeto de referencia de reglas del algoritmo de ofertas personalizadas recuperado:

Sugerencia: Si no usas uno de los tres lenguajes de programación que se incluyen en esta guía, crea tu solicitud media.upload con la muestra del comando cURL proporcionada.

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

Cómo crear un objeto de reglas

Una vez que se suba el archivo JSON AlgorithmRules, crea un recurso de reglas de algoritmo de ofertas personalizadas con el método customBiddingAlgorithms.rules.create. El objeto CustomBiddingAlgorithmRules que se pasa en la solicitud solo debe incluir el objeto CustomBiddingAlgorithmRulesRef como valor asignado del campo rules. Esto asocia el archivo JSON AlgorithmRules que se subió con el nuevo recurso de reglas.

El siguiente es un ejemplo de cómo crear un recurso de reglas:

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

Una vez que creas un recurso de reglas, Display & Video 360 procesa el conjunto de reglas a fin de garantizar que se pueda usar correctamente para calificar las impresiones. Recupera el estado de este procesamiento a través del campo state del objeto de reglas. Una vez que se aceptan las reglas nuevas, el algoritmo de ofertas personalizadas comienza a utilizar las reglas para puntuar los valores de las impresiones de inmediato.

Si se rechazan las reglas, recupera el motivo del rechazo desde el error del objeto de las reglas. En caso de que se rechace, actualiza el objeto AlgorithmRules para corregir el error y repite el proceso de carga a partir de la recuperación del objeto de referencia de reglas.

Asignar un algoritmo de ofertas personalizadas

Después de crear un algoritmo de ofertas personalizadas, subir la lógica aceptada y cumplir con los requisitos necesarios, puedes asignarlo a la estrategia de ofertas de una línea de pedido o un pedido de inserción.

Puedes utilizar algoritmos de ofertas personalizadas en las estrategias de ofertas para maximizar la inversión y el objetivo de rendimiento. Para ello, asigna el BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO y el ID del algoritmo de ofertas personalizadas a los campos performanceGoalType y customBiddingAlgorithmId, respectivamente. Según la estrategia de oferta, es posible que se incluyan o se requieran otros parámetros de oferta.

A continuación, se muestra un ejemplo de cómo actualizar una línea de pedido para que use una estrategia de oferta para maximizar la inversión con un algoritmo de ofertas personalizadas determinado:

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