Edit

AI Max Campaigns

AI Max extends Search campaigns with AI-powered search term matching, final URL expansion, and automatically generated text and image assets. You control each feature through AISearchSetting, while Microsoft Advertising uses your campaign goals, website content, ads, and optional page feeds to find relevant traffic.

The Campaign Management V13 contract retains the name AISearchSetting. In this guide, AI Max refers to the feature represented by that setting.

Important

AI Max is available only to eligible accounts and Search campaigns. Some capabilities, including image generation and URL inclusions, can have additional eligibility requirements.

Before you begin

AI Max URL expansion and search term matching require a conversion-based bid strategy or a portfolio bid strategy. Before you enable either capability:

  1. Create a UET tag and add the tracking script to your website, or configure an eligible offline conversion goal.
  2. Create an appropriate conversion goal.
  3. Configure the Search campaign to use one of the following bid strategies:

For more information about conversion tracking, see Universal Event Tracking. For bidding guidance, see Budget and Bid Strategies.

Create an AI Max campaign

Use AddCampaigns to create the campaign.

  • Set CampaignType to Search.
  • Set an eligible BiddingScheme.
  • Include one AISearchSetting in Campaign.Settings.
  • Set AISearchEnabled to true.
  • Explicitly choose the child capabilities that you want to enable. The child properties are opt-out values, so false enables a capability and true disables it.

The following C# example shows the relevant campaign settings.

var campaign = new Campaign
{
    CampaignType = CampaignType.Search,
    BiddingScheme = new MaxConversionsBiddingScheme(),
    Settings = new Setting[]
    {
        new AISearchSetting
        {
            AISearchEnabled = true,
            SearchTermMatchingOptOut = false,
            FinalUrlExpansionOptOut = false,
            AutoGeneratedTextOptOut = false,
            AutoGeneratedImageOptOut = true
        }
    }
};

The example enables search term matching, final URL expansion, and automatically generated text, and opts out of automatically generated images.

AI Max settings

Setting false true Important behavior
AISearchEnabled AI Max is disabled. AI Max is enabled. This is the parent switch. When disabled, all child capabilities are opted out.
SearchTermMatchingOptOut Search term matching is enabled. Search term matching is disabled. Requires an eligible bid strategy.
FinalUrlExpansionOptOut Final URL expansion is enabled. Final URL expansion is disabled. Requires an eligible bid strategy and automatically generated text.
AutoGeneratedTextOptOut Automatically generated text is enabled. Automatically generated text is disabled. Synchronized with ResponsiveSearchAdsSetting.AutoGeneratedAssetsEnabled.
AutoGeneratedImageOptOut Automatically generated images are enabled. Automatically generated images are disabled. Enabling image generation can require additional account eligibility.
PageFeedIds Not applicable. Not applicable. Associates up to 20 unique page feeds with the campaign.

When you add a campaign and omit a nullable child opt-out, Microsoft Advertising stores the child as opted out. When you update an existing AI Max campaign and omit a child opt-out, its current value is preserved.

Use UpdateCampaigns to change these settings. Disabling AI Max opts out all child capabilities.

Search term matching

Set SearchTermMatchingOptOut to false to enable search term matching. Microsoft Advertising then uses AI-optimized targeting to match relevant search terms without requiring an advertiser-managed keyword for each query.

Microsoft Advertising manages the internal targeting used by this feature. In reports, traffic matched this way can have the bid or delivered match type AIOptimized. AIOptimized is not a Campaign Management MatchType that you can add, update, or delete.

To filter reporting data for this traffic, use DeliveredMatchTypeReportFilter.AIOptimized.

Final URL expansion

Set FinalUrlExpansionOptOut to false to allow Microsoft Advertising to select a relevant landing page from your website. Final URL expansion requires automatically generated text, so the following combination is invalid:

FinalUrlExpansionOptOut = false
AutoGeneratedTextOptOut = true

You can use page feeds and URL inclusion rules to give Microsoft Advertising more information about the pages that you want the campaign to consider.

Automatically generated assets

Text assets

AISearchSetting.AutoGeneratedTextOptOut and ResponsiveSearchAdsSetting.AutoGeneratedAssetsEnabled control the same effective text automation and are synchronized as inverse values.

  • If you supply both values and they conflict, AutoGeneratedTextOptOut takes precedence.
  • Enabling RSA auto-generated assets can enable AI Max if needed.
  • Setting AutoGeneratedTextOptOut to false can also enable AI Max.
  • Disabling RSA auto-generated assets opts out of AI Max text generation but doesn't disable the AI Max parent setting.

For information about responsive search ads, see Responsive Search Ads.

Generated text guidance

