Display & Video 360 API به شما امکان می دهد پیاده سازی های پیشنهادی سفارشی را به طور کامل مدیریت کنید. میتوانید الگوریتمهای پیشنهادی سفارشی ایجاد کنید، اسکریپتهای فردی را آپلود و تأیید کنید، و الگوریتم خاصی را به عنوان استراتژی مناقصه به یک منبع اختصاص دهید.
این صفحه نحوه ایجاد، بهروزرسانی و اختصاص الگوریتمهای مناقصه سفارشی با Display & Video 360 API را شرح میدهد. هر بخش یک نمونه کد ارائه می دهد.
یک الگوریتم مناقصه سفارشی ایجاد کنید
یک شیء CustomBiddingAlgorithm
نشان دهنده یک الگوریتم جداگانه است که می توانید به یک آیتم خطی برای استفاده در استراتژی پیشنهاد آن اختصاص دهید. این شی دارای جزئیاتی در مورد الگوریتم است، مانند customBiddingAlgorithmType
و entityStatus
، و همچنین readinessState
و suspensionState
برای هر مدل ایجاد شده توسط تبلیغ کننده مرتبط. شما می توانید اشیاء CustomBiddingScript
و CustomBiddingAlgorithmRules
را به عنوان منابع فرزند برای الگوریتم ایجاد کنید.
در اینجا مثالی از نحوه ایجاد یک الگوریتم پیشنهادی سفارشی مبتنی بر اسکریپت آورده شده است:
جاوا
// 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()
);
پایتون
# 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']);
دسترسی الگوریتم را مدیریت کنید
الگوریتم های مناقصه سفارشی می تواند متعلق به یک شریک یا یک تبلیغ کننده باشد. الگوریتم های متعلق به یک شریک توسط آن شریک و هر تبلیغ کننده فرزند فهرست شده در قسمت sharedAdvertiserIds
قابل دسترسی و اصلاح هستند. الگوریتمهای متعلق به یک تبلیغکننده میتوانند توسط آن تبلیغکننده و شریک اصلی او قابل دسترسی و اصلاح باشند، اما نمیتوانند با تبلیغکنندگان دیگر به اشتراک گذاشته شوند.
اگر از الگوریتم فقط برای یک تبلیغکننده استفاده میکنید، تبلیغکننده را به عنوان مالک با قسمت advertiserId
اختصاص دهید. در غیر این صورت، شریک والد تبلیغکنندگان را بهعنوان مالک با فیلد partnerId
اختصاص دهید و به تبلیغکنندگان اجازه دسترسی با قسمت sharedAdvertiserIds
را بدهید.
منطق الگوریتم آپلود
بسته به نوع الگوریتم مناقصه سفارشی شما، در مرحله بعد باید یک اسکریپت یا یک شیء قوانین ایجاد کنید تا بتوانید منطقی را برای استفاده از الگوریتم ارائه دهید.
یک اسکریپت آپلود کنید
الگوریتمهای پیشنهادی سفارشی مبتنی بر اسکریپت از اسکریپتهای ارائهشده توسط کاربر برای ارزیابی ارزش یک نمایش استفاده میکنند. نمونههایی از اسکریپتهای ساده و فهرستی از فیلدهای پیشرفته از طریق مرکز راهنمای Display & Video 360 در دسترس هستند.
بخش های زیر به شما آموزش می دهند که چگونه یک اسکریپت جدید یا به روز شده را به یک الگوریتم پیشنهاد قیمت سفارشی اضافه کنید.
یک مکان منبع اسکریپت را بازیابی کنید
ابتدا، با روش customBiddingAlgorithms.uploadScript
، یک مکان منبع موجود را تحت منبع الگوریتم پیشنهاد سفارشی بازیابی کنید. این درخواست یک شی CustomBiddingScriptRef
را با نام منبع برمی گرداند. شما می توانید فایل اسکریپت خود را در مکانی که با نام منبع دیکته شده است آپلود کنید . سپس از شی مرجع اسکریپت پیشنهادی سفارشی برای ایجاد منبع اسکریپت خود استفاده کنید.
در اینجا مثالی از نحوه بازیابی مکان منبع موجود آورده شده است:
جاوا
// 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()
);
پایتون
# 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()
);
یک فایل اسکریپت را آپلود کنید
پس از بازیابی یک مکان منبع موجود، فایل اسکریپت خود را در آن مکان در سیستم Display & Video 360 با روش media.upload
آپلود کنید. این روش از یک آپلود ساده که به پارامتر پرس و جو نیاز دارد uploadType=media
پشتیبانی می کند.
در اینجا مثالی از نحوه آپلود یک فایل اسکریپت با توجه به یک شی مرجع اسکریپت پیشنهادی سفارشی بازیابی شده آورده شده است:
جاوا
// 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));
پایتون
# 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
یک شی اسکریپت ایجاد کنید
هنگامی که فایل اسکریپت آپلود شد، با روش customBiddingAlgorithms.scripts.create
یک منبع اسکریپت پیشنهادی سفارشی ایجاد کنید. شی CustomBiddingScript
ارسال شده در درخواست فقط باید شی CustomBiddingScriptRef
را به عنوان مقدار تخصیص یافته فیلد script
شامل شود. این فایل اسکریپت آپلود شده را با منبع اسکریپت جدید مرتبط می کند.
در اینجا مثالی از نحوه ایجاد یک منبع اسکریپت آورده شده است:
جاوا
// 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());
پایتون
# 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());
هنگامی که یک منبع اسکریپت مناقصه سفارشی ایجاد کردید، Display & Video 360 اسکریپت را پردازش میکند تا مطمئن شود که میتواند با موفقیت برای امتیاز دادن به نمایشها استفاده شود. وضعیت این پردازش را از طریق فیلد state
شی اسکریپت بازیابی کنید. هنگامی که اسکریپت جدید پذیرفته شد، الگوریتم مناقصه سفارشی شروع به استفاده از اسکریپت برای امتیاز دادن به مقادیر نمایش می کند. این بلافاصله اتفاق می افتد، بنابراین مطمئن شوید که می خواهید الگوریتم را قبل از ایجاد یک منبع اسکریپت جدید به روز کنید.
قوانین آپلود
الگوریتمهای مناقصه سفارشی مبتنی بر قوانین، از منطق ارائه شده در شیء AlgorithmRules
برای ارزیابی ارزش یک نمایش استفاده میکنند.
اشیاء AlgorithmRules
در یک فایل JSON آپلود می شوند و سپس از طریق یک شی CustomBiddingAlgorithmRules
با یک الگوریتم پیشنهادی سفارشی مرتبط می شوند.
مکان منبع قوانین را بازیابی کنید
ابتدا، با روش customBiddingAlgorithms.uploadRules
، یک مکان منبع موجود را تحت منبع الگوریتم پیشنهاد سفارشی بازیابی کنید. این درخواست یک شی CustomBiddingAlgorithmsRulesRef
را با نام منبع برمی گرداند. می توانید فایل قوانین خود را در مکانی که نام منبع دیکته شده است آپلود کنید . سپس از شی مرجع قوانین الگوریتم مناقصه سفارشی برای ایجاد منبع قوانین خود استفاده کنید.
در اینجا مثالی از نحوه بازیابی مکان منبع موجود آورده شده است:
جاوا
// 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()
);
پایتون
# 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
را آپلود کنید
پس از بازیابی مکان منبع موجود، فایل قوانین خود را در آن مکان در سیستم Display & Video 360 با روش media.upload
آپلود کنید. این روش از یک آپلود ساده که به پارامتر پرس و جو نیاز دارد uploadType=media
پشتیبانی می کند.
در اینجا مثالی از نحوه آپلود فایل AlgorithmRules
با توجه به یک شی مرجع قوانین الگوریتم پیشنهاد قیمت سفارشی بازیابی شده آورده شده است:
جاوا
// 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));
پایتون
# 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
یک شیء قوانین ایجاد کنید
هنگامی که فایل JSON AlgorithmRules
آپلود شد، با روش customBiddingAlgorithms.rules.create
یک منبع قوانین الگوریتم پیشنهاد قیمت سفارشی ایجاد کنید. شی CustomBiddingAlgorithmRules
ارسال شده در درخواست فقط باید شی CustomBiddingAlgorithmRulesRef
را به عنوان مقدار تخصیص یافته فیلد rules
شامل شود. این فایل JSON AlgorithmRules
آپلود شده را با منبع قوانین جدید مرتبط می کند.
در اینجا مثالی از نحوه ایجاد یک منبع قوانین آورده شده است:
جاوا
// 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());
پایتون
# 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());
هنگامی که یک منبع قوانین ایجاد می کنید، Display & Video 360 مجموعه قوانین را پردازش می کند تا مطمئن شود که می تواند با موفقیت برای امتیاز دادن به نمایش ها استفاده شود. وضعیت این پردازش را از طریق فیلد state
شی قوانین بازیابی کنید. هنگامی که قوانین جدید پذیرفته می شوند، الگوریتم پیشنهاد سفارشی شروع به استفاده از قوانین برای به دست آوردن مقادیر نمایش فورا می کند.
اگر قوانین رد شدند، دلیل رد را از error
شی قوانین بازیابی کنید. در صورت رد، شی AlgorithmRules
خود را برای رفع خطا بهروزرسانی کنید و فرآیند آپلود را با شروع بازیابی شی مرجع قوانین تکرار کنید.
یک الگوریتم مناقصه سفارشی اختصاص دهید
پس از ایجاد یک الگوریتم مناقصه سفارشی، آپلود منطق پذیرفته شده، و برآوردن الزامات لازم ، می توانید الگوریتم پیشنهاد قیمت سفارشی خود را به استراتژی پیشنهاد قیمت یک آیتم خطی یا سفارش درج اختصاص دهید.
میتوانید با اختصاص دادن BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO
و شناسه الگوریتم پیشنهاد سفارشی به ترتیب به فیلدهای performanceGoalType
و customBiddingAlgorithmId
، از الگوریتمهای مناقصه سفارشی برای به حداکثر رساندن هزینهها و استراتژیهای پیشنهاد عملکرد هدف استفاده کنید. بسته به استراتژی پیشنهاد، سایر پارامترهای پیشنهادی ممکن است در دسترس یا مورد نیاز باشند.
در اینجا نمونهای از نحوه بهروزرسانی یک آیتم خط برای استفاده از استراتژی پیشنهاد حداکثر هزینه با یک الگوریتم پیشنهادی سفارشی ارائه شده است:
جاوا
// 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());
پایتون
# 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']
);