Release Notes for Microsoft Advertising Scripts

For information about changes that were included with each release, see the following sections.

March 31, 2021

Average position is no longer available in Microsoft Advertising.

The getAveragePosition method is removed from the Stats object.

The AveragePosition column is removed as a condition with the following selectors.

March 5, 2021

Added support for absolute top impression rate and top impression rate as a percentage of your total impressions.

Added the following methods to the Stats object.

Added AbsoluteTopImpressionRate and TopImpressionRate as possible columns that you may specify with the following selectors.

February 23, 2021

Added support for responsive search ads.

  • Added the ResponsiveSearchAd object, which defines a responsive search ad.

  • Added the ResponsiveSearchAdBuilder object, which you use to add an expanded text ad to the ad group.

  • Added the responsiveSearchAdBuilder method to the AdBuilderSpace object. If you want to build a responsive search ad, you'd call the responsiveSearchAdBuilder method to get the ResponsiveSearchAdBuilder object.

  • Added the AdTextAsset object, which contains properties for responsive search ad descriptions and headlines.

  • Added the responsiveSearchAd method to the AdTypeSpace object, which contains the methods used to test whether an ad is of the specified type. For example, to test whether the ad is a responsive search ad.

  • Added the responsiveSearchAd method to the AdViewSpace object, which is used to cast an ad to a specific type. For example, cast the base ad object to a responsive search ad.

January 21, 2021

Added support for targeted and excluded audiences.

This change added following objects:

December 10, 2020

Added support for targeted and excluded locations.

This change added following objects:

Added the ExcludedLocationOperation object, which you use to determine whether Scripts successfully added the excluded location.

Added the TargetedLocationOperation object, which you use to determine whether Scripts successfully added the targeted location.

March 31, 2020

Added the following objects that derive from ProductGroup:

Added the following methods to ProductGroup:

  • asChannel()
  • asChannelExclusivity()

Removed calls to Logger.Log() from some script examples. Because logging is an expensive call in terms of performance, guidance is to use logging sparingly and probably not within high volume loops except to provide notification of issues. Also, instead of using multiple Log() calls to write multiple lines, use a single call and include newline characters ('\n').

January 16, 2020

Added support for product groups. The support is limited to enumerating product groups and updating their bids. For examples, see script examples.

This change added following objects:

Added the following objects that derive from ProductGroup:

Added the following methods to AdsApp:

Added the following methods to AdGroup:

Added the following method to Cammpaign:

Added CampaignType as a possible column to the AdGroupSelector object's withCondition method.

Added Type as a possible column to the CampaignSelector object's withCondition method.

October 18, 2019

Added the Id column to the withCondition() method of the AdSelector and KeywordSelector objects. You can use this column to check for ads or keywords with IDs greater than the specified ID (for example, withCondition('Id > 1234')).

Added the Check ad and keyword URLs script solution, which you can use to check whether ads or keywords in your accounts contain broken URLs.

October 7, 2019

Added CombinedApprovalStatus as a possible column that you may specify when selecting keywords. For example, you can use the column to select keywords that have been disapproved for editorial reasons. See KeywordSelector.withCondition.

September 13, 2019

Added the ExecutionInfo object, which contains information about the environment in which the script is currently executing. For example, if the script is running in preview mode or the amount of time the script is allowed to continue executing.

Added the getExecutionInfo method to the AdsApp object. Use this method to get the ExecutionInfo object.

Added the getRemainingDailyQuota method to the UrlFetchApp object. Use this method to get the remaining number of fetch() calls that the user can make today.

August 20, 2019

The following is a documentation-only change.

  • Clarified that Scripts uses the account's time zone as elsewhere in Microsoft Advertising. For example, if you use a selector's .forDateRange() method, Scripts uses the account's time zone to determine the data to return. Read more
  • Clarified that data latency in Scripts is the same as elsewhere in Microsoft Advertising. Read more

The following are non-breaking API changes to support labels.

  • Added the following methods to the AdsApp object.
    • createLabel — creates a label
    • labels — gets a selector used to filter the list of labels in this account
  • Added the following label-related objects.
    • Label — defines a label.
    • LabelSelector — gets a list of labels for the account.
    • LabelIterator — iterates over a list of labels that matched the selector's selection criteria.
  • Added the following methods to the Keyword object.
    • applyLabel — applies the label to the keyword
    • labels — gets a selector used to filter the list of labels applied to this keyword
    • removeLabel — removes the label from this keyword
  • Added the LabelNames column to the KeywordSelector object's withCondition method.
  • Added the following methods to the Ad and ExpandedTextAd objects.
    • applyLabel — applies the label to the ad
    • labels — gets a selector used to filter the list of labels applied to this ad
    • removeLabel — removes the label from this ad
  • Added the LabelNames column to the AdSelector object's withCondition method.
  • Added the following methods to the AdGroup object.
    • applyLabel — applies the label to the ad group
    • labels — gets a selector used to filter the list of labels applied to this ad group
    • removeLabel — removes the label from this ad group
  • Added the LabelNames column to the AdGroupSelector object's withCondition method.
  • Added the following methods to the Campaign object.
    • applyLabel — applies the label to the campaign
    • labels — gets a selector used to filter the list of labels applied to this campaign
    • removeLabel — removes the label from this campaign
  • Added the LabelNames column to the CampaignSelector object's withCondition method.

April 30, 2019

The following is a documentation-only change.

  • Bing Ads is now Microsoft Advertising. Our new name reflects how we're growing our advertising solutions to help you reach more customers. All references to the Bing Ads platform in the documentation were changed to Microsoft Advertising.

The following are non-breaking API changes to support the brand update.

  • Added the AdsApp object. Scripts will continue to support the BingAdsApp object for backwards compatibility; however, you're encouraged to update your scripts to use the new objects at your earliest convenience.

