Create and use a custom bidding script

Create your script

Note:

• If you have partner-level access: You can create the script at either the partner or advertiser level, allowing the algorithm to be shared with multiple advertisers.
• If you only have advertiser access: You can only create scripts at the advertiser level. The corresponding algorithm will only be associated with the advertiser it's created in. 

1. Navigate to your Partner or Advertiser.
2. Expand Resources  Custom Bidding in the left menu.
3. Choose New Algorithm.
4. Enter a name for your custom bid.
5. Select your objective. The objective you choose determines which rules can be selected. Choose Custom then select Use script to define which impressions are most valuable for your campaign.

Write your script

To learn more about custom bidding script syntax and for samples, go to Custom bidding script reference.

You can search for linked attributes when writing a custom bidding script:

1. In the New script window, expand Script tools.
   Note: If you're creating your script at the partner level, next Choose an advertiser. 
2. Choose one of the following categories:
   1. Attribution models
   2. Floodlight activities
   3. U-Variables
3. (Optional) Use the search bar to search for a specific attribute.
4. Select the copy and paste icon next to the attribute.
5. Paste the metadata to your script.
6. (Optional) Select Check syntax to review syntax issues with your script.

Test your script

Before you create your custom bidding script, you can test your algorithm to generate a chart that shows the distribution of scores for your chosen impressions. You can use this data to test your script's performance and check if it performs as expected. 

Sample scenario

For example: 

You can test a weighted conversion script to check the potential outcome of using different weight values and revise the script to optimize your results.

Note: The chart displays no more than 10 columns. The sample impressions are grouped together if you test more than 10 potential outcomes.

To test your script:

1. From the drop-down menu, choose an advertiser.
   1. You must link an advertiser to the algorithm to see them in the list. 
   2. The advertiser must meet custom bidding data requirements. 
2. Under Sample type, choose how impressions are sampled: 
   • All impressions: Recommended to understand overall expected distribution of impression values.
   • Only impressions with clicks: Useful if clicks are central to the script.
   • Only impressions with conversions: Useful if conversions central to the script. This sample includes all conversion events in your advertiser and will be based off the default attribution model 

You can test your algorithm using a random sample of 10 000 impressions from eligible impressions. You can review the following results:

• The number of impressions in the sample: The number of sampled impressions included in the results.
• Impression value/cost: The impression value/cost for the sampled impressions.
  Note: Included in the results only when using all impressions as the sample type.
• Percentage of execution errors: The percentage of sampled impressions that returned an error after testing the script.
• Percentage impressions scored: The percentage of sampled impressions successfully scored.
• Percentage of positive impressions scored: The percentage of sampled impressions  successfully scored with a score over 0.

You can download a .csv file to view the details of individual values in the results. 

When you're done, choose Create.

After you create your script, it requires time to process. It may take 20 mins before it's available. When it's available, you can view your script from the script list.

Get started with a campaign

Your algorithm may take 1–3 days to train after you have saved a script that meets the data requirements. Once your model is ready, you will see Yes next to Is the model ready? in the model's Summary tab.

1. (Recommended) Set up an A/B experiment. Your custom bidding algorithm can be the experiment that you test against a control. If your custom bidding model isn't ready yet, you can use a placeholder bid strategy and come back later to update.
2. In the Insertion Order Details tab for each of your custom bidding test insertion orders, you can select: Optimization  Automate bid & budget at insertion order level Custom bidding ​​  [your custom bidding algorithm]  
   1. The system will automatically adjust the insertion order's bids for the highest impression value (determined by your algorithm). Spending your full budget will be prioritized.
3. Alternatively, In the Line Item Details tab for each of your custom bidding test line items, you can select: Bid strategy   Automated Bidding  Custom bidding ​​ [your custom bidding algorithm]
   1. The system can automatically adjust your line item's bids for: 
      1. The highest impression value (determined by your algorithm). Spending your full budget will be prioritized.
      2. A target value or cost that you set.