Menerapkan Bidding Kustom

Layar & Video 360 API memungkinkan Anda mengelola bidding kustom sepenuhnya implementasi yang tepat. Anda dapat membuat algoritma bidding kustom, mengupload, dan memverifikasi skrip individu, dan menetapkan algoritma tertentu ke sumber daya sebagai bidding-nya strategi.

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

Membuat Algoritma Bidding Kustom

Objek CustomBiddingAlgorithm mewakili individu yang dapat ditetapkan ke item baris untuk digunakan dalam strategi biddingnya. Ini memiliki detail algoritma, seperti customBiddingAlgorithmType dan entityStatus, serta readinessState dan suspensionState untuk model yang dibuat pengiklan terkait. Anda dapat membuat CustomBiddingScript dan Objek CustomBiddingAlgorithmRules sebagai resource turunan untuk algoritma yang berbeda.

Berikut adalah contoh cara membuat algoritma bidding kustom berbasis skrip:

// 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}')

// 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 algoritma

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

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

Upload logika algoritma

Bergantung pada jenis algoritma bidding kustom, Anda selanjutnya harus membuat skrip atau objek rules tempat Anda dapat menyediakan logika untuk digunakan oleh algoritma.

Upload skrip

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

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

Mengambil lokasi resource skrip

Pertama, ambil lokasi resource yang tersedia di bagian bidding kustom resource algoritma dengan Metode customBiddingAlgorithms.uploadScript. Ini menampilkan objek CustomBiddingScriptRef dengan nama resource. Anda dapat upload file skrip Anda ke lokasi yang ditentukan oleh nama resource. Lalu, gunakan objek referensi skrip bidding kustom untuk buat resource skrip.

Berikut adalah contoh cara mengambil lokasi resource yang tersedia:

// 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}')

// 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 resource tersebut di tab Display & Video 360 dengan Metode media.upload. Metode ini mendukung objek upload sederhana yang memerlukan parameter kueri uploadType=media.

Berikut adalah contoh cara mengupload file skrip yang diberikan objek referensi skrip bidding:

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

// 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 --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. Tujuan Objek CustomBiddingScript yang diteruskan dalam permintaan hanya boleh sertakan objek CustomBiddingScriptRef sebagai objek yang ditetapkan nilai kolom script. Hal ini mengaitkan file yang diupload file skrip dengan resource skrip baru.

Berikut adalah contoh cara membuat resource skrip:

// 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}')

// 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 aset skrip bidding kustom, kampanye Display & Video 360 memproses untuk memastikan bahwa skrip itu berhasil digunakan untuk mencetak tayangan. Ambil status pemrosesan ini melalui metode Kolom state. Setelah skrip baru diterima, algoritma bidding mulai menggunakan skrip untuk menilai nilai tayangan. Ini terjadi seketika, jadi pastikan Anda ingin memperbarui algoritma sebelum membuat resource skrip baru.

Upload aturan

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

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

Mengambil lokasi resource aturan

Pertama, ambil lokasi resource yang tersedia di bagian bidding kustom resource algoritma dengan Metode customBiddingAlgorithms.uploadRules. Ini permintaan menampilkan objek CustomBiddingAlgorithmsRulesRef dengan nama resource. Anda dapat mengupload aturan ke lokasi yang ditentukan oleh nama resource. Selanjutnya gunakan objek referensi aturan algoritma bidding kustom untuk membuat aturan resource.

Berikut adalah contoh cara mengambil lokasi resource yang tersedia:

// 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}')

// 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 resource tersebut di tab Display & Video 360 dengan Metode media.upload. Metode ini mendukung objek upload sederhana yang memerlukan parameter kueri uploadType=media.

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

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

// 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 --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 bidding kustom resource aturan algoritma dengan Metode customBiddingAlgorithms.rules.create. Tujuan Objek CustomBiddingAlgorithmRules yang diteruskan dalam permintaan harus hanya sertakan objek CustomBiddingAlgorithmRulesRef sebagai nilai yang ditetapkan dari kolom rules. Hal ini mengaitkan mengupload AlgorithmRules file JSON dengan resource aturan baru.

Berikut adalah contoh cara membuat resource aturan:

// 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}')

// 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 aset aturan, kampanye Display & Video 360 memproses kumpulan aturan untuk membuat memastikan bahwa iklan tersebut dapat berhasil digunakan untuk mencetak tayangan. Mengambil status pemrosesan ini melalui kolom state objek aturan. Setelah aturan baru diterima, algoritma bidding kustom akan mulai menggunakan lainnya untuk langsung menilai nilai tayangan.

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

Menetapkan Algoritma Bidding Kustom

Setelah membuat algoritma bidding kustom, upload logika yang diterima, dan penuhi persyaratan yang diperlukan, Anda dapat menetapkan algoritma bidding ke strategi bidding item baris atau pesanan pemasangan iklan.

Anda dapat menggunakan algoritma bidding kustom di memaksimalkan pembelanjaan dan strategi bidding sasaran performa dengan menetapkan BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO dan ID algoritma bidding kustom ke performanceGoalType dan customBiddingAlgorithmId kolom. Bergantung pada strategi bidding, parameter bid lain mungkin tersedia atau tidak diperlukan.

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

// 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"]}.')

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