Skip to end of metadata
Go to start of metadata

Smart Leaves

This offering is currently in Alpha and available to a limited set of clients. For more information about the AppNexus Programmable Bidder and potential use cases that may apply to your business, reach out to your AppNexus representative.

This page assumes you are already familiar with The Bonsai Language and Bonsai Features.

You use the AppNexus Bonsai Language to write decision tree logic for custom predictive models. Each branch leads to a node, or "leaf", that evaluates to a simple numeric value representing the bid. Instead of evaluating to a single static value, smart leaves evaluate to a bid value that's dynamically modified based on a specified ad performance or delivery metric. Smart leaves also allow you to name individual leaves with an arbitrary string value. This is available in the standard feed to aid debugging and performance analysis.

Smart leaves are defined using a form of YAML, a human-readable data serialization format.


On This Page

compute() Syntax

You can use smart leaves to specify a static value or a bid calculated from an advertising metric, or to specify that no bid be made at all. If the value is calculated, it is determined by the compute expression, which uses the following format:

This is evaluated as the following equation:

That is, the calculated value is the input field times the multiplier, plus an offset. If the result is less than the minimum value, the minimum value is returned instead. If the result is greater than the maximum value, the maximum value is returned. To omit a calculation (multiplier, offset, minimum value, or maximum value), use an underscore (_) for the omitted value. If you omit to specify the multiplier value, the default value is 1. 

The bids calculated by the model are always expressed in the currency set on the advertiser, even if you have specified a different currency for the line item or campaign.

Smart Leaf Fields

Field

Field Type

Description

Default

value

text

The bid value. If the tree model is bid price, the bid is expressed in the currency set for this advertiser. If the tree model is bid modifier, the bid is a float or an integer. Possible values are:

  • compute(input_field, multiplier, offset, min_value, max_value)
  • no_bid
  • a static value (number)

Specifying compute calculates a value based on one of the input fields below. To omit a calculation (multiplier, offset, minimum value, or maximum value), use an underscore (_) for the omitted value. 

Do not use compute() expressions that evaluate to negative numbers or to zero (0). These values are not supported and may provide unexpected results.  It is best to specify no_bid explicitly.


 

leaf_name

string(7)

An optional string value that will be passed through to logs and reporting to aid with debugging and performance analysis. leaf_name may be up to seven ASCII (7-bit) characters and is not required to be unique.

Because leaf_name is a string, the value must be enclosed by double quotation marks (").

 
 

Input Fields for compute()

The values for the input fields are determined by AppNexus optimization

Field

Type

Description

estimated_iab_viewthrough_rate

float, integer

How likely this web display impression is to be measured as viewable by the IAB standard, from 0 to 1.  
predicted_iab_video_view_ratefloat, integer

How likely this video impression is to be measured as viewable by the IAB standard, from 0 to 1.

predicted_video_completion_ratefloat, integer

This feature is not yet available.

How likely the user is to watch this video impression fully, from 0 to 1. Non-video inventory will be 0.   

estimated_average_pricefloat, integerThe median price for this impression.
estimated_clearing_pricefloat, integerThe 80th percentile price for this impression. For more information, see Estimated Clear Price (customer login required).  
uniformfloat, integerA uniform random number between 0 and 1 (0 included, 1 excluded).

Using Segments as the Input for compute()

You can perform calculations using the value or age of the user in a first-party or third-party segment to determine a bid value. If the user is not present in the segment, no bid is made. Use the Segment Service to retrieve segment IDs.

Field

Type

Description

segment[ID].value

float, integer

The value of the user in a first-party or third-party segment. If the user is not present in the segment, no bid will be made.

ID is the segment ID.

segment[ID].agefloat, integer

The age of a user in a first-party or third-party segment. If the user is not present in the segment, no bid will be made.

ID is the segment ID.

Using Frequency or Recency as Inputs for compute()

You can perform calculations using frequency or recency to determine a bid value.

Field

Type

Description

OBJECT[ID].day_frequency

float, integer

The number of ads seen by a user on the current day. This can be determined for an advertiser, line item, or campaign. If no frequency data is found, the frequency is marked as zero (0).

OBJECT is advertiser, line_item, or campaign, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service to retrieve IDs.

 OBJECT[ID].lifetime_frequencyfloat, integer

The number of ads seen by a user over the lifetime of an advertiser, line item, campaign, or creative. If no frequency data is found, the frequency is marked as zero (0).

OBJECT is advertiser, line_item, or campaign, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service, to retrieve IDs.

OBJECT[ID].recencyfloat, integer

The number of minutes since the user has seen an ad. This can be determined for all ads under an advertiser, line item, or campaign, or for an individual creative. If no recency data is found, no bid will be made.

OBJECT is advertiser, line_item, campaign, or creative, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service to retrieve IDs.

 

Examples

Example bid price with estimated average price. One leaf has a minimum allowable bid price but no limit on the maximum.

 Example bid price tree with estimated clearing price, no bid, and static value smart leaves.

 Example bid modifier tree with estimated IAB viewthrough rate smart leaves. 

Example bid based on segment value

Example bid based on segment age

Example bid based on daily frequency

Example bid based on lifetime frequency

Example bid based on recency

Related Topics

  • No labels