Use campaign-level text guidance to shape AI-generated ad copy:

  • Term exclusions specify exact terms or phrases to exclude from generated copy. Campaign Management supports the Campaign.TermExclusions property; each item is an AssetLink whose TextAsset.Text contains the excluded term. You can specify up to 25 terms, with up to 30 characters per term. The same setting is also available in the Bulk Campaign record.
  • Messaging restrictions provide guidance for generated copy, such as language to avoid, rules to follow, or themes to emphasize. Campaign Management supports the Campaign.MessagingRestrictions property; each item is an AssetLink whose TextAsset.Text contains the messaging restriction. You can specify up to 40 restrictions, each up to 300 characters. The same setting is also available in the Bulk Campaign record.

For Bulk examples and field details, see AI Max with the Bulk API.

Image assets

Set AutoGeneratedImageOptOut to false to enable automatically generated images. This capability can require additional account eligibility. If the account isn't eligible, the operation returns AccountNotEnabledForAIMaxImage.

Use page feeds

You can associate up to 20 unique page feed IDs with an AI Max campaign through AISearchSetting.PageFeedIds. The account must have the separate AI Max URL-inclusion eligibility.

For information about creating feeds and feed items, see Page Feeds.

For a campaign that has both Dynamic Search Ads and AI Max settings:

  • AI Max owns the page feed associations when AISearchEnabled is true and the account is eligible for AI Max URL inclusions.
  • Otherwise, Dynamic Search Ads remains the page feed owner.

To retrieve page feed IDs through Campaign Management, include both CampaignAdditionalField.AISearchSetting and CampaignAdditionalField.PageFeedInAISearchSettings in ReturnAdditionalFields.

Create URL inclusions

URL inclusions let you refine the webpages that AI Max can target. A URL inclusion is a biddable Webpage criterion under a standard Search ad group in an AI Max-enabled campaign.

Use AddAdGroupCriterions with a BiddableAdGroupCriterion.

An inclusion must contain at least one condition and can contain at most three. The supported condition and operator combinations are:

Condition Supported operator
Url Contains or Equals
Category Equals
CustomLabel Equals
PageTitle Contains
PageContent Contains

A URL Equals condition must be the only condition. AI Max URL targets don't support a bid, tracking template, custom parameters, or final URL suffix. To change the conditions, delete the target and add a new one.

An eligible mixed campaign can contain both AISearchSetting and DynamicSearchAdsSetting. Its SearchStandard ad groups use AI Max URL inclusions, while its SearchDynamic ad groups continue to use Dynamic Search Ads targeting.

Use brand exclusions and inclusions

Associate a BrandList with a campaign by using SetSharedEntityAssociations. Set SharedEntityType to BrandList, EntityType to Campaign, and use IsExclusion to choose how the list applies: true for a brand exclusion list or false for a brand inclusion list. You can also manage the association with a Bulk Campaign Brand List Association record.

AI Max brand exclusions are not subject to the search term matching requirement for brand inclusions. Search term matching must be enabled to add, reactivate, or delete an AI Max brand inclusion association.

If search term matching is disabled, you can still set an existing inclusion association to Inactive. Attempts to make other inclusion changes return BrandInclusionRequiresSearchTermMatching.

When AI Max or search term matching is disabled, Microsoft Advertising can set applicable active brand inclusion associations to Inactive. Re-enabling the feature can reactivate the applicable associations.

Get AI Max settings

AI Max settings aren't returned by default. Include CampaignAdditionalField.AISearchSetting when you call GetCampaignsByAccountId or GetCampaignsByIds.

To also return PageFeedIds, include CampaignAdditionalField.PageFeedInAISearchSettings.

Report on AI Max

Use SearchTermLandingPageReportRequest to map AI Max search terms to the delivered headline and final landing page.

The report:

  • Includes AI Max-enabled campaigns.
  • Excludes rows with zero clicks.
  • Supports AIOptimized in the bid and delivered match type columns.
  • Supports DeliveredMatchTypeReportFilter.AIOptimized.
  • Requires FinalUrl and at least one performance statistic.

If you request Headline, rows without a resolved supported headline asset are excluded.

Common errors

Code Error Cause
6901 AccountNotEnabledForAIMax The account isn't eligible for AI Max.
6902 InvalidAIMaxSettings The parent and child settings conflict, or URL expansion is enabled while text generation is disabled.
6903 AccountNotEnabledForAIMaxImage The account isn't eligible for AI Max image generation.
6906 AccountNotEnabledForAIMaxUrlInclusion The account isn't eligible for AI Max page feeds or URL inclusions.
6908 AIMaxUrlInclusionConditionIsNullOrEmpty A URL inclusion doesn't contain a targeting condition.
6909 BrandInclusionRequiresSearchTermMatching A brand inclusion change was requested while search term matching was disabled.
6910 UrlOptionsNotSupportedForAIMaxUrlTarget An AI Max URL target contains unsupported URL options.

See also