March 25, 2019

The following is a documentation-only change.

February 11, 2019

Added the following methods to the BingAdsAccountStats object.

Note

If you use the getClickConversionRate() and getConvertedClicks() methods, you should update your scripts to use the getConversionRate() and getConversions() methods instead.

Added the following methods to the Stats object.

Note

If you use the getClickConversionRate() and getConvertedClicks() methods, you should update your scripts to use the getConversionRate() and getConversions() methods instead.

November 27, 2018

The following is a documentation-only change.

November 7, 2018

The following is a documentation-only change.

  • Changed the preview note to indicate that Scripts is now in open beta and available to all Microsoft Advertising users.

October 4, 2018

This is the Beta release of Scripts. For information about participating in the program, please contact your account manager. The Scripts classes and documentation are subject to change.

Added the following objects to support URL fetch.

  • Added the UrlFetchApp object, which is the top-level object that you use to fetch resources from the web.

  • Added the HTTPResponse, which contains the methods for accessing the contents of the fetched resource.

  • Added the UrlFetch limits topic, which lists limits for fetching resources from the web.

Add the following topics:

October 2, 2018

Added the following objects and methods to support multi-accounts.

  • Added the currentAccount method to BingAdsApp. Use this method to get the Account object, which contains information about the account that the script is currently processing.

  • Added the AccountsApp object. This is the top-level object that you use if you're managing accounts for others. Use it to get the list of accounts you have access to and to select the account to manage.

  • Added the BingAdsAccount object. Use it to get account information for a managed account such as name, customer ID, and account-level performance data.

  • Added the BingAdsAccountIterator object. Use it to iterate through the list of managed accounts that you selected.

  • Added the BingAdsAccountSelector object. Use it to select the list of managed accounts that you want to get.

  • Added the BingAdsAccountStats object. Use it to access the managed account's performance data.

  • Added the ExecutionResult object. Use it to get the results and return value of the function you specify in the executeInParallel selector method (see BingAdsAccountSelector).

Added the following fields to the Budget object to support shared budgets.

  • campaigns — Gets a selector that returns all campaigns that share this budget.
  • getEntityType — Gets the object's type.
  • getId — Gets the ID that uniquely identifies the shared budget.
  • getName — Gets the shared budget's name.
  • getStats — Gets the performance data for the campaigns that share this budget.
  • getType — Get the budget's type (for example, DAILY).
  • isExplicitlyShared — Gets a Boolean value that indicates whether this budget is a shared budget.

The getId, getName, and getStats methods return data for only shared budgets; the getId and getName methods return null for unshared (individual campaign) budgets.

Added the following field to the BingAdsApp object.

  • budgets — Gets all shared budgets in the account. Use the selector to filter the list of shared budgets.

Added the following objects that you use to filter and loop through a list of shared budgets.

  • BudgetSelector — Contains the methods for filtering and ordering the list of shared budgets.

  • BudgetIterator — Contains the methods for looping through the list of shared budgets. The selector's get method returns the iterator.

The selector returns only shared budgets, it does not include unshared (individual campaign) budgets. To determine if a campaign uses an individual budget, get the budget by calling the campaign's getBudget method. Then, call the budget's isExplicitlyShared method to determine if the budget is shared. The budget is shared if isExplicitlyShared returns true.

October 1, 2018

Added the following method to the Keyword object.

  • getQualityScore — Gets the keyword's quality score. The score is in the range 1 through 10 (highest). The score shows you how competitive your ads are in the marketplace by measuring how relevant your keywords and landing pages are to customers' search terms.

September 12, 2018

Added the following methods for getting an entity's parent and child entities.

September 9, 2018

Added support for ads.

  • Added the newAd method to AdGroup. The method returns an AdBuilderSpace object, which you use to get an ad builder.

  • Added the AdBuilderSpace object. The object contains methods for getting ad builders. For example, if you want to build an expanded text ad, you'd call the object's expandedTextAdBuilder method to get the ExpandedTextAdBuilder object.

  • Added the ExpandedTextAdBuilder object, which you use to add an expanded text ad to the ad group.

  • Added the AdOperation object, which you use to determine whether Scripts successfully added the ad.

  • Added the AdViewSpace object, which contains the methods used to cast an ad to a specific type. For example, cast the base ad object to an expanded text ad.

  • Added the AdTypeSpace object, which contains the methods used to test whether an ad is of the specified type. For example, to test whether the ad is an expanded text ad.

  • Added the Ad object, which is the base ad type. It also defines a text ad.

  • Added the AdUrls object, which contains the methods for getting the ad's URLs, tracking template, and custom parameters.

  • Added the ExpandedTextAd object, which defines an expanded text ad.

  • Added the AdSelector object, which you use to specify the filter criteria for selecting ads.

  • Added the AdIterator object, which you use to iterate through the filtered list of ads.

  • Added the ads method to BingAdsApp. The method returns the AdSelector object, which you use to specify the filter criteria for selecting ads in the account.

  • Added the ads method to AdGroup. The method returns the AdSelector object, which you use to specify the filter criteria for selecting ads in the ad group.

  • Added the ads method to Campaign. The method returns the AdSelector object, which you use to specify the filter criteria for selecting ads in the campaign.

June 15, 2018

Closed beta release. This release of Microsoft Advertising Scripts is available to select participants only. For information about participating in the preview release program, please contact your account manager. The Scripts classes and documentation are subject to change.

This initial release includes the following capabilities:

  • Core campaign management (campaigns, ad groups, keywords)
  • Performance data at entity-level (campaigns, ad groups, keywords)
  • Shared Negative Keyword Lists