Özel Teklif Verme özelliğini uygulayın

Display & Video 360 API, özel teklif uygulamalarını tümüyle yönetmenize olanak tanır. Özel teklif verme algoritmaları oluşturabilir, tek tek komut dosyaları yükleyip doğrulayabilir ve teklif stratejisi olarak bir kaynağa belirli bir algoritma atayabilirsiniz.

Bu sayfada, Display & Video 360 API ile özel teklif verme algoritmalarının nasıl oluşturulacağı, güncelleneceği ve atanacağı açıklanmaktadır. Her bölümde bir kod örneği sunulur.

Özel Teklif Algoritması Oluşturma

CustomBiddingAlgorithm nesnesi, teklif stratejisinde kullanmak üzere bir satır öğesine atayabileceğiniz bağımsız bir algoritmayı temsil eder. Bu nesne, alakalı her reklamverenin oluşturulan modeli için customBiddingAlgorithmType ve entityStatus gibi algoritmanın yanı sıra readinessState ve suspensionState gibi ayrıntıları da içerir. Algoritmanın kullanması için alt kaynaklar olarak CustomBiddingScript ve CustomBiddingAlgorithmRules nesnelerini oluşturabilirsiniz.

Aşağıda, komut dosyası tabanlı özel teklif verme algoritmasının nasıl oluşturulacağına dair bir örnek verilmiştir:

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

Algoritma erişimini yönetme

Özel teklif verme algoritmaları, bir iş ortağına veya reklamverene ait olabilir. Bir iş ortağına ait algoritmalara, söz konusu iş ortağı ve sharedAdvertiserIds alanında listelenen alt reklamverenler tarafından erişilebilir ve bu algoritmalar değiştirilebilir. Bir reklamverene ait algoritmalar, söz konusu reklamveren ve üst iş ortağı tarafından erişilebilir ve değiştirilebilir ancak diğer reklamverenlerle paylaşılamaz.

Algoritmayı yalnızca tek bir reklamverene yönelik olarak kullanıyorsanız reklamvereni advertiserId alanıyla sahip olarak atayın. Aksi takdirde, reklamverenlerin ana iş ortağını partnerId alanıyla sahip olarak atayın ve reklamverenlere sharedAdvertiserIds alanıyla erişim izni verin.

Algoritma mantığını yükle

Özel teklif verme algoritmanızın türüne bağlı olarak, algoritmanın kullanacağı mantığı sağlayabileceğiniz bir komut dosyası veya kurallar nesnesi oluşturmanız gerekir.

Komut dosyası yükleyin

Komut dosyası tabanlı özel teklif verme algoritmaları, bir gösterimin değerini değerlendirmek için kullanıcı tarafından sağlanan komut dosyalarını kullanır. Basit komut dosyaları örnekleri ve gelişmiş alanların bir listesine Display & Video 360 Yardım Merkezi'nden ulaşabilirsiniz.

Aşağıdaki bölümlerde, özel teklif verme algoritmasına yeni veya güncellenmiş komut dosyası ekleme hakkında bilgi verilmektedir.

Komut dosyası kaynak konumunu alma

Öncelikle customBiddingAlgorithms.uploadScript yöntemiyle özel teklif verme algoritması kaynağı altında kullanılabilir bir kaynak konumu alın. Bu istek, kaynak adına sahip bir CustomBiddingScriptRef nesnesi döndürür. Komut dosyanızı kaynak adı tarafından belirtilen konuma yükleyebilirsiniz. Ardından, komut dosyası kaynağınızı oluşturmak için özel teklif verme komut dosyası referans nesnesini kullanın.

Kullanılabilir bir kaynağın konumunu nasıl alabileceğinizle ilgili bir örnek aşağıda verilmiştir:

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

Komut dosyası yükleme

Kullanılabilir bir kaynak konumunu aldıktan sonra komut dosyası dosyanızı, media.upload yöntemini kullanarak Display & Video 360 sisteminde bu konuma yükleyin. Bu yöntem, uploadType=media sorgu parametresini gerektiren basit yüklemeyi destekler.

Alınan bir özel teklif verme komut dosyası referans nesnesine göre komut dosyası dosyasının nasıl yükleneceğine dair bir örneği aşağıda bulabilirsiniz:

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

Komut dosyası nesnesi oluşturma

Komut dosyası yüklendikten sonra customBiddingAlgorithms.scripts.create yöntemiyle bir özel teklif verme komut dosyası kaynağı oluşturun. İstekte iletilen CustomBiddingScript nesnesi, script alanının atanan değeri olarak yalnızca CustomBiddingScriptRef nesnesini içermelidir. Bu işlem, yüklenen komut dosyasını yeni komut dosyası kaynağıyla ilişkilendirir.

