Edit

Share via

AssetGroup Data Object - Campaign Management

  • Article

Defines an asset group in an advertising campaign.

Syntax

<xs:complexType name="AssetGroup" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="AssetGroupSearchThemes" nillable="true" type="tns:ArrayOfAssetGroupSearchTheme">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="BusinessName" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="CallToAction" nillable="true" type="tns:CallToAction" />
    <xs:element minOccurs="0" name="Descriptions" nillable="true" type="tns:ArrayOfAssetLink" />
    <xs:element minOccurs="0" name="EditorialStatus" nillable="true" type="tns:AssetGroupEditorialStatus" />
    <xs:element minOccurs="0" name="EndDate" nillable="true" type="tns:Date" />
    <xs:element xmlns:q114="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalMobileUrls" nillable="true" type="q114:ArrayOfstring" />
    <xs:element xmlns:q115="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalUrls" nillable="true" type="q115:ArrayOfstring" />
    <xs:element xmlns:q116="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q116:ArrayOfKeyValuePairOfstringstring" />
    <xs:element minOccurs="0" name="Headlines" nillable="true" type="tns:ArrayOfAssetLink" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="Images" nillable="true" type="tns:ArrayOfAssetLink" />
    <xs:element minOccurs="0" name="LongHeadlines" nillable="true" type="tns:ArrayOfAssetLink" />
    <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Path1" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Path2" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="StartDate" nillable="true" type="tns:Date" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:AssetGroupStatus" />
  </xs:sequence>
</xs:complexType>

Elements

The AssetGroup object has the following elements: AssetGroupSearchThemes, BusinessName, CallToAction, Descriptions, EditorialStatus, EndDate, FinalMobileUrls, FinalUrls, ForwardCompatibilityMap, Headlines, Id, Images, LongHeadlines, Name, Path1, Path2, StartDate, Status.

Element Description Data Type
AssetGroupSearchThemes A list of asset group search themes. AssetGroupSearchTheme array
BusinessName The name of the business.

Your business's name may appear in your ad, depending on the ad placement.

The length of the string is limited to 25 characters.

Add: Required. If not provided and parent campaign associates to a store, the store name will be used as the business name.
Update: Optional. If no value is set for the update, this setting is not changed.		 string
CallToAction A brief, punchy reason for customers to click your ad right now.

This is displayed on your call to action button.

Add: Required. If not provided and parent campaign associates to a store, it will default to LearnMore.
Update: Optional. If no value is set for the update, this setting is not changed.		 CallToAction
Descriptions The descriptions that are shown below the path in your ad.

You must set between 2-5 descriptions. Each description's Text must contain at least one word. The Text cannot contain the newline (\n) character.

If the parent campaign associates to a store and you specify Descriptions, you must also specify Headlines, LongHeadlines, and Images.

Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store.
Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any descriptions that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.		 AssetLink array
EditorialStatus The editorial review status of the asset group, which indicates whether the asset group is pending review, has been approved, or has been disapproved.

Add: Read-only
Update: Read-only		 AssetGroupEditorialStatus
EndDate The date that the asset group will expire.

If you do not specify an end date, the asset group will not expire. The end date can be extended to make an asset group eligible for delivery, even after the asset group expires.

The end date is inclusive. For example, if you set EndDate to 12/31/2020, the ads in the ad group will expire at 11:59 PM on 12/31/2020. The time is based on the time zone that you specify at the campaign level.

Add: Optional. To set no end date when adding an asset group, set this element to null.
Update: Optional. If no value is set for the update, this setting is not changed. To delete the existing end date setting, and effectively set no end date when updating an asset group, set the end date equal to or later than January 2, 2050. When you retrieve the asset group next time, this element will be nil i.e. it will not be set to January 2, 2050.		 Date
FinalMobileUrls The mobile landing page URL.

The following validation rules apply to Final URLs and Final Mobile URLs.
- The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- You may specifiy up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility.
- Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}.
- Final URLs must each be a well-formed URL starting with either http:// or https://.
- If you specify FinalMobileUrls, you must also specify FinalUrls.

Add: Optional
Update: Optional		 string array
FinalUrls The landing page URL.

The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters.

The following validation rules apply to Final URLs and Final Mobile URLs.
- The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility.
- Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}.
- Final URLs must each be a well-formed URL starting with either http:// or https://.
- If you specify FinalMobileUrls, you must also specify FinalUrls.

