Menerapkan Bidding Kustom

Display & Video 360 API memungkinkan Anda mengelola penerapan bidding kustom sepenuhnya. Anda dapat membuat algoritma bidding kustom, mengupload dan memverifikasi setiap skrip, serta menetapkan algoritma tertentu ke resource sebagai strategi biddingnya.

Halaman ini menjelaskan cara membuat, memperbarui, dan menetapkan algoritma bidding kustom dengan Display & Video 360 API. Setiap bagian menyediakan contoh kode.

Membuat Algoritma Bidding Kustom

Objek CustomBiddingAlgorithm mewakili setiap algoritma yang dapat Anda tetapkan ke item baris untuk digunakan dalam strategi biddingnya. Objek ini memiliki detail tentang algoritme, seperti customBiddingAlgorithmType dan entityStatus, serta readinessState dan suspensionState untuk setiap model yang dihasilkan pengiklan yang relevan. Anda dapat membuat objek CustomBiddingScript dan CustomBiddingAlgorithmRules sebagai resource turunan untuk digunakan algoritma.

Berikut ini contoh cara membuat algoritma bidding kustom berbasis skrip:

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

Mengelola akses algoritme

Algoritma bidding kustom dapat dimiliki oleh partner atau pengiklan. Algoritme yang dimiliki oleh partner dapat diakses dan diubah oleh partner tersebut dan setiap pengiklan turunan yang tercantum di kolom sharedAdvertiserIds. Algoritma yang dimiliki oleh pengiklan dapat diakses dan diubah oleh pengiklan tersebut dan partner induknya, tetapi tidak dapat dibagikan kepada pengiklan lain.

Jika Anda hanya menggunakan algoritme untuk satu pengiklan, tetapkan pengiklan sebagai pemilik dengan kolom advertiserId. Jika tidak, tetapkan partner induk pengiklan sebagai pemilik dengan kolom partnerId, dan beri pengiklan akses dengan kolom sharedAdvertiserIds.

Mengupload logika algoritme

Bergantung pada jenis algoritma bidding kustom, Anda selanjutnya harus membuat skrip atau objek aturan tempat Anda dapat memberikan logika yang akan digunakan oleh algoritme.

Upload skrip

Algoritma bidding kustom berbasis skrip menggunakan skrip yang diberikan pengguna untuk mengevaluasi nilai tayangan. Contoh skrip sederhana dan daftar kolom lanjutan tersedia melalui Pusat Bantuan Display & Video 360.

Bagian berikut menunjukkan cara menambahkan skrip baru atau yang diperbarui ke algoritma bidding kustom.

Mengambil lokasi resource skrip

Pertama, ambil lokasi resource yang tersedia di bagian resource algoritma bidding kustom dengan metode customBiddingAlgorithms.uploadScript. Permintaan ini menampilkan objek CustomBiddingScriptRef dengan nama resource. Anda dapat mengupload file skrip ke lokasi yang ditentukan oleh nama resource. Kemudian, gunakan objek referensi skrip bidding kustom untuk membuat resource skrip.

Berikut adalah contoh cara mengambil lokasi resource yang tersedia:

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

Upload file skrip

Setelah mengambil lokasi resource yang tersedia, upload file skrip Anda ke lokasi tersebut dalam sistem Display & Video 360 dengan metode media.upload. Metode ini mendukung upload sederhana yang memerlukan parameter kueri uploadType=media.

Berikut adalah contoh cara mengupload file skrip berdasarkan objek referensi skrip bidding kustom yang diambil:

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

Membuat objek skrip

Setelah file skrip diupload, buat resource skrip bidding kustom dengan metode customBiddingAlgorithms.scripts.create. Objek CustomBiddingScript yang diteruskan dalam permintaan hanya boleh menyertakan objek CustomBiddingScriptRef sebagai nilai yang ditetapkan dari kolom script. Tindakan ini akan mengaitkan file skrip yang diupload dengan resource skrip baru.

Berikut adalah contoh cara membuat resource skrip:

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

