Overview

Like delivery modifiers, delivery models create the ability to finely control the distribution of programmatic ads separately from the prices that will be bid for those ads. This unique capability dynamically shifts the budget according to a set of instructions defined during the creation of the model while ensuring full delivery. A delivery model can be uploaded and used in place of modifier terms that are input directly into the UI. The delivery model will contain a collection of delivery modifier terms.

Delivery models and modifiers allocate spending to specific inventory in real-time based on defined rules. For instance, a delivery model or modifier can be set to allocate 50% of the budget to a particular Domain List, 25% to a specific Publisher, and 25% to other inventory that meets targeting criteria. Delivery models and modifiers can be linked to one or more Line-Items or Campaigns. At the Campaign level, the delivery model or modifier applies to all associated Line-Items that do not have their own existing delivery model or modifier. Both delivery models and modifiers can be used with a custom bidding agent, but pacing must be enabled on the custom bidding strategy. If pacing is not available as an option, the account team can be contacted to have it set up.

How It Works

Delivery Model Example Distribution

A Delivery Model might consist of the following criteria:

This model dynamically reallocates the budget to meet the overall target, ensuring the ad spend is optimized based on available inventory. If inventory from higher-priority sources (e.g., O&O) is unavailable, the budget is reallocated to secondary sources (e.g., open exchange).

Budget Allocation and Pacing

Beeswax’s pacing system ensures that each term within the Delivery Model is paced according to the Line-Item’s pacing settings (Daily, Lifetime, or Flight). The system recalculates budget allocations and bid probabilities regularly to ensure full delivery of the total budget.

• Pacing Rules: The pacing of each Term is based on the line item's pacing settings. If a Term under-delivers, its unspent budget is redistributed to other Terms within the Delivery Model to maintain delivery schedules.
• Example of Delivery Model Reallocation: If the O&O inventory is insufficient to deliver the required impressions, the budget is automatically reallocated to other inventory sources (e.g., Other Deals or Open Exchange) based on their assigned weight.

Upload and Create Delivery Models

1.  The first step is to create the model offline.

This can be done by training a model using Beeswax log data, or a different first/third party data source, or any other modeling technique. The delivery 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 delivery model. Prediction files should be kept to a maximum of 100 rows 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 relative delivery weight for that row, from 0 to 1000
• 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

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. 

How to Upload a Delivery Model:

1. In order to use a delivery model, the files must be uploaded to S3. Please reach out to your support alias if you are not set up for this and request access. Instructions on how to access S3 buckets for upload can be found here.
   
   
2. Once access is granted, follow the API documentation to upload the manifest and data files to s3://beeswax-data-<region>/bid_models/<buzz key>/. Regardless of which region you upload the files to, the data will be replicated to each region in which your bidder is live.
   
   
3. File structure is largely flexible, but please note that manifest files must be under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/customer_manifests/.

How to Create a Delivery Model

The final step to creating and using delivery models is to create the delivery model in the UI. API instructions can be found here

1. Select Create > Model.
   
   

2. Enter the following fields in the Overview screen.
   *Required

   Field Name	Description
   Model ID	An ID associated to the model generated after creation.
   Model Name*	Desired name for the Model.
   Value Type*	Select Budget Weight for a delivery model.
   Alternative ID	Any number or string. Used to map this object to an object in an outside system.
   Active	Active or Inactive.
   Notes	Any desired notes about this model.

   Click Save & Continue
   
   

3. From the Model Versions screen, create the first Delivery Model version by entering the Manifest S3 Path (location of the pre-loaded manifest file) and Model Version Name.
   
   
4. The model will automatically go into ‘PENDING’ status. This status signifies the version is being validated and prepared to receive traffic.
   
   
5. The final step is to associate the delivery model with a line item. Under the Modifiers tab during line item creation, an existing bid model may be selected.