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