Setelah Anda membuat resource skrip bidding kustom, Display & Video 360 memproses skrip untuk memastikannya berhasil digunakan untuk mendapatkan skor tayangan. Ambil status pemrosesan ini melalui kolom state objek skrip. Setelah skrip baru diterima, algoritma bidding kustom akan mulai menggunakan skrip tersebut untuk mendapatkan nilai tayangan iklan. Proses ini terjadi segera, jadi pastikan Anda ingin mengupdate algoritma sebelum membuat resource skrip baru.

Aturan upload

Algoritma bidding kustom berbasis aturan menggunakan logika yang disediakan dalam objek AlgorithmRules untuk mengevaluasi nilai tayangan.

Objek AlgorithmRules diupload dalam file JSON, lalu dikaitkan dengan algoritma bidding kustom melalui objek CustomBiddingAlgorithmRules.

Mengambil lokasi resource aturan

Pertama, ambil lokasi resource yang tersedia di bagian resource algoritma bidding kustom dengan metode customBiddingAlgorithms.uploadRules. Permintaan ini menampilkan objek CustomBiddingAlgorithmsRulesRef dengan nama resource. Anda dapat mengupload file aturan ke lokasi yang ditentukan oleh nama resource. Kemudian, gunakan objek referensi aturan algoritma bidding kustom untuk membuat resource aturan Anda.

Berikut adalah contoh cara mengambil lokasi resource yang tersedia:

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

Upload file AlgorithmRules

Setelah mengambil lokasi resource yang tersedia, upload file aturan Anda ke lokasi tersebut dalam sistem Display & Video 360 dengan metode media.upload. Metode ini mendukung upload sederhana yang memerlukan parameter kueri uploadType=media.

Berikut adalah contoh cara mengupload file AlgorithmRules berdasarkan objek referensi aturan algoritma bidding kustom yang diambil:

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

Membuat objek aturan

Setelah file JSON AlgorithmRules diupload, buat resource aturan algoritma bidding kustom dengan metode customBiddingAlgorithms.rules.create. Objek CustomBiddingAlgorithmRules yang diteruskan dalam permintaan hanya boleh menyertakan objek CustomBiddingAlgorithmRulesRef sebagai nilai yang ditetapkan dari kolom rules. Tindakan ini akan mengaitkan file JSON AlgorithmRules yang diupload dengan resource aturan baru.

Berikut adalah contoh cara membuat resource aturan:

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

Setelah Anda membuat resource aturan, Display & Video 360 memproses kumpulan aturan untuk memastikannya berhasil digunakan untuk mendapatkan skor tayangan. Ambil status pemrosesan ini melalui kolom state objek aturan. Setelah aturan baru diterima, algoritma bidding kustom akan langsung mulai menggunakan aturan tersebut untuk langsung menentukan skor tayangan iklan.

Jika aturan ditolak, ambil alasan penolakan dari error objek aturan. Jika terjadi penolakan, perbarui objek AlgorithmRules untuk memperbaiki error dan ulangi proses upload yang dimulai dari mengambil objek referensi aturan.

Tetapkan Algoritma Bidding Kustom

Setelah membuat algoritma bidding kustom, mengupload logika yang diterima, dan memenuhi persyaratan yang diperlukan, Anda dapat menetapkan algoritme bidding kustom untuk strategi bidding item baris atau perjanjian pemasangan iklan.

Anda dapat menggunakan algoritma bidding kustom dalam strategi bidding memaksimalkan pembelanjaan dan sasaran performa dengan menetapkan BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO dan ID algoritma bidding kustom ke masing-masing kolom performanceGoalType dan customBiddingAlgorithmId. Bergantung pada strategi bidding, parameter bid lain mungkin tersedia atau wajib ada.

Berikut adalah contoh cara memperbarui item baris untuk menggunakan strategi bidding maksimalkan pembelanjaan dengan algoritma bidding kustom tertentu:

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']
);
Sebelumnya
Mengambil item baris YouTube & Partners
Berikutnya
Mengaktifkan item baris