Overview

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. Delivery Modifiers allocate spending to specific inventory in real-time based on defined rules. For instance, a Delivery 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. A Delivery Modifier can be linked to one or more Line-Items or Campaigns. At the Campaign level, the Delivery Modifier applies to all associated Line-Items that do not have their own Delivery Modifiers.

How It Works

Delivery Modifiers consist of multiple Terms (1 to 100), each specifying a portion of the budget for different inventory pools. The Weight of each Term determines its budget share relative to others.

• Budget Caps: Limit the spending on each Term, providing control but risking under delivery if inventory is limited.
• Pacemaker: Beeswax’s pacing system manages the pacing and budget allocation for each Delivery Modifier Term. Terms are paced based on the Line-Item’s pacing settings (Daily, Lifetime, or Flight) and can be controlled by Spend or Impressions.

Term Weighting:

• Maximum weight value: 100
• Minimum weight value: 0.01
• Minimum fallback weight: 0

Pacing Rules:

• Line-Item pacing overrides Delivery Modifier Term pacing.
• If a Term under-delivers, its unspent budget is redistributed to other Terms to maintain schedule.
• Reallocation occurs within 12-24 hours if inventory becomes available.
• Budget allocations and bid probabilities are recalculated hourly and approximately every 60 seconds, respectively.

Term Priority:

• Priority determines which Term uses the impression in an RTB auction if multiple Terms match. The Term with the highest priority counts the impression towards its budget unless it is pacing. In such cases, the next highest priority Term's budget will be used.
• Priority affects impression allocation but does not influence budget reallocation across Terms. Fallback Weight may occasionally overlap with active Modifier Terms.

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.