Внедрение специальных ставок

Вы можете использовать API Display & Video 360 для управления пользовательскими настройками назначения ставок . Вы можете создавать собственные алгоритмы назначения ставок, загружать и проверять отдельные скрипты, а также назначать определенный алгоритм ресурсу в качестве стратегии назначения ставок.

This page describes how to create, update, and assign custom bidding algorithms with the Display & Video 360 API. Each section provides a code sample.

Создание пользовательского алгоритма назначения ставок

Объект CustomBiddingAlgorithm представляет собой отдельный алгоритм, который можно назначить позиции заказа для использования в ее стратегии назначения ставок. Этот объект содержит подробную информацию об алгоритме, такую ​​как customBiddingAlgorithmType , entityStatus и customBiddingAlgorithmState . Вы можете создавать объекты CustomBiddingScript в качестве дочерних ресурсов для использования алгоритмом.

Примечание: Данное руководство посвящено пользовательским алгоритмам назначения ставок на основе скриптов. Алгоритмы, созданные в Ads Data Hub или с помощью инструмента Goal Builder в Display & Video UI, можно получить и назначить, но ими нельзя полностью управлять.

Here's an example of how to create a script-based custom bidding algorithm:

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=algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

Управление доступом к алгоритмам

Custom bidding algorithms can be owned by a partner or an advertiser. Algorithms owned by a partner can be accessed and modified by that partner and any child advertisers listed in the sharedAdvertiserIds field. Algorithms owned by an advertiser can be accessed and modified by that advertiser and its parent partner, but cannot be shared with other advertisers.

Note: When creating a custom bidding algorithm, you must have read/write access to the partner or advertiser which you assign as the owner.

Если вы используете алгоритм только для одного рекламодателя, назначьте рекламодателя владельцем, используя поле advertiserId . В противном случае назначьте родительского партнера рекламодателей владельцем, используя поле partnerId , и предоставьте рекламодателям доступ, используя поле sharedAdvertiserIds .

Загрузите скрипт

После создания пользовательского алгоритма назначения ставок создайте скрипт для его использования. Пользовательские алгоритмы назначения ставок на основе скриптов используют предоставленные пользователем скрипты для оценки ценности показа. Примеры простых скриптов и список расширенных полей доступны в Справочном центре Display & Video 360 .

The following sections teach you how to add a new or updated script to a custom bidding algorithm.

Получить местоположение ресурса скрипта

Сначала получите доступное местоположение ресурса в разделе «Ресурс пользовательского алгоритма торгов» с помощью метода customBiddingAlgorithms.uploadScript . Этот запрос возвращает объект CustomBiddingScriptRef с именем ресурса . Вы можете загрузить свой скриптовый файл в местоположение, указанное в имени ресурса. Затем используйте объект ссылки на скрипт пользовательского алгоритма торгов для создания ресурса скрипта .

Here's an example of how to retrieve an available resource location:

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

Загрузите файл скрипта.

После получения информации о доступном местоположении ресурса загрузите свой скриптовый файл в это местоположение в системе Display & Video 360 с помощью метода media.upload . Этот метод поддерживает простую загрузку , для которой требуется параметр запроса uploadType=media .

Warning: Custom bidding scripts have a maximum file size of 7MB.

Here's an example of how to upload a script file given a retrieved custom bidding script reference object:

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

Создайте объект скрипта.

Once the script file is uploaded, create a custom bidding script resource with the customBiddingAlgorithms.scripts.create method. The CustomBiddingScript object passed in the request should only include the CustomBiddingScriptRef object as the assigned value of the script field. This associates the uploaded script file with the new script resource.

Внимание: если в загруженном вами файле скрипта обнаружена синтаксическая ошибка, ваш запрос customBiddingAlgorithms.scripts.create завершится неудачей и вернет подробную информацию об обнаруженной синтаксической ошибке. Чтобы загрузить исправленный файл скрипта, необходимо перезапустить этот процесс, получив новое местоположение ресурса скрипта .

Here's an example of how to create a script file:

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

После создания пользовательского скрипта для назначения ставок Display & Video 360 обрабатывает его, чтобы убедиться в возможности успешного использования для оценки показов. Состояние этой обработки можно получить через поле state объекта скрипта. После принятия нового скрипта алгоритм назначения ставок начинает использовать его для оценки значений показов. Это происходит немедленно, поэтому убедитесь, что вы действительно хотите обновить алгоритм, прежде чем создавать новый ресурс скрипта.

Назначьте собственный алгоритм назначения ставок.

После создания пользовательского алгоритма назначения ставок, загрузки утвержденного скрипта и выполнения необходимых требований вы можете назначить свой пользовательский алгоритм назначения ставок стратегии назначения ставок для позиции заказа или заказа на размещение товара.

В стратегиях назначения ставок для максимизации затрат и достижения целевых показателей производительности можно использовать пользовательские алгоритмы назначения ставок, присвоив полям performanceGoalType и customBiddingAlgorithmId значение BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO и идентификатор пользовательского алгоритма назначения ставок соответственно. В зависимости от стратегии назначения ставок могут быть доступны или необходимы другие параметры.

Here's an example of how to update a line item to use a maximize spend bid strategy with a given custom bidding algorithm:

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