맞춤 입찰 구현

Display & Video 360 API를 사용하면 맞춤 입찰 구현을 완전히 관리할 수 있습니다. 맞춤 입찰 알고리즘을 만들고, 개별 스크립트를 업로드 및 확인하고, 특정 알고리즘을 리소스에 입찰 전략으로 할당할 수 있습니다.

이 페이지에서는 Display & Video 360 API를 사용하여 맞춤 입찰 알고리즘을 생성, 업데이트, 할당하는 방법을 설명합니다. 각 섹션에는 코드 샘플이 제공됩니다.

맞춤 입찰 알고리즘 만들기

CustomBiddingAlgorithm 객체는 입찰 전략에 사용하기 위해 광고 항목에 할당할 수 있는 개별 알고리즘을 나타냅니다. 이 객체에는 customBiddingAlgorithmTypeentityStatus와 같은 알고리즘에 관한 세부정보와 각 관련 광고주의 생성된 모델에 관한 readinessStatesuspensionState가 포함됩니다. 알고리즘에서 사용할 하위 리소스로 CustomBiddingScriptCustomBiddingAlgorithmRules 객체를 만들 수 있습니다.

다음은 스크립트 기반 맞춤 입찰 알고리즘을 만드는 방법의 예입니다.

자바

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

알고리즘 액세스 관리

맞춤 입찰 알고리즘은 파트너 또는 광고주가 소유할 수 있습니다. 파트너가 소유한 알고리즘은 해당 파트너와 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()
);

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

스크립트 파일 업로드

사용 가능한 리소스 위치를 검색한 후 media.upload 메서드를 사용하여 Display & Video 360 시스템의 해당 위치에 스크립트 파일을 업로드합니다. 이 메서드는 쿼리 매개변수 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));

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

스크립트 객체 만들기

스크립트 파일이 업로드되면 customBiddingAlgorithms.scripts.create 메서드로 커스텀 입찰 스크립트 리소스를 만듭니다. 요청에 전달된 CustomBiddingScript 객체는 script 필드의 할당된 값으로 CustomBiddingScriptRef 객체만 포함해야 합니다. 이렇게 하면 업로드된 스크립트 파일이 새 스크립트 리소스와 연결됩니다.

다음은 스크립트 리소스를 만드는 방법의 예입니다.

자바

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

맞춤 입찰 스크립트 리소스를 만들면 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()
);

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 파일 업로드

사용 가능한 리소스 위치를 가져온 후 media.upload 메서드를 사용하여 Display & Video 360 시스템의 해당 위치에 규칙 파일을 업로드합니다. 이 메서드는 쿼리 매개변수 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));

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

규칙 객체 만들기

AlgorithmRules JSON 파일이 업로드되면 customBiddingAlgorithms.rules.create 메서드로 맞춤 입찰 알고리즘 규칙 리소스를 만듭니다. 요청에 전달된 CustomBiddingAlgorithmRules 객체에는 rules 필드의 할당된 값으로 CustomBiddingAlgorithmRulesRef 객체만 포함되어야 합니다. 이렇게 하면 업로드된 AlgorithmRules JSON 파일이 새 규칙 리소스와 연결됩니다.

다음은 규칙 리소스를 만드는 방법의 예입니다.

자바

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

규칙 리소스를 만들면 Display & Video 360에서 노출 점수를 매기는데 규칙 집합을 사용할 수 있는지 확인하기 위해 규칙 집합을 처리합니다. 규칙 객체의 state 필드를 통해 이 처리의 상태를 가져옵니다. 새 규칙이 수락되면 맞춤 입찰 알고리즘이 규칙을 사용하여 노출 가치를 즉시 평가하기 시작합니다.

규칙이 거부되면 규칙 객체의 error에서 거부 사유를 가져옵니다. 거부된 경우 AlgorithmRules 객체를 업데이트하여 오류를 수정하고 규칙 참조 객체 검색부터 업로드 프로세스를 반복합니다.

맞춤 입찰 알고리즘 할당

맞춤 입찰 알고리즘을 만들고, 승인된 로직을 업로드하고, 필요한 요구사항을 충족하면 맞춤 입찰 알고리즘을 광고 항목 또는 게재 신청서의 입찰 전략에 할당할 수 있습니다.

BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO맞춤 입찰 알고리즘 ID를 각각 performanceGoalTypecustomBiddingAlgorithmId 필드에 할당하여 지출 극대화실적 목표 입찰 전략에서 맞춤 입찰 알고리즘을 사용할 수 있습니다. 입찰 전략에 따라 다른 입찰 매개변수를 사용할 수 있거나 사용해야 할 수도 있습니다.

다음은 지정된 맞춤 입찰 알고리즘으로 지출 최대화 입찰 전략을 사용하도록 광고 항목을 업데이트하는 방법의 예입니다.

자바

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