Aşağıda, komut dosyası kaynağının nasıl oluşturulacağına ilişkin bir örnek verilmiştir:

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

Özel teklif verme komut dosyası kaynağı oluşturduğunuzda Display & Video 360, komut dosyasını gösterimlere puan vermek için başarıyla kullanılabilmesini sağlamak amacıyla işler. Bu işlemenin durumunu, komut dosyası nesnesinin state alanından alın. Yeni komut dosyası kabul edildikten sonra, özel teklif verme algoritması gösterim değerlerini puanlamak için komut dosyasını kullanmaya başlar. Bu işlem hemen gerçekleşir. Bu nedenle, yeni bir komut dosyası kaynağı oluşturmadan önce algoritmayı güncellemek istediğinizden emin olun.

Kuralları yükle

Kurallara dayalı özel teklif verme algoritmaları, bir gösterimin değerini değerlendirmek için AlgorithmRules nesnesinde sağlanan mantığı kullanır.

AlgorithmRules nesneleri bir JSON dosyasında yüklenir ve daha sonra CustomBiddingAlgorithmRules nesnesi aracılığıyla özel bir teklif verme algoritmasıyla ilişkilendirilir.

Kural kaynağı konumu alma

Öncelikle customBiddingAlgorithms.uploadRules yöntemiyle özel teklif verme algoritması kaynağı altında kullanılabilir bir kaynak konumu alın. Bu istek, kaynak adına sahip bir CustomBiddingAlgorithmsRulesRef nesnesi döndürür. Kural dosyanızı, kaynak adı tarafından belirtilen konuma yükleyebilirsiniz. Ardından, kural kaynağınızı oluşturmak için özel teklif verme algoritması kuralları referans nesnesini kullanın.

Kullanılabilir bir kaynağın konumunu nasıl alabileceğinizle ilgili bir örnek aşağıda verilmiştir:

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

AlgorithmRules dosyası yükle

Kullanılabilir bir kaynak konumunu aldıktan sonra kurallar dosyanızı Display & Video 360 sisteminde media.upload yöntemiyle söz konusu konuma yükleyin. Bu yöntem, uploadType=media sorgu parametresini gerektiren basit yüklemeyi destekler.

Alınan özel teklif verme algoritması kuralları referans nesnesine göre AlgorithmRules dosyasının nasıl yükleneceğine dair bir örneği burada bulabilirsiniz:

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

Kural nesnesi oluşturma

AlgorithmRules JSON dosyası yüklendikten sonra customBiddingAlgorithms.rules.create yöntemiyle özel teklif verme algoritması kuralları kaynağı oluşturun. İstekte iletilen CustomBiddingAlgorithmRules nesnesi, rules alanının atanmış değeri olarak yalnızca CustomBiddingAlgorithmRulesRef nesnesini içermelidir. Bu işlem, yüklenen AlgorithmRules JSON dosyasını yeni kurallar kaynağıyla ilişkilendirir.

Aşağıda, kural kaynağı oluşturma örneği verilmiştir:

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

Kural kaynağı oluşturduğunuzda, Display & Video 360, gösterimleri puanlamak için başarıyla kullanılabilmesini sağlamak amacıyla kural kümesini işler. Bu işlemenin durumunu kural nesnesinin state alanından alın. Yeni kurallar kabul edildikten sonra, özel teklif verme algoritması gösterim değerlerini hemen puanlamak için kuralları kullanmaya başlar.

Kurallar reddedilirse kural nesnesinin error öğesinden reddedilme nedenini alın. Reddedilme durumunda, hatayı düzeltmek için AlgorithmRules nesnenizi güncelleyin ve kural referans nesnesini almaktan başlayarak yükleme işlemini tekrarlayın.

Özel Teklif Algoritması Atama

Özel teklif verme algoritması oluşturduktan, kabul edilen mantığı yükledikten ve gerekli koşulları karşıladıktan sonra, özel teklif verme algoritmanızı bir satır öğesinin veya kampanya siparişinin teklif stratejisine atayabilirsiniz.

performanceGoalType ve customBiddingAlgorithmId alanlarına sırasıyla BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO ve özel teklif verme algoritması kimliğini atayarak harcamayı en üst düzeye çıkarma ve performans hedefi teklif stratejilerinde özel teklif verme algoritmalarını kullanabilirsiniz. Teklif stratejisine bağlı olarak, diğer teklif parametreleri kullanılabilir veya gerekli olabilir.

Aşağıda, bir satır öğesinin belirli bir özel teklif verme algoritmasıyla harcamayı artırma teklif stratejisini kullanacak şekilde nasıl güncelleneceğine dair örnek verilmiştir:

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