Implementa le offerte personalizzate

L'API Display & Video 360 ti consente di gestire completamente le implementazioni delle offerte personalizzate. Puoi creare algoritmi di offerte personalizzate, caricare e verificare singoli script e assegnare un algoritmo specifico a una risorsa come strategia di offerta.

Beta: gli algoritmi di offerte personalizzate basati su regole sono disponibili solo per un numero limitato di utenti.

Questa pagina descrive come creare, aggiornare e assegnare algoritmi di offerte personalizzate con l'API Display & Video 360. Ogni sezione fornisce un esempio di codice.

Creare un algoritmo di offerte personalizzate

Un oggetto CustomBiddingAlgorithm rappresenta un singolo algoritmo che puoi assegnare a un elemento pubblicitario per utilizzarlo nella relativa strategia di offerta. Questo oggetto contiene dettagli sull'algoritmo, come customBiddingAlgorithmType e entityStatus, nonché readinessState e suspensionState per il modello generato da ogni inserzionista pertinente. Puoi creare oggetti CustomBiddingScript e CustomBiddingAlgorithmRules come risorse figlio che l'algoritmo utilizzerà.

Nota: questa guida si concentra sugli algoritmi di offerte personalizzate basate su script e regole. Gli algoritmi creati in Ads Data Hub o tramite lo strumento per la creazione di obiettivi dell'interfaccia utente di Display & Video 360 possono essere recuperati e assegnati, ma non possono essere gestiti completamente.

Di seguito è riportato un esempio di come creare un algoritmo di offerte personalizzate basato su 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']);

Gestisci l'accesso all'algoritmo

Gli algoritmi di offerte personalizzate possono essere di proprietà di un partner o di un inserzionista. Gli algoritmi di proprietà di un partner sono accessibili e modificati dal partner stesso e da qualsiasi inserzionista secondario elencato nel campo sharedAdvertiserIds. L'inserzionista e il partner principale possono accedere agli algoritmi di proprietà di un inserzionista e modificarli, ma non possono essere condivisi con altri inserzionisti.

Nota: quando crei un algoritmo di offerte personalizzate, devi disporre dell'accesso in lettura/scrittura al partner o all'inserzionista che assegni come proprietario.

Se utilizzi l'algoritmo solo per un singolo inserzionista, assegna l'inserzionista come proprietario con il campo advertiserId. In caso contrario, assegna il partner principale degli inserzionisti come proprietario con il campo partnerId e concedi agli inserzionisti l'accesso con il campo sharedAdvertiserIds.

Logica dell'algoritmo di caricamento

A seconda del tipo di algoritmo delle offerte personalizzate, devi poi creare uno script o un oggetto regole in cui puoi fornire la logica da utilizzare per l'algoritmo.

Carica uno script

Gli algoritmi di offerte personalizzate basati su script utilizzano script forniti dall'utente per valutare il valore di un'impressione. Esempi di script semplici e un elenco di campi avanzati sono disponibili nel Centro assistenza Display & Video 360.

Le seguenti sezioni spiegano come aggiungere uno script nuovo o aggiornato a un algoritmo di offerte personalizzate.

Recupera la località di una risorsa di script

Innanzitutto, recupera una località disponibile sotto l'algoritmo delle offerte personalizzate con il metodo customBiddingAlgorithms.uploadScript. Questa richiesta restituisce un oggetto CustomBiddingScriptRef con un nome risorsa. Puoi caricare il file di script nella posizione indicata dal nome della risorsa. Quindi, utilizza l'oggetto di riferimento allo script di offerte personalizzate per creare la risorsa script.

Ecco un esempio di come recuperare una località delle risorse disponibile:

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

Carica un file di script

Dopo aver recuperato una posizione delle risorse disponibile, carica il file di script in quella posizione nel sistema Display & Video 360 con il metodo media.upload. Questo metodo supporta un caricamento semplice che richiede il parametro di ricerca uploadType=media.

Avviso: gli script di offerte personalizzate hanno una dimensione massima del file di 7 MB.

Ecco un esempio di come caricare un file di script in presenza di un oggetto di riferimento per lo script di offerte personalizzate recuperato:

Suggerimento: se non utilizzi uno dei tre linguaggi di programmazione inclusi in questa guida, crea la tua richiesta media.upload utilizzando l'esempio di comando cURL fornito.

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 oggetto script

Una volta caricato il file di script, crea una risorsa script di offerte personalizzate con il metodo customBiddingAlgorithms.scripts.create. L'oggetto CustomBiddingScript passato nella richiesta deve includere solo l'oggetto CustomBiddingScriptRef come valore assegnato del campo script. In questo modo il file di script caricato viene associato alla nuova risorsa di script.

