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
• Available functions and signals
  • Functions
  • Signals
• Limitations

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:

• Floodlights: Learn more by seeing script examples using Floodlight data.
• Impression level data: Learn more by seeing script examples using impression level data.
• Google Analytics: Learn more by seeing script examples using data from Google Analytics.

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://www.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:

• Link Google Analytics 4 property to Display & Video 360

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