For retail campaigns, the final url must match the domain from the store associated with the campaign.

Add: Required. If not provided and parent campaign associates to a store, the store URL will be used as the final URL.
Update: Optional		 string array
ForwardCompatibilityMap The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version.

Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this object.		 KeyValuePairOfstringstring array
Headlines Headlines are the most prominent text that appears in your ad, so you should make the most out of the available characters. We require multiple headlines so the ad can flexibly display across a variety of publishers and placements.

From a data model perspective the descriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account.

You must set between 3-15 headlines. Each headline's Text must contain at least one word.

The Text cannot contain the newline (\n) character.

If the parent campaign associates to a store and you specify Headlines, you must also specify LongHeadlines, Descriptions, and Images.

Add: Optional if its parent campaign associates to a store, required if its parent campaign does not associate to a store.
Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any headlines that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.		 AssetLink array
Id The system generated asset group ID.

Add: Read-only
Update: Read-only		 long
Images Image assets with different sizes and aspect ratios so they can flexibly display across a variety of publishers and placements.

Include one or more AssetLink objects that each contain an ImageAsset with SubType and crop settings that match the desired aspect ratio.

The ImageAsset contains the CropHeight, CropWidth, CropX, CropY and SubType fields.

The possible sub type values include LandscapeImageMedia, SquareImageMedia, LandscapeLogoMedia, SquareLogoMedia, ImageMedia15X10, ImageMedia133X100, ImageMedia178X100, ImageMedia1X2, and ImageMedia4X1.

You must provide at least 1 LandscapeImageMedia and 1 SquareImageMedia. A total of up to 20 images and a total of up to 5 logos can be saved.

If the parent campaign associates to a store and you specify Images, you must also specify Headlines, LongHeadlines, and Descriptions.

Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store.
Update: Optional. If no value is set for the update, this setting is not changed. If you include images during update, any previously set images will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.		 AssetLink array
LongHeadlines You must set between 1-5 long headlines. Each headline's Text must contain at least one word. The Text cannot contain the newline (\n) character.

If the parent campaign associates to a store and you specify LongHeadlines, you must also specify Headlines, Descriptions, and Images.

Add: Optional if the parent campaign associates to a store, required if its parent campaign does not associate to a store.
Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set a value for this element, any headlines that were previously linked to this asset group will be replaced. If the parent campaign associates to a store and you set this element to an empty list, the previous setting will be deleted.		 AssetLink array
Name The name of the asset group. Names should be unique in a campaign and are case sensitive. The length cannot exceed 256 characters.

Add: Required
Update: Optional		 string
Path1 The first part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2.

No more than 15 characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 67 characters.

For languages with double-width characters e.g. Traditional Chinese no more than 7 final characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis.

The path cannot contain the forward slash (/) or newline (\n) characters.

If the path includes a space, it will be replaced with an underscore (_) when the ad is shown.

Add: Optional
Update: Optional		 string
Path2 The second part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2.

You can only specify Path2 if Path1 is also set.

No more than 15 characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 67 characters.

For languages with double-width characters e.g. Traditional Chinese no more than 7 final characters can be input. The ad will fail to display if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis.

The path cannot contain the forward slash (/) or newline (\n) characters.

If the path includes a space, it will be replaced with an underscore (_) when the ad is shown.

Add: Optional
Update: Optional		 string
StartDate The date that the asset group can begin serving; otherwise, the service can begin serving ads the day that the asset group becomes active.

The start date is inclusive. For example, if you set the start date to 5/5/2021, the ads created from the asset group will start at 12:00 AM on 5/5/2021. The time is based on the time zone that you specify at the campaign level.

Add: Optional. If you do not set the start date, then it will default to today's date and the service can begin serving ads as soon as the asset group status is active.
Update: Optional. If no value is set for the update, this setting is not changed. The start date cannot be updated after the asset group is submitted i.e., once the start date has arrived.		 Date
Status The status of the Asset group. Possible values are Active, Expired and Paused. The Expired status is read-only.

Add: Optional. Default is Paused.
Update: Optional		 AssetGroupStatus

Requirements

Service: CampaignManagementService.svc v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13

Used By

AddAssetGroups
GetAssetGroupsByCampaignId
GetAssetGroupsByIds
UpdateAssetGroups