Avviso: se il file di script caricato contiene un errore di sintassi, la richiesta customBiddingAlgorithms.scripts.create non andrà a buon fine e restituirà i dettagli relativi all'errore di sintassi rilevato. Per caricare un file di script corretto, devi riavviare questo processo recuperando una nuova posizione della risorsa di script.

Ecco un esempio di come creare una risorsa 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());

Una volta creata una risorsa di script delle offerte personalizzate, Display & Video 360 elabora lo script per assicurarsi che possa essere utilizzato correttamente per assegnare un punteggio alle impressioni. Recupera lo stato di questa elaborazione tramite il campo state dell'oggetto script. Una volta accettato il nuovo script, l'algoritmo delle offerte personalizzate inizia a utilizzarlo per assegnare un punteggio ai valori delle impressioni. Questo avviene immediatamente, quindi assicurati di voler aggiornare l'algoritmo prima di creare una nuova risorsa di script.

Regole di caricamento

Gli algoritmi di offerte personalizzate basati su regole utilizzano la logica fornita in un oggetto AlgorithmRules per valutare il valore di un'impressione.

Gli oggetti AlgorithmRules vengono caricati in un file JSON e poi associati a un algoritmo di offerte personalizzate tramite un oggetto CustomBiddingAlgorithmRules.

Recuperare una località delle risorse delle regole

Innanzitutto, recupera una località disponibile sotto l'algoritmo delle offerte personalizzate con il metodo customBiddingAlgorithms.uploadRules. Questa richiesta restituisce un oggetto CustomBiddingAlgorithmsRulesRef con un nome risorsa. Puoi caricare il file delle regole nella località indicata dal nome della risorsa. Quindi utilizza l'oggetto di riferimento delle regole dell'algoritmo delle offerte personalizzate per creare la risorsa delle regole.

Ecco un esempio di come recuperare una località delle risorse disponibile:

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

Carica un file AlgorithmRules

Dopo aver recuperato una località delle risorse disponibile, carica il file delle regole in quella posizione nel sistema Display & Video 360 con il metodo media.upload. Questo metodo supporta un caricamento semplice che richiede il parametro di ricerca uploadType=media.

Avviso: la dimensione massima dei file JSON AlgorithmRules caricati è di 7 MB.

Ecco un esempio di come caricare un file AlgorithmRules dato un oggetto di riferimento alle regole dell'algoritmo delle offerte personalizzate recuperato:

Suggerimento: se non utilizzi uno dei tre linguaggi di programmazione inclusi in questa guida, crea la tua richiesta media.upload utilizzando l'esempio di comando cURL fornito.

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

Creare un oggetto regole

Dopo aver caricato il file JSON AlgorithmRules, crea una risorsa delle regole dell'algoritmo delle offerte personalizzate con il metodo customBiddingAlgorithms.rules.create. L'oggetto CustomBiddingAlgorithmRules passato nella richiesta deve includere solo l'oggetto CustomBiddingAlgorithmRulesRef come valore assegnato del campo rules. In questo modo il file JSON AlgorithmRules caricato viene associato alla nuova risorsa delle regole.

Ecco un esempio di come creare una risorsa regole:

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 volta creata una risorsa delle regole, Display & Video 360 elabora il set di regole per assicurarsi che possa essere utilizzata correttamente per assegnare un punteggio alle impressioni. Recupera lo stato di questa elaborazione tramite il campo state dell'oggetto regole. Una volta accettate le nuove regole, l'algoritmo delle offerte personalizzate inizia a utilizzarle per assegnare immediatamente un punteggio ai valori delle impressioni.

Se le regole vengono rifiutate, recupera il motivo del rifiuto dal error dell'oggetto regole. In caso di rifiuto, aggiorna l'oggetto AlgorithmRules per correggere l'errore e ripeti il processo di caricamento iniziando dal recupero dell'oggetto di riferimento delle regole.

Assegnare un algoritmo di offerte personalizzate

Dopo aver creato un algoritmo delle offerte personalizzate, caricato la logica accettata e soddisfatto i requisiti necessari, puoi assegnare l'algoritmo di offerte personalizzate alla strategia di offerta di un elemento pubblicitario o di un ordine di inserzione.

Puoi utilizzare gli algoritmi delle offerte personalizzate nelle strategie di offerta Massimizza la spesa e Obiettivo di rendimento assegnando BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO e ID algoritmo delle offerte personalizzate rispettivamente ai campi performanceGoalType e customBiddingAlgorithmId. A seconda della strategia di offerta, potrebbero essere disponibili o obbligatori altri parametri di offerta.

Di seguito è riportato un esempio di come aggiornare un elemento pubblicitario per utilizzare una strategia di offerta Massimizza la spesa con un determinato algoritmo di offerte personalizzate:

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