Use * syntax for faster search

Table of Contents


Overview

Bid Models enable building a more complex and custom bidding strategy. These models are built offline as a data table, and then uploaded to the platform. The data table must define specific targeting combinations and expressions, and their associated bids or bid modifiers. Once applied to campaigns, they are used to make bidding decisions in real time. Bid models are a flexible way to create more complex bidding strategies than bid modifiers, without the use of a custom bidding agent. An example use case for building a bid model can be based on data from the DSP logs (wins, conversions, etc). The model could use a combination of bid request fields (city, inventory source, etc.) and determine an associated bid or bid multiplier.

To see which fields are supported in bid models, please see Github.

These three steps must be completed in order to create a bid model:

  1. Create the data model offline

  2. Upload the bid model to S3

    Delivery Models and Bid Models can be used on the same line item. A Delivery Model controls the delivery, while a Bid Model controls the bid price. However, Deliver Models and Modifiers can not be used on the same line item. For upload instructions, click here.

  3. Upload the bid model to Buzz

For more information on what fields can be used in a bid model, please see Bid and Delivery Models Fields.


How To Create a Bid Model Offline

  1. The first step is to create the model offline. This can be done by training a model using the DSP log data, or a different first/third party data source, or any other modeling technique. The bid model consists of 2 files: the manifest file and the prediction file.

  2. Creating the Prediction File: Prediction files are the table that contains the bid model. Prediction files should be kept to a maximum size of 25MB each, and an accumulative maximum size of 100MB per Bid Model, to optimize loading performance and should be in the below format:
    • pipe-delimited ("|") text files
    • no compression
    • first row of each file contains headers
    • at least one bid request key field
    • a required field called "value", which represents either the CPM Bid or Bid Multiplier for that row
    • null values should be left blank
    • an asterisk (*) can optionally be used to match any value (note: a maximum of three wildcard fields are supported)
    • max file size = 25MB
    • Prediction files can only include values that are bids or multipliers

  3. Creating the Manifest File: The manifest file is a .json file with the below format:
  • The model predictions object includes a list of S3 paths to all prediction files (previous step) associated with this model version. The files live under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/

  • The metadata.fields object contains a list of feature fields that are included in this model version and, optionally, the fields which contain wildcards. 

  • A sample manifest can be downloaded here.



How To Create a Bid Model in UI

The updated versions of the bid model table can be uploaded to the same bid model object in Buzz, and the most recent upload version will be used unless otherwise specified.

  1. From Trafficking > Models, click New Model. If creating the model via API, instructions can be found here. 

  2. Complete the following fields in the Overview:
    *Required

    Model IDAn ID associated to the model generated after creation.
    Model Name*Desired name for the Model.
    Value Type*
    • CPM Bid
    • Multiplier
    ActiveActive or Inactive.
    Alternative IDAny number or string. Used to map this object to an object in an outside system.
    NotesAny desired notes about this model.


  3. Click Save & Continue.

  4. The Model Versions screen will appear to associate a model version with this model. Enter the Manifest S3 Path (location of the pre-loaded manifest file) and a Model Version Name, then click Add Version.

  5. The model will automatically go into PENDING status. This status signifies the version is being validated and prepared to receive traffic. The Status will subsequently change to LIVE or FAILED. One option to check if bid models are working is to use the real time bidding stats graph in the line item overview. This graph does not tell you exactly what you are bidding in every auction, but if your default bid is very low (i.e. $0.01) and that’s all the line item is bidding (or not bidding at all), then it is likely the bid model is not working well. In this case, please make sure your prediction values are in a reasonable range of CPM/bid multiplier.

    See below for each available status and what they mean:

    • Pending: The bid model has just been uploaded and is being validated and prepared to handle traffic.

    • Available: The bid model has been validated and is ready to receive traffic, though it's not yet in active use.

    • New: A new version of the bid model has been created but not yet validated or loaded for serving traffic.

    • Live: The bid model is loaded and actively serving traffic, or ready to serve.

    • Failed: There was an issue during the bid model upload. A red caret icon will appear, which you can click to view the error details.

    Additionally, status' can be found here.

  6. The final step is to associate the bid model with a line item. Under the Modifiers tab during line item creation, an existing bid model may be selected.

    Matching Bid Model’s values will be multiplied with Bid Modifier terms.

  7. Click Save & Continue to apply the model to the line item.

Bid Model Logic

The line item will bid on all traffic, even if it doesn't match the specific bid model combinations. However, the bid for traffic that matches the bid model combinations will be selected in the following order:

To avoid spending on traffic not in the bid model, it is recommended to set a base bid on the overview screen of a line item as $0.

  1. The system will attempt to get the bid from the bid model based on the data combinations.

  2. If the bid request matches one of the combinations, and the returned value is less than or equal to the max bid, the system will use that bid.

  3. If the bid request matches one of the combinations, and the returned value is greater than the max bid, the system will use the max bid.

  4. If the bid request does not match one of the combinations but does match line item targeting, the system will use the default for the strategy.

Using a Wildcard with Bid Models

To use wildcards, the following changes need to be made to the model:

In the manifest file, fields that contain wildcards (up to three fields) must be specified. An example manifest file can be seen in the provided GitHub link. In the prediction files, an asterisk (*) should be entered in any cell that should match any value on the bid request. If multiple rows in the bid model match, the row with the fewest wildcards will be used. If multiple rows with the same number of wildcards match, the first will be used.


Bid Model Interaction with Bid Modifier

The output of the bid model will be multiplied against the output of the bid modifiers

  • No labels
Provide feedback on this article
You are evaluating Refined.