Custom bidding script reference

You can use the functions and signals described in this topic to create a custom bidding script that accurately represents the key performance indicators (KPIs) you want to improve toward when informing your custom bidding model.

Topics in this article

Syntax rules

You can improve impression values by using first-party data to inform your custom bidding scripts. Display & Video 360 supports first-party data from:

When you create a custom bidding script, you’ll use the following syntax rules:

  • Enclose all criteria in brackets [ ]
  • A comma , also represents "and"

Example

In this sample script, criteria1 returns true only if criteria_a and criteria_b are both true. While criteria2 returns true if criteria_a is true:
return aggregate_function([
([criteria_a, criteria_b], score), #criteria1
([criteria_a], score) #criteria2
])

Comments

You can use comments to add context to your script. For example, you can add comments to communicate the intent of your script.

You can use the following syntax for comments:

  • To add a single-line comment, use #.
  • To add a multi-line comment, enclose your comment in """ or '''.

Example

# This is an single line comment

"""

This is a multi-line comment

"""

'''

This is also a multi-line comment

'''

Operators

You can use the following operators in your script:

  • Arithmetic operators: + , -, *, / , %, **, //
  • Assignment operators: =, +=, -=, *=, /=, %=, **=, //=
  • Comparison operators: ==, !=, <, >, >=, <=
  • Logical operators: and, or, not
  • Membership operators: in, not in

Membership operators

You can use the in and not in membership operators in your script to check whether an element is in a field or not.

  • in: Returns true if the element is found in the field.
  • not in: Returns true if the element is not found in the field.

Example

Example
if 123 in channel_id: #checks if 123 is in the channel ID
return y

Comparison operators

You can use comparison operators to include or exclude an element from your model.

Example 1

Example 1
The following script excludes a date from your custom bidding model:

# Excluding date

if date == 20180711:

return None

You can identify impressions you want to exclude when training your custom bidding model by returning None. You can use a statement that returns None to identify impressions you want excluded when training your custom bidding model.

Example 2

Example 2

The following script excludes an ad type from your custom bidding model:

# Excluding slice (ad_type == 1 means VIDEO)

if ad_type != 1:

return None

Available functions and signals

The following is a list of functions you can use in your custom bidding script. The tables contain the following information:

  • Field: The function or signal name you use in the script.
  • Type: The output data type. Custom bidding supports the following data types:
    • Boolean: Contains a true or a false value.
    • Binary: Contains binary data.
    • Double: Contains a floating numerical value. For example, 1.0 .
    • List of integers: Contains a set of integers.
    • Integer: Contains positive or negative whole numbers. For example, 1 or -1.
    • String: Contains UTF-8 characters from a minimum length of 0 or more. For example, country_code outputs a string “US”.
  • Details: Contains more information and link to examples.

For more details, go to the Display & Video 360 API or download the Structured Data File (SDF).

Functions

Display & Video 360 custom bidding supports the following functions:

  • Aggregate: Functions that calculate aggregated values assigned to a criteria.
  • Casting: Functions that convert a variable to a specific data type to perform an operation.
  • Math: Functions that calculate values using advanced math.

These functions accept one or more signals to accurately represent your key performance indicators (KPIs) in your custom bidding script.

Category Function Type Details
Aggregate functions first_match_aggregate Double Returns the weight value assigned to the first criteria in the array that returns true.
max_aggregate Double Returns the highest weight value assigned to criteria that returns true.
sum_aggregate Double Returns the sum of all values assigned to all criteria that return true.
Casting functions

bool

bool(x)

Returns a boolean value: true or false.

float

float(x)

Converts a number or a string data type: Returns a floating point.

Example: float(1) returns as 1.0.

int

int(x)

Converts a number or a string data type and returns an integer.

Example: int(1.0) returns as 1.

str

str(object)

Converts a data type and returns a string.

Example: str(1) returns as “1”.
Math functions

log

log(x[, base])

With one argument: Returns the natural logarithm of x (to base e).

With two arguments: Returns the logarithm of x to the given base, calculated as log(x)/log(base).

 

Signals

Display & Video 360 custom bidding functions accept data from the following signal categories:

  • Dimension variables: Signals used in scripts that score based on a variable.
  • Conversions: Signals used in scripts that score based on a conversion outcome.
  • Google Analytics: Signals used in scripts that score based on data from Google Analytics 4.

Dimension variables

Category

Signal

Type

Details
General

advertiser_id

Integer

The advertiser identifier from Display & Video 360.

insertion_order_id

Integer

The insertion order identifier from Display & Video 360.

line_item_id

Integer

The line item identifier from Display & Video 360.
Date/Time

date

Integer

The date the impression was made.

Format: yyyymmdd

day_of_week

Integer

The numerical code for the day of the week the impression was made.

  • 0 for Sunday
  • 1 for Monday
  • 2 for Tuesday
  • 3 for Wednesday
  • 4 for Thursday
  • 5 for Friday
  • 6 for Saturday

hour_of_day

Integer

The hour the impression was made using browser's local time zone in the 24-hour format.

Valid inputs: 0 - 23

utc_date

Integer

The date the impression was made using coordinated universal time (UTC).

Format: yyyymmdd

utc_hour_of_day

Integer

The hour the impression was made using coordinated universal time (UTC) in 24-hour format.

Valid inputs: 0 - 23
Location

city_id

Integer

The city identifier.

You can generate the city_id using the Display & Video 360 API or by downloading the SDF metadata.

country_code

String

The country or region code.

You can download a pdf of the country or region code mappings as reference.

country_id

Integer

The country or region identifier.

You can download a pdf of the country or region ID mappings as reference.

dma_id

Integer

The designated market area (DMA) identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

zip_postal_code

String

The ZIP or postal code.

You can find a list of available ZIP or postal code using the Display & Video 360 API or by downloading the SDF metadata.
Creative (General)

ad_type

Integer

The numerical code representing the ad format:

  • 0 for display
  • 1 for video
  • 2 for audio

creative_height

Integer

Creative height in pixels.

Note: For display creatives only.

creative_id

Integer

The creative ID as it appears in Display & Video 360.

creative_width

Integer

Creative width in pixels.

Note: For display creatives only.
Computer System

browser_id

Integer

The browser identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

browser_timezone_offset_minutes

Integer

The difference in minutes between the active time zone on the browser and GMT-12.

Example:

1320 represents a browser time zone of GMT+10

device_type

Integer

The numerical code representing the device type:

  • 0 for desktop
  • 1 for unknown
  • 2 for smart phone
  • 3 for tablet
  • 4 for smart TV
  • 5 for connected TV
  • 6 for set top box
  • 7 for connected device

environment

Integer

The numerical code representing the serving environment for your ad.

  • 10 for web optimized for device
  • 11 for web not optimized for device
  • 12 for app

isp_id

Integer

The internet service provider (ISP) identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

language

String

The browser's language setting.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

mobile_make_id

Integer

The mobile make identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.
mobile_model_id Integer

The mobile model identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

net_speed

Integer

The numerical code representing the network speed detected when the impression was made:

  • 1 for broadband/4G (2mbps and faster)
  • 2 for dialup (56kbps and slower)
  • 3 for unknown connection speed
  • 4 for EDGE/2G (57kbps and faster)
  • 5 for UMTS/3G (384kbps and faster)
  • 6 for basic DSL (768kbps and faster)
  • 7 for HSDPA/3.5G (1.8mbps and faster)

operating_system_id

Integer

The operating system identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.
Serving (General)

ad_position

Integer

The numerical code representing the ad placement position:

  • 0 for unknown position
  • 1 for above the fold
  • 2 for below the fold

adx_page_categories

List of integers

The page category identifier.

You can view the full list category ID mappings on the AdWords API reference.

channels

List of integers

The channel identifier from Display & Video 360.

domain

String

Note: Domains aren't supported for CTV line items. For CTV line items use site_id.

The root domain name which consists of the domain name and the top-level domain.

Example: For the URL http://domain.com, the root domain would be domain.com.

exchange_id

Integer

The exchange identifier.

Download the custom bidding ID sheet (.xlsx format) for these IDs.

site_id

Integer

The site identifier.
Active View

active_view_measurable

boolean

Returns 1 for true if the impression was measurable by Active View when your ad was served.

Some factors may prevent impressions from being counted. If the impression was not measurable, returns 0 for false.

active_view_viewed

boolean

 Returns 1 for true once Active View detects that your ad has been viewed. Otherwise, returns 0 for false.
Event

click

boolean

Returns 1 for true if the ad was clicked. Otherwise, returns 0 for false.

time_on_screen_seconds

Integer

The time the ad was on screen in seconds.
Video

audible

boolean

Note: Supported for real-time bidding (RTB) videos only

Returns 1 for true if the video’s sound was ON when viewed. Otherwise, returns 0 for false.

completed_in_view_audible

boolean

Note: Supported for real-time bidding (RTB) videos only

Returns 1 for true if the video had the sound ON when viewed. Otherwise, returns 0 for false.

video_completed

boolean

Note: Only applies to video ad types. Non-video impressions won’t be labeled.

Returns 1 for true if the video was completed. Otherwise, returns 0 for false.

video_player_height_start

Integer

The video player height at first frame in pixels.

video_player_size

Integer

The numerical code representing the target video inventory based on the video player size.

  • 0 for unknown
  • 1 for small
  • 2 for large
  • 3 for high definition (HD)

To learn more, go to Video Targeting.

video_player_width_start

Integer

The video player width at first frame in pixels.

video_resized

Binary

Returns 1 for true if the video player was resized during playback. Otherwise, returns 0 for false.

viewable_on_complete

boolean

Note: Supported for real-time bidding (RTB) videos only.

Returns 1 for true if the video was viewed on completion. Otherwise, returns 0 for false.

  video_content_duration_bucket Integer

Note: Only applies to video ad types. Non-video impressions won’t be labeled.

The numerical code that represents the video’s bucket,which is used to categorize videos based on their length. The upper bound range is exclusive. 

Example

For videos that have a duration of 1 minute:

  • They’re categorized under the “1 to 5 minutes” bucket.
  • They are not under the “0-1 minute” bucket since this bucket excludes videos that are 1 minute or over.
  • 0 for unknown
  • 1 for 0 to 1 minute
  • 2 for 1 to 5 minutes
  • 3 for 5 to 15 minutes
  • 4 for 15 to 30 minutes
  • 5 for 30 to 60 minutes
  • 7 for over 60 minutes
  video_genre_ids List of integers

Note: Only applies to video ad types. Non-video impressions won’t be labeled.

Represents a list of video genre IDs for targeting ads based on related groups of audio and video inventory.

Learn more about Genre targeting.
  video_livestream boolean

Note: Only applies to video ad types. Non-video impressions won’t be labeled.

Returns true if the video is a livestream. Otherwise returns false.

Conversions

Category

Signal

Type

Details
Conversion signals

total_conversion_count(Floodlight Activity ID, Attribution Model ID)

Double

The total number of conversion events for ID pair. Use your own model, or enter 0 for the model ID to use last-touch attribution.

total_conversion_value(
Floodlight Activity ID, Attribution Model ID)

Double

Takes the revenue value from activities tracked by Floodlight Sales tags. Use your own model, or enter 0 for the model ID to use last-touch attribution.

total_conversion_quantity( FloodlightActivity ID, Attribution Model ID)

Double

The total quantity of conversions attributed to the given ID pair. Use your own model, or enter 0 for the model ID to use last-touch attribution.

conversion_custom_variable(
Floodlight Activity ID, Attribution Model ID, Custom Variable Index)

String

The string value of the custom variable for the latest attributed conversion for the impression. Otherwise returns None (if there's no conversion or the value isn't set). Use your own model, or enter 0 for the model ID to use last-touch attribution.

conversion_variable_num(
FloodlightActivity ID, Attribution Model ID)

Integer

Gets the latest conversion with positive credit to get the “num” Floodlight variable if it exists where count_micros is positive. Otherwise returns None.

conversion_variable_ord(Floodlight Activity ID, Attribution Model ID)

String

Gets the latest conversion with positive credit to get the “ord” Floodlight variable if it exists where count_micros is positive. Otherwise returns None.

Video genre mappings

Genre ID

Genre Name

2

/Adult

3

/Arts & Entertainment

317

/Arts & Entertainment/Comics & Animation/Anime & Manga

319

/Arts & Entertainment/Comics & Animation/Cartoons

1108

/Arts & Entertainment/Entertainment Industry/Film & TV Industry/Film & TV Awards

569

/Arts & Entertainment/Events & Listings

1273

/Arts & Entertainment/Events & Listings/Live Sporting Events

895

/Arts & Entertainment/Humor/Live Comedy

1097

/Arts & Entertainment/Movies/Action & Adventure Films

1099

/Arts & Entertainment/Movies/Action & Adventure Films/Western Films

1095

/Arts & Entertainment/Movies/Comedy Films

615

/Arts & Entertainment/Movies/Horror Films

1105

/Arts & Entertainment/Movies/Musical Films

1310

/Arts & Entertainment/Movies/Romance Films

616

/Arts & Entertainment/Movies/Science Fiction & Fantasy Films

1096

/Arts & Entertainment/Movies/Thriller, Crime & Mystery Films

35

/Arts & Entertainment/Music & Audio

449

/Arts & Entertainment/Offbeat/Occult & Paranormal

23

/Arts & Entertainment/Performing Arts

894

/Arts & Entertainment/Performing Arts/Acting & Theater

581

/Arts & Entertainment/Performing Arts/Dance

1185

/Arts & Entertainment/Performing Arts/Opera

358

/Arts & Entertainment/TV & Video/TV Shows & Programs

1047

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Comedies

1411

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Documentary & Nonfiction

1193

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Dramas

1111

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Dramas/TV Crime & Legal Shows

357

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Dramas/TV Soap Operas

1110

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Family-Oriented Shows

1050

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Game Shows

1049

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Reality Shows

1112

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Sci-Fi & Fantasy Shows

1410

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Talent & Variety Shows

1048

/Arts & Entertainment/TV & Video/TV Shows & Programs/TV Talk Shows

24

/Arts & Entertainment/Visual Art & Design

47

/Autos & Vehicles

1191

/Autos & Vehicles/Bicycles & Accessories

1405

/Autos & Vehicles/Bicycles & Accessories/Mountain Bikes

273

/Autos & Vehicles/Motor Vehicles (By Type)/Motorcycles

148

/Autos & Vehicles/Motor Vehicles (By Type)/Off-Road Vehicles

185

/Beauty & Fitness/Fashion & Style

94

/Beauty & Fitness/Fitness

241

/Beauty & Fitness/Fitness/Bodybuilding

1418

/Beauty & Fitness/Fitness/Fitness Instruction & Personal Training

46

/Business & Industrial/Agriculture & Forestry

5

/Computers & Electronics

122

/Food & Drink/Cooking & Recipes

39

/Games/Card Games

924

/Games/Card Games/Poker & Casino Games

924

/Games/Card Games/Poker & Casino Games

41

/Games/Computer & Video Games

698

/Games/Gambling/Sports Betting/Horse & Dog Racing

939

/Games/Table Games/Billiards

940

/Games/Table Games/Table Tennis

45

/Health

284

/Hobbies & Leisure/Crafts

688

/Hobbies & Leisure/Outdoors

462

/Hobbies & Leisure/Outdoors/Fishing

461

/Hobbies & Leisure/Outdoors/Hunting & Shooting

461

/Hobbies & Leisure/Outdoors/Hunting & Shooting

461

/Hobbies & Leisure/Outdoors/Hunting & Shooting

999

/Hobbies & Leisure/Recreational Aviation

678

/Hobbies & Leisure/Special Occasions/Holidays & Seasonal Events

459

/Hobbies & Leisure/Water Activities/Boating

11

/Home & Garden

158

/Home & Garden/Home Improvement

966

/Law & Government/Government/State & Local Government

75

/Law & Government/Legal

366

/Law & Government/Military

16

/News

784

/News/Business News

396

/News/Politics

1201

/News/Politics/Opinion & Commentary

1077

/News/Sports News

785

/News/Technology News

63

/News/Weather

113

/People & Society/Ethnic & Identity Groups/Lesbian, Gay, Bisexual & Transgender

58

/People & Society/Family & Relationships/Family/Parenting

59

/People & Society/Religion & Belief

870

/People & Society/Self-Help & Motivational

57

/People & Society/Social Issues & Advocacy/Charity & Philanthropy

82

/People & Society/Social Issues & Advocacy/Green Living & Environmental Issues

886

/Pets & Animals/Pets/Dogs

888

/Pets & Animals/Pets/Horses

119

/Pets & Animals/Wildlife

119

/Pets & Animals/Wildlife

690

/Reference/General Reference/Biographies & Quotations

694

/Reference/General Reference/How-To, DIY & Expert Content

433

/Reference/Humanities/History

1288

/Reference/Humanities/History/Military History

174

/Science

18

/Shopping

64

/Shopping/Antiques & Collectibles

292

/Shopping/Auctions

69

/Shopping/Consumer Resources

1666

/Sports/Animal Sports

568

/Sports/Animal Sports/Equestrian

515

/Sports/Combat Sports/Boxing

516

/Sports/Combat Sports/Martial Arts

1674

/Sports/Combat Sports/Martial Arts/Mixed Martial Arts

512

/Sports/Combat Sports/Wrestling

1681

/Sports/Combat Sports/Wrestling/Professional Wrestling

554

/Sports/Extreme Sports

1206

/Sports/Extreme Sports/Drag & Street Racing

1000

/Sports/Individual Sports

1016

/Sports/Individual Sports/Bowling

458

/Sports/Individual Sports/Cycling

261

/Sports/Individual Sports/Golf

519

/Sports/Individual Sports/Gymnastics

262

/Sports/Individual Sports/Racquet Sports

1376

/Sports/Individual Sports/Racquet Sports/Tennis

541

/Sports/Individual Sports/Running & Walking

1126

/Sports/Individual Sports/Skate Sports

518

/Sports/Individual Sports/Track & Field

513

/Sports/International Sports Competitions/Olympics

180

/Sports/Motor Sports

1595

/Sports/Motor Sports/Auto Racing

1596

/Sports/Motor Sports/Motorcycle Racing

1001

/Sports/Team Sports

258

/Sports/Team Sports/American Football

259

/Sports/Team Sports/Baseball

264

/Sports/Team Sports/Basketball

534

/Sports/Team Sports/Cheerleading

296

/Sports/Team Sports/Cricket

1017

/Sports/Team Sports/Handball

260

/Sports/Team Sports/Hockey

517

/Sports/Team Sports/Rugby

294

/Sports/Team Sports/Soccer

699

/Sports/Team Sports/Volleyball

118

/Sports/Water Sports

1593

/Sports/Water Sports/Surfing

1594

/Sports/Water Sports/Swimming

265

/Sports/Winter Sports

1149

/Sports/Winter Sports/Ice Skating

1148

/Sports/Winter Sports/Skiing & Snowboarding

67

/Travel & Transportation

Google Analytics

Important
To use Google Analytics 4 conversions to inform your custom bidding model, you'll need to share conversion data. Learn more about how to:
Category Signal Type Details
Google Analytics 4

has_ga4_conversions(
property_id, conversion_event_name)

Boolean

 Returns true if a given impression has at least one conversion with a property ID and conversion event attributed. Otherwise returns false.

ga4_conversions_count(
property_id, conversion_event_name)

Integer

 Returns the number of conversions with a property ID and conversion event attributed to the given impression.

ga4_conversions_max_value(
property_id,conversion_event_name))*

Double

Returns the highest value assigned to a conversion with a property ID and conversion event attributed to the given impression.

Returns 0 if the highest conversion value is 0 or if no conversions are attributed.

ga4_conversions_max_value_usd(
property_id, conversion_event_name)

Double

Note: For Google Analytics 4 accounts using USD currency.

Returns the highest value assigned to a conversion with a property ID and conversion ID attributed to the given impression

Returns 0 if the highest conversion value is 0 or if no conversions are attributed.

ga4_conversions_total_value(GA4 property ID, conversion_event_name)

 Double

Returns the sum of the weight values assigned to conversions with a property ID and conversion event attributed to the given impression.

Returns 0 if the highest conversion value is 0 or if no conversions are attributed.

ga4_conversions_total_value_usd(
property_id, conversion_event_name)

 Double

Note: For Google Analytics 4 accounts using USD currency.

Returns the sum of the weight values assigned to conversions with a property ID and conversion event attributed to the given impression.

Returns 0 if the highest conversion value is 0 or if no conversions are attributed.

Limitations

The following aren’t supported in custom bidding scripts:

  • Passing named arguments: For example, func(arg1 = “abc”, arg2 = “def”)
  • Subscripts and slices: For example, userlists[1:3]
  • Referencing attributes: For example, domain.length
  • Variable and function names can come from a predefined set
  • Recursion
  • Advanced custom variable assignments:
    • multi assignments
    • augmented assignments
    • annotated assignments
Example

The following are samples of unsupported syntax in custom variable assignments

_a, _b = 1, 2

_a, _b = _b, _a

_a = _b = 2

_idx += 1

  • Unsupported keywords:
    • global, nonlocal and exec keywords
    • class and class definitions
    • def and function definitions
    • Import and import from keywords
    • lambda and lambdas support
    • break
    • continue
    • yield
    • raise
    • assert
    • try
    • finally
    • except
    • async
    • await
    • del
    • Pass
    • ellipsis
  • Unsupported loops:
    • for and while loops.
  • Unsupported operators:
    • * and ** when used in non-arithmetic statements.
    • << and >> shift operators.
    • Bit operators
    • @ decorators.
    • is, not is identity operators

Was this helpful?

How can we improve it?

Need more help?

Try these next steps:

Contact us Tell us more and we’ll help you get there
true
2024 Privacy Readiness guide

Prepare for a world without third-party cookies and unlock the AI
opportunity by adopting the right durable audience and measurement
solutions.
Start Today

Search
Clear search
Close search
Google apps
Main menu
17234895356832039398
true
Search Help Center
true
true
true
true
true
69621
true
false