Microsoft Advertising

https://learn.microsoft.com/en-us/advertising
Admin
Microsoft Advertising provides APIs and platforms for managing ad campaigns, content, hotel ads, and...
Tokens:3,723,424
Snippets:26,313
Trust Score:10
Update:4 days ago
Show doc for...
Tokens:
Raw
### AdGroupExcludedAudienceSelector Example Usage

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupexcludedaudienceselector

Example usage of the AdGroupExcludedAudienceSelector to iterate over ad group excluded audiences. The example shows how to get all ad groups, then for each ad group, get the excluded audiences with a limit and ID filter.

```APIDOC
## AdGroupExcludedAudienceSelector

### Description
Contains the methods for filtering and sorting a list of ad group excluded audiences. For information about selectors, see Selectors.

### Example Usage

```javascript
// Gets the iterator that iterates all ad group excluded audiences
// in the account.
var iterator = AdsApp.adGroups().get();

// Loops through all ad groups in the account.
while (iterator.hasNext()) {
    var adGroup = iterator.next();

    // Gets the iterator that iterates all ad group excluded audiences
    // in the ad group excluded audience.
    var audienceIterator = adGroup.targeting().audiences()
        .withLimit(10)
        .withIds("123456789")
        .get();

    // Loops through all ad group excluded audiences in the ad group excluded audience.
    while (audienceIterator.hasNext()) {
        var audience = audienceIterator.next();
    }
}
```

### Methods
- **withLimit(limit)** - Sets the maximum number of ad group excluded audiences to return. (Inferred from example usage)
- **withIds(ids)** - Filters the ad group excluded audiences by their IDs. (Inferred from example usage)
- **get()** - Returns an iterator over the ad group excluded audiences that match the selector's criteria. (Inferred from example usage)
```

--------------------------------

### ManageProductExample C# Implementation

Source: https://learn.microsoft.com/en-us/advertising/shopping-content/code-example-manage-products

This C# example demonstrates the core workflow for managing products, including authentication, listing catalogs, adding a product, and retrieving product details.

```csharp
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Reflection;
using System.Security.Cryptography;
using System.ServiceModel;
using System.Text;
using System.Threading.Tasks;
using Microsoft.BingAds;
using Newtonsoft.Json;

namespace Products
{
    public class ManageProductExample
    {
        private const string BaseUri = "https://content.api.bingads.microsoft.com/shopping/v9.1";
        private const string BmcUri = BaseUri + "/bmc/{0}";
        private const string ClientState = "ClientStateGoesHere";
        
        private static string ClientId = "<CLIENTIDGOESHERE>";
        private static string DeveloperToken = "<DEVELOPERTOKENGOESHERE>";
        private static string RefreshToken = "<REFRESHTOKENGOESHERE>";
        private static string MerchantId = "<STOREIDGOESHERE>";

        private static OAuthDesktopMobileAuthCodeGrant OAuth;

        public static void Main()
        {
            try
            {
                OAuth = AuthenticateWithOAuth();

                // Get the default catalog.
                // Note that getting catalog information is an expensive call and should be limited. The example
                // includes this call simply to demonstrate using the call. If you don't specify a catalog, the
                // product is automatically written to the default catalog, so getting the catalog ID is only useful
                // if you're adding the product to a non-default catalog. 

                Catalog defaultCatalog = ListCatalogs().FirstOrDefault(cat => cat.IsDefault == true);

                // Add a product to the catalog
                Product testProduct = GetTestProduct("My Test Product ({0})");
                // If catalog id is not specified, the product is added to the default catalog.
                Product addedProduct = AddProduct(defaultCatalog.Id, testProduct);
                Console.WriteLine("*** Added product to catalog (catalog.Id=" + defaultCatalog.Id + ", product.Id=" + addedProduct.Id + ")***");
                Print(addedProduct);
                Console.WriteLine("*** / End of added product (catalog.Id=" + defaultCatalog.Id + ", product.Id=" + addedProduct.Id + ")***");
                Console.WriteLine();

                // Retrieve a product by id
                Product retrievedProduct = GetProduct(addedProduct.Id);
                Console.WriteLine("*** Retrieved product (product.Id=" + retrievedProduct.Id + ")***");
                Print(retrievedProduct);
                Console.WriteLine("*** / End retrieved product (product.Id=" + retrievedProduct.Id + ")***");
                Console.WriteLine();

                // List products
                Console.WriteLine("*** Listing products ***");
                foreach (Product product in ListProducts())
                {
                    Print(product);
                }
                Console.WriteLine("*** / End of listing products ***");
                Console.WriteLine();
```

--------------------------------

### AdGroupAudienceSelector Example Usage

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupaudienceselector

Example demonstrating how to iterate through all ad group audiences in an account using the AdGroupAudienceSelector. The example shows getting an iterator for ad groups, then for each ad group, getting an iterator for its audiences with limit and ID filters.

```APIDOC
## AdGroupAudienceSelector

### Description
Contains the methods for filtering and sorting a list of ad group audiences. For information about selectors, see Selectors.

### Methods
- **withLimit(limit)** - Sets the maximum number of ad group audiences to return.
- **withIds(ids)** - Filters the ad group audiences by their IDs.
- **get()** - Gets the iterator that iterates all ad group audiences.

### Example Usage
```javascript
// Gets the iterator that iterates all ad group audiences
// in the account.
var iterator = AdsApp.adGroups().get();

// Loops through all ad groups in the account.
while (iterator.hasNext()) {
    var adGroup = iterator.next();

    // Gets the iterator that iterates all ad group audiences
    // in the ad group audience.
    var audienceIterator = adGroup.targeting().audiences()
        .withLimit(10)
        .withIds("123456789")
        .get();

    // Loops through all ad group audiences in the ad group audience.
    while (audienceIterator.hasNext()) {
        var audience = iterator.next();
    }
}
```
```

--------------------------------

### Apply and update product partition bids

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-product-ads

Demonstrates applying a root partition with a bid, then updating that bid using the CampaignManagementExampleHelper.

```csharp
OutputStatusMessage("-----\nApplyProductPartitionActions:");
OutputStatusMessage("Applying only the root as a Unit with a bid...");
var applyProductPartitionActionsResponse = await CampaignManagementExampleHelper.ApplyProductPartitionActionsAsync(
    criterionActions: helper.PartitionActions);

OutputStatusMessage("-----\nGetAdGroupCriterionsByIds:");
var adGroupCriterions = await CampaignManagementExampleHelper.GetAdGroupCriterionsByIdsAsync(
    adGroupCriterionIds: null,
    adGroupId: adGroupId,
    criterionType: AdGroupCriterionType.ProductPartition,
    null);

OutputStatusMessage("The ad group's product partition only has a tree root node: \n");
OutputProductPartitions(adGroupCriterions?.AdGroupCriterions);

// Let's update the bid of the root Unit we just added.

BiddableAdGroupCriterion updatedRoot = new BiddableAdGroupCriterion
{
    Id = applyProductPartitionActionsResponse.AdGroupCriterionIds[0],
    CriterionBid = new FixedBid
    {
        Amount = 0.45
    }
};

helper = new PartitionActionHelper(adGroupId);
helper.UpdatePartition(updatedRoot);

OutputStatusMessage("-----\nApplyProductPartitionActions:");
OutputStatusMessage("Updating the bid for the tree root node...");
await CampaignManagementExampleHelper.ApplyProductPartitionActionsAsync(
    criterionActions: helper.PartitionActions);

OutputStatusMessage("-----\nGetAdGroupCriterionsByIds:");
adGroupCriterions = await CampaignManagementExampleHelper.GetAdGroupCriterionsByIdsAsync(
    adGroupCriterionIds: null,
    adGroupId: adGroupId,
    criterionType: AdGroupCriterionType.ProductPartition,
    null);

OutputStatusMessage("Updated the bid for the tree root node: \n");
OutputProductPartitions(adGroupCriterions?.AdGroupCriterions);
```

--------------------------------

### Bulk CSV Example for App Install Ad Label

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/app-install-ad-label

Example of a Bulk CSV file that applies a label to an app install ad, with valid Id and Parent Id values.

```APIDOC
## Bulk CSV Example

### Description
Applies a label to an app install ad using a Bulk CSV file.

### Format
CSV

### Example
```csv
Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Name,Description,Label,Color
Format Version,,,,,,,,6.0,,,
App Install Ad Label,,-22,-11112,,,ClientIdGoesHere,,,,,
```

### Fields
- **Type** (string) - Required - The record type, set to "App Install Ad Label".
- **Status** (string) - Optional - Status of the association (e.g., Active).
- **Id** (long) - Required - The identifier of the label association.
- **Parent Id** (long) - Required - The identifier of the app install ad.
- **Client Id** (string) - Optional - A client-supplied identifier for the record.
- **Modified Time** (datetime) - Optional - The last modified time of the record.
```

--------------------------------

### Set up a service API client with Configuration

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started-php

Configure authentication once using the Configuration class and construct a typed API client per service. This example sets up a CampaignManagementServiceApi with OAuth desktop/mobile auth code grant, sandbox environment, and a refresh token. Replace placeholders like YOUR_CLIENT_ID and YOUR_ACCOUNT_ID with actual values.

```php
use Microsoft\MsAds\Rest\Api\CampaignManagementServiceApi;
use Microsoft\MsAds\Rest\Auth\ApiEnvironment;
use Microsoft\MsAds\Rest\Auth\AuthorizationData;
use Microsoft\MsAds\Rest\Auth\OAuthDesktopMobileAuthCodeGrant;
use Microsoft\MsAds\Rest\Auth\OAuthScope;
use Microsoft\MsAds\Rest\Configuration;
use GuzzleHttp\Client;

$configuration = Configuration::getDefaultConfiguration();

$authentication = (new OAuthDesktopMobileAuthCodeGrant())
    ->withEnvironment(ApiEnvironment::SANDBOX)
    ->withClientId('YOUR_CLIENT_ID')
    ->withOAuthScope(OAuthScope::MSADS_MANAGE);

$configuration->setAuthorizationData(
    (new AuthorizationData())
        ->withAuthentication($authentication)
        ->withDeveloperToken('BBD37VB98')
        ->withCustomerId('YOUR_CUSTOMER_ID')
        ->withAccountId('YOUR_ACCOUNT_ID')
);

$configuration->getAuthorizationData()->Authentication->RequestOAuthTokensByRefreshToken($refreshToken);

$campaignManagementServiceApi = new CampaignManagementServiceApi(
    new Client(),
    $configuration,
    null,
    ApiEnvironment::SANDBOX
);
```

--------------------------------

### NegativeKeywordListIterator Example Usage

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlistiterator

Example JavaScript code demonstrating how to get an iterator for all negative keyword lists in the account and loop through them.

```APIDOC
## NegativeKeywordListIterator Example Usage

### Description
Gets an iterator for all negative keyword lists in the account and loops through each list.

### Code Example
```javascript
// Gets the iterator that iterates all negative keyword
// lists in the account.
var iterator = AdsApp.negativeKeywordLists().get();

// Loops through all lists in the account.
while (iterator.hasNext()) {
    var nkwList = iterator.next();
}
```
```

--------------------------------

### Create and Apply Product Partitions

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-product-ads

This snippet demonstrates defining product conditions and adding them as partitions to an ad group, followed by applying the actions and retrieving the updated criterion tree.

```java
        ProductCondition petSuppliesSubdivisionCondition = new ProductCondition();
        petSuppliesSubdivisionCondition.setAttribute("Pet Supplies");
        petSuppliesSubdivisionCondition.setOperand("CategoryL2");

        AdGroupCriterion petSuppliesSubdivision = addPartition(
                        adGroupId,
                        animalsSubdivision, 
                        petSuppliesSubdivisionCondition, 
                        ProductPartitionType.SUBDIVISION, 
                        null, 
                        false);

        ProductCondition brandACondition = new ProductCondition();
        brandACondition.setAttribute("Brand A");
        brandACondition.setOperand("Brand");

        AdGroupCriterion brandA = addPartition(
                        adGroupId,
                        petSuppliesSubdivision, 
                        brandACondition, 
                        ProductPartitionType.UNIT, 
                        getFixedBid(0.35), 
                        false);

        ProductCondition brandBCondition = new ProductCondition();
        brandBCondition.setAttribute("Brand B");
        brandBCondition.setOperand("Brand");

        AdGroupCriterion brandB = addPartition(
                        adGroupId,
                        petSuppliesSubdivision, 
                        brandBCondition, 
                        ProductPartitionType.UNIT, 
                        null, 
                        true);

        ProductCondition otherBrandsCondition = new ProductCondition();
        otherBrandsCondition.setAttribute(null);
        otherBrandsCondition.setOperand("Brand");

        AdGroupCriterion otherBrands = addPartition(
                        adGroupId,
                        petSuppliesSubdivision, 
                        otherBrandsCondition, 
                        ProductPartitionType.UNIT, 
                        getFixedBid(0.35), 
                        false);

        ProductCondition otherPetSuppliesCondition = new ProductCondition();
        otherPetSuppliesCondition.setAttribute(null);
        otherPetSuppliesCondition.setOperand("CategoryL2");

        AdGroupCriterion otherPetSupplies = addPartition(
                        adGroupId,
                        animalsSubdivision, 
                        otherPetSuppliesCondition, 
                        ProductPartitionType.UNIT, 
                        getFixedBid(0.35), 
                        false);

        ProductCondition electronicsCondition = new ProductCondition();
        electronicsCondition.setAttribute("Electronics");
        electronicsCondition.setOperand("CategoryL1");

        AdGroupCriterion electronics = addPartition(
                        adGroupId,
                        root, 
                        electronicsCondition, 
                        ProductPartitionType.UNIT, 
                        getFixedBid(0.35), 
                        false);

        ProductCondition otherCategoryL1Condition = new ProductCondition();
        otherCategoryL1Condition.setAttribute(null);
        otherCategoryL1Condition.setOperand("CategoryL1");

        AdGroupCriterion otherCategoryL1 = addPartition(
                        adGroupId,
                        root, 
                        otherCategoryL1Condition, 
                        ProductPartitionType.UNIT, 
                        getFixedBid(0.35), 
                        false);

        outputStatusMessage("-----\nApplyProductPartitionActions:");
        outputStatusMessage("Applying product partitions to the ad group...");
        ApplyProductPartitionActionsResponse applyPartitionActionsResponse = CampaignManagementExampleHelper.applyProductPartitionActions(
                _partitionActions);

        outputStatusMessage("-----\nGetAdGroupCriterionsByIds:");
        adGroupCriterions = CampaignManagementExampleHelper.getAdGroupCriterionsByIds(
            null,
            adGroupId, 
            criterionType,
            null).getAdGroupCriterions();

        outputStatusMessage("The product partition group tree now has 9 nodes");
        printProductPartitions(adGroupCriterions);

        return applyPartitionActionsResponse;
    }
```

--------------------------------

### Upload BulkAppInstallAd using BulkServiceManager in C#

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/app-install-ad

Demonstrates how to map properties to a BulkAppInstallAd object and upload it using the BulkServiceManager. The example includes mapping for ad group, campaign, app platform, and custom parameters.

```csharp
var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkAppInstallAd
var bulkAppInstallAd = new BulkAppInstallAd
{
    // 'Parent Id' column header in the Bulk file
    AdGroupId = adGroupIdKey,
    // 'Ad Group' column header in the Bulk file
    AdGroupName = "AdGroupNameGoesHere",
    // 'Campaign' column header in the Bulk file
    CampaignName = "ParentCampaignNameGoesHere",
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
                
    // Map properties in the Bulk file to the 
    // AppInstallAd object of the Campaign Management service.
    AppInstallAd = new AppInstallAd
    {
        // 'App Platform' column header in the Bulk file
        AppPlatform = "Android",
        // 'App Id' column header in the Bulk file
        AppStoreId = "AppStoreIdGoesHere",
        // 'Device Preference' column header in the Bulk file
        DevicePreference = 0,
        // 'Final Url' column header in the Bulk file
        FinalUrls = new[] {
            // Each Url is delimited by a semicolon (;) in the Bulk file
            "FinalUrlGoesHere"
        },
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Status' column header in the Bulk file
        Status = AdStatus.Active,
        // 'Text' column header in the Bulk file
        Text = "Find New Customers & Increase Sales!",
        // 'Title' column header in the Bulk file
        Title = "Contoso Quick Setup",
        // 'Tracking Template' column header in the Bulk file
        TrackingUrlTemplate = null,
        // 'Custom Parameter' column header in the Bulk file
        UrlCustomParameters = new CustomParameters
        {
            // Each custom parameter is delimited by a semicolon (;) in the Bulk file
            Parameters = new[] {
                new CustomParameter(){
                    Key = "promoCode",
                    Value = "PROMO1"
                },
                new CustomParameter(){
                    Key = "season",
                    Value = "summer"
                },
            }
        },
    },
};

uploadEntities.Add(bulkAppInstallAd);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();
```

--------------------------------

### Manage Conversion Goals with PHP (Add, Get, Update)

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-conversion-goals

PHP code example for managing conversion goals in Microsoft Advertising. It shows adding an app install goal, fetching goals by IDs, and updating a goal (including changing its type). The code uses the Campaign Management service and includes assertions for partial errors.

```php
$appInstallGoal = new AppInstallGoal();
// You must provide a valid app platform and app store identifier,
// otherwise this goal will not be added successfully.
$appInstallGoal->setAppPlatform("Windows");
$appInstallGoal->setAppStoreId("AppStoreIdGoesHere");
$appInstallGoal->setConversionWindowInMinutes(30);
$appInstallGoal->setCountType(ConversionGoalCountType::ALL);
$appInstallGoal->setName("My App Install Goal".self::generateRandomAlphaNumeric());
// Account scope is not supported for app install goals. You can
// set scope to Customer or don't set it for the same result.
$appInstallGoal->setScope(EntityScope::CUSTOMER);
$appInstallGoal->setStatus(ConversionGoalStatus::ACTIVE);
// The TagId is inherited from the ConversionGoal base class,
// however, App Install goals do not use a UET tag.

$revenue = new ConversionGoalRevenue();
$revenue->setType(ConversionGoalRevenueType::FIXED_VALUE);
$revenue->setValue(5.00);
$appInstallGoal->setRevenue($revenue);

$request = new AddConversionGoalsRequest([
    'ConversionGoals' => [$durationGoal, $eventGoal, $pagesViewedPerVisitGoal, $urlGoal, $appInstallGoal]
]);

$response = self::$campaignManagementServiceApi->addConversionGoals($request);
$goalIds = $response->getConversionGoalIds() ?? [];
print("ConversionGoalIds:\r\n");
print_r($goalIds);
print("PartialErrors:\r\n");
print_r($response->getPartialErrors());
self::assertEmpty($response->getPartialErrors());
self::assertNotEmpty($goalIds);

return array_values(array_filter($goalIds));
}
```

```php
/**
 * @depends testAddConversionGoals
 * @throws ApiException
 */
public function testGetConversionGoalsByIds($goalIds)
{
    print("-----\r\nFetching Conversion Goals:\r\n");

    $request = new GetConversionGoalsByIdsRequest([
        'ConversionGoalIds' => $goalIds,
        'ConversionGoalTypes' => $this->conversionGoalTypes,
        'ReturnAdditionalFields' => $this->returnAdditionalFields
    ]);

    $response = self::$campaignManagementServiceApi->getConversionGoalsByIds($request);
    $conversionGoals = $response->getConversionGoals() ?? [];
    print("ConversionGoals:\r\n");
    print_r($conversionGoals);
    print("PartialErrors:\r\n");
    print_r($response->getPartialErrors());
    self::assertEmpty($response->getPartialErrors());
    self::assertNotEmpty($conversionGoals);
}
```

```php
/**
 * @depends testAddConversionGoals
 * @depends testGetConversionGoalsByIds
 * @throws ApiException
 */
public function testUpdateConversionGoals($goalIds)
{
    print("-----\r\nUpdating Conversion Goals:\r\n");

    $updateDurationGoal = new DurationGoal();
    // You can change the conversion goal type e.g. in this example an event goal
    // had been created above at index 1. Now we are using the returned identifier
    // at index 1 to update the type from EventGoal to DurationGoal.
    $updateDurationGoal->setId($goalIds[1]);
    $updateDurationGoal->setName("Updated Duration Goal".self::generateRandomAlphaNumeric());
    $updateDurationGoal->setConversionWindowInMinutes(60);
    $updateDurationGoal->setCountType(ConversionGoalCountType::UNIQUE);
    $updateDurationGoal->setMinimumDurationInSeconds(120);
    $updateDurationGoal->setStatus(ConversionGoalStatus::PAUSED);
    // The Scope cannot be updated, even if you update the goal type.
    // You can either send the same value or leave Scope empty.
    $updateDurationGoal->setScope(EntityScope::ACCOUNT);

    $revenue = new ConversionGoalRevenue();
    $revenue->setType(ConversionGoalRevenueType::FIXED_VALUE);
    $revenue->setValue(10.00);
    $updateDurationGoal->setRevenue($revenue);
    // You can update the tag as needed. In this example we will explicitly use the same UET tag.
    // To keep the UET tag unchanged, you can also leave this element nil or empty.
    // Update Event Goal

    $updateEventGoal = new EventGoal();
    // For both add and update conversion goal operations, you must include one or more
    // of the following event operator pairs:
    // (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression),
    // (LabelOperator and LabelExpression), (ValueOperator and Value).
    // Each event pair (e.g. ActionOperator and ActionExpression) is optional if you include
    // one or more of the other events.
```

--------------------------------

### CreateBrandKitRecommendation (C#)

Source: https://learn.microsoft.com/en-us/advertising/campaign-management-service/createbrandkitrecommendation

C# example demonstrating how to call the CreateBrandKitRecommendation operation asynchronously using the Campaign Management service.

```APIDOC
## CreateBrandKitRecommendation (C#)

### Description
C# example demonstrating how to call the CreateBrandKitRecommendation operation asynchronously using the Campaign Management service.

### Method
POST

### Endpoint
CampaignManagementService.svc v13

### Parameters
#### Request Body
- **AccountId** (long) - Required - The account identifier.
- **FinalUrl** (string) - Required - The final URL for the brand kit recommendation.

### Request Example
```csharp
public async Task<CreateBrandKitRecommendationResponse> CreateBrandKitRecommendationAsync(
    long accountId,
    string finalUrl)
{
    var request = new CreateBrandKitRecommendationRequest
    {
        AccountId = accountId,
        FinalUrl = finalUrl
    };

    return (await CampaignManagementService.CallAsync((s, r) => s.CreateBrandKitRecommendationAsync(r), request));
}
```

### Response
#### Success Response
- **CreateBrandKitRecommendationResponse** - The response object containing the result of the operation.

### Requirements
- **Service**: CampaignManagementService.svc v13
- **Namespace**: https://bingads.microsoft.com/CampaignManagement/v13
```

--------------------------------

### Bulk CSV App Install Ad Label Record

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/app-install-ad-label

Example of a Bulk CSV record used to apply a label to an app install ad.

```csv
Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Name,Description,Label,Color
Format Version,,,,,,,,6.0,,,
App Install Ad Label,,-22,-11112,,,ClientIdGoesHere,,,,,
```

--------------------------------

### getStartDate

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Get the date when ads in this ad group start serving.

```APIDOC
## getStartDate

### Description
Get the date when ads in this ad group start serving.

### Method
getStartDate

### Return Type
BingAdsDate
```

--------------------------------

### ManageProductsExample Java implementation

Source: https://learn.microsoft.com/en-us/advertising/shopping-content/code-example-manage-products

This Java class provides a complete workflow for managing products, including authentication setup, catalog retrieval, and CRUD operations for products.

```java
package com.microsoft.contentapi.examples;

import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.*;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.ProtocolException;
import java.net.URL;
import java.text.SimpleDateFormat;
import java.util.*;

import com.microsoft.contentapi.examples.datatransferobjects.*;

public class ManageProductsExample {
    private static String BaseUri = "https://content.api.bingads.microsoft.com/shopping/v9.1";
    private static String BmcUri = BaseUri + "/bmc/%s";
    private static String ClientState = "ClientStateGoesHere";

    private static String ClientId = "<CLIENTIDGOESHERE>";
    private static String DeveloperToken = "<DEVELOPERTOKENGOESHERE>";
    private static String MerchantId = "<STOREIDGOESHERE>";

    private static String authenticationToken = "<AUTHENTICATIONTOKENGOESHERE>";

    public static void main(String args[]) throws Exception {
        try{
            // Get the default catalog
            Catalog defaultCatalog = retrieveDefaultCatalog();

            // Add a product to catalog
            Product testProduct = createTestProduct("My Test Product %s");
            // if catalog id is not specified the product will be added to the default catalog, here we are specifying the default explicitly
            Product addedProduct = AddProduct(defaultCatalog.getId(), testProduct);
            System.out.println("*** Added product to catalog (catalog.Id=" + defaultCatalog.getId() + ", product.Id=" + addedProduct.getId() + ")***");
            Print(addedProduct);
            System.out.println("*** / End of added product (catalog.Id=" + defaultCatalog.getId() + ", product.Id=" + addedProduct.getId() + ")***");
            System.out.println();

            // Retrieve a product by id
            Product retrievedProduct = GetProduct(addedProduct.getId());
            System.out.println("*** Retrieved product (product.Id=" + retrievedProduct.getId() + ")***");
            Print(retrievedProduct);
            System.out.println("*** / End retreived product (product.Id=" + retrievedProduct.getId() + ")***");
            System.out.println();

            // List products
            System.out.println("*** Listing products ***");
            for (Product product : ListProducts())
            {
                Print(product);
            }
            System.out.println("*** / End of listing products ***");
            System.out.println();

            // Delete product
            System.out.println("*** Deleting Product (" + addedProduct.getId() + ") ***");
            DeleteProduct(addedProduct.getId());
            System.out.println("*** / Deleting Product Done (" + addedProduct.getId() + ") ***");
        }catch(Exception ex) {
            System.out.println(ex.getMessage());
        }
    }

    public static Catalog retrieveDefaultCatalog() throws IOException {
        List<Catalog> catalogs = ListCatalogs();
        for(Catalog catalog : catalogs){
            if(catalog.getIsDefault() == true){
                return catalog;
            }
        }
        return null;
    }

    // List catalogs
    public static String CatalogsUri = BmcUri + "/catalogs";
    public static String CatalogUri = CatalogsUri + "/%s";
    public static List<Catalog> ListCatalogs() throws IOException {
        String url = String.format(CatalogsUri, MerchantId);
        CatalogCollection catalogs = Request("GET", url, null, CatalogCollection.class);
        return catalogs == null ? new LinkedList<Catalog>() : catalogs.getCatalogs();
    }

    // List products
    public static String ListUri = BmcUri + "/products";
    public static String ListQueryString = "?max-results=2&alt=json"; // max-results set to 2 to test paging, this would be set to a higher value in a real world scenario based on your needs
    public static String ListQueryStringWithStartToken = "?max-results=2&alt=json&start-token=%s";
    public static List<Product> ListProducts() throws IOException {
        String url = String.format(ListUri + ListQueryString, MerchantId);
        LinkedList results = new LinkedList();
        while(url != null){
            ProductCollection productCollection = Request("GET", url, null, ProductCollection.class);
            results.addAll(productCollection.getResources());

            if(productCollection.nextPageToken != null){
                url = String.format(ListUri + ListQueryStringWithStartToken, MerchantId, productCollection.nextPageToken);
            }else{
                url = null;
            }
        }
        return results;
    }
```

--------------------------------

### Filter by Text

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keywordselector

Example of filtering keywords that start with a specific text string.

```javascript
withCondition("Text STARTS_WITH 'flowers'")
```

--------------------------------

### CreateBrandKitRecommendation (Java)

Source: https://learn.microsoft.com/en-us/advertising/campaign-management-service/createbrandkitrecommendation

Java example demonstrating how to call the CreateBrandKitRecommendation operation using the Campaign Management service.

```APIDOC
## CreateBrandKitRecommendation (Java)

### Description
Java example demonstrating how to call the CreateBrandKitRecommendation operation using the Campaign Management service.

### Method
POST

### Endpoint
CampaignManagementService.svc v13

### Parameters
#### Request Body
- **accountId** (Long) - Required - The account identifier.
- **finalUrl** (String) - Required - The final URL for the brand kit recommendation.

### Request Example
```java
static CreateBrandKitRecommendationResponse createBrandKitRecommendation(
    java.lang.Long accountId,
    java.lang.String finalUrl) throws RemoteException, Exception
{
    CreateBrandKitRecommendationRequest request = new CreateBrandKitRecommendationRequest();

    request.setAccountId(accountId);
    request.setFinalUrl(finalUrl);

    return CampaignManagementService.getService().createBrandKitRecommendation(request);
}
```

### Response
#### Success Response
- **CreateBrandKitRecommendationResponse** - The response object containing the result of the operation.

### Requirements
- **Service**: CampaignManagementService.svc v13
- **Namespace**: https://bingads.microsoft.com/CampaignManagement/v13
```

--------------------------------

### Upgrade the Bing Ads Python SDK with pip.exe install --upgrade msads

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started-python

Run this command if you already have the Bing Ads Python SDK installed to get the latest bits.

```powershell
pip.exe install --upgrade msads

```

--------------------------------

### Build a product partition tree structure

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-product-ads

Shows how to clear an existing root node and build a hierarchical product partition tree using subdivisions.

```csharp
helper = new PartitionActionHelper(adGroupId);

// Check whether a root node exists already.

OutputStatusMessage("-----\nGetAdGroupCriterionsByIds:");
adGroupCriterions = await CampaignManagementExampleHelper.GetAdGroupCriterionsByIdsAsync(
    adGroupCriterionIds: null,
    adGroupId: adGroupId,
    criterionType: AdGroupCriterionType.ProductPartition,
    null);

var existingRoot = GetRootNode(adGroupCriterions?.AdGroupCriterions);
if (existingRoot != null)
{
    helper.DeletePartition(existingRoot);
}

root = helper.AddSubdivision(
    null,
    new ProductCondition { Operand = "All", Attribute = null }
);

// The direct children of any node must have the same Operand. 
// For this example we will use CategoryL1 nodes as children of the root. 
// For a list of valid CategoryL1 through CategoryL5 values, see the Bing Category Taxonomy:
// https://go.microsoft.com/fwlink?LinkId=507666

var animalsSubdivision = helper.AddSubdivision(
    parent: root,
    condition: new ProductCondition { Operand = "CategoryL1", Attribute = "Animals & Pet Supplies" });

// If you use a CategoryL2 node, it must be a descendant (child or later) of a CategoryL1 node. 
// In other words you cannot have a CategoryL2 node as parent of a CategoryL1 node. 
// For this example we will a CategoryL2 node as child of the CategoryL1 Animals & Pet Supplies node. 

var petSuppliesSubdivision = helper.AddSubdivision(
    parent: animalsSubdivision,
    condition: new ProductCondition { Operand = "CategoryL2", Attribute = "Pet Supplies" });
```

--------------------------------

### Manage Ad Extensions in C#

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-ad-extensions

This example shows how to initialize the Campaign Management service, add a campaign, and prepare media for an image ad extension using the V13 Campaign Management service.

```C#
using System;
using System.Drawing;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.CampaignManagement;
using Microsoft.BingAds;

namespace BingAdsExamplesLibrary.V13
{
    /// <summary>
    /// How to manage ad extensions for an account's ad extension library, 
    /// associate the extensions with a campaign, and determine why an extension failed 
    /// editorial review.
    /// </summary>
    public class AdExtensions : ExampleBase
    {
        // To run this example you'll need to provide your own image.  
        // For required aspect ratios and recommended dimensions please see 
        // Image remarks at https://go.microsoft.com/fwlink/?linkid=872754.

        private const string MediaFilePath = "c:\\dev\\media\\";
        private const string ImageAdExtensionMediaFileName = "imageadextension300x200.png";

        public override string Description
        {
            get { return "Ad Extensions | Campaign Management V13"; }
        }

        public async override Task RunAsync(AuthorizationData authorizationData)
        {
            try
            {
                ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;

                CampaignManagementExampleHelper CampaignManagementExampleHelper = new CampaignManagementExampleHelper(
                    OutputStatusMessageDefault: this.OutputStatusMessage);
                CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                    authorizationData: authorizationData,
                    environment: environment);

                // Add a campaign to associate with ad extensions. 

                var campaigns = new[] {
                    new Campaign
                    {
                        BudgetType = BudgetLimitType.DailyBudgetStandard,
                        DailyBudget = 50,
                        Languages = new string[] { "All" },
                        Name = "Everyone's Shoes " + DateTime.UtcNow,
                        TimeZone = "PacificTimeUSCanadaTijuana",
                    }
                };

                OutputStatusMessage("-----\nAddCampaigns:");
                AddCampaignsResponse addCampaignsResponse = await CampaignManagementExampleHelper.AddCampaignsAsync(
                    accountId: authorizationData.AccountId,
                    campaigns: campaigns);
                long?[] campaignIds = addCampaignsResponse.CampaignIds.ToArray();
                BatchError[] campaignErrors = addCampaignsResponse.PartialErrors.ToArray();
                OutputStatusMessage("CampaignIds:");
                CampaignManagementExampleHelper.OutputArrayOfLong(campaignIds);
                OutputStatusMessage("PartialErrors:");
                CampaignManagementExampleHelper.OutputArrayOfBatchError(campaignErrors);
                
                // Create media for the image ad extension that we'll add later. 

                var imageAdExtensionMedia = GetImageMedia(
                    "Image15x10",
                    MediaFilePath + ImageAdExtensionMediaFileName,
                    System.Drawing.Imaging.ImageFormat.Png);
```

--------------------------------

### getStartDate

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Gets the date when ads in this ad group start serving. Returns a BingAdsDate object.

```APIDOC
## getStartDate

### Description
Gets the date when ads in this ad group start serving.

### Method
Method call

### Returns
- **BingAdsDate** - The date when ads in this ad group start serving.
```

--------------------------------

### C# SDK Example

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/campaign-action-ad-extension

Example of using the BulkServiceManager to upload a BulkCampaignActionAdExtension object.

```APIDOC
## C# SDK Example

### Description
Example of using the BulkServiceManager to upload a BulkCampaignActionAdExtension object.

### Code
```csharp
var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkCampaignActionAdExtension
var bulkCampaignActionAdExtension = new BulkCampaignActionAdExtension
{
    // Map properties in the Bulk file to the 
    // AdExtensionIdToEntityIdAssociation object of the Campaign Management service.
    AdExtensionIdToEntityIdAssociation = new AdExtensionIdToEntityIdAssociation
    {
        // 'Id' column header in the Bulk file
        AdExtensionId = actionAdExtensionIdKey,
        // 'Parent Id' column header in the Bulk file
        EntityId = campaignIdKey,
    },
                
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
    // 'Status' column header in the Bulk file
    Status = Status.Active,
};

uploadEntities.Add(bulkCampaignActionAdExtension);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();
```
```

--------------------------------

### Add a new App Install Goal via Bulk CSV

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/app-install-goal

Example of a Bulk CSV record used to add a new app install goal. The format version is specified as 6.0.

```csv
Type,Id,Attribution Model Type,Count Type,Exclude From Bidding,Goal Category,Is Enhanced Conversions Enabled,Name,Conversion Currency Code,Revenue Value,Revenue Type,Scope,UET Tag Id,Status,View Through Conversion Window In Minutes,Conversion Window In Minutes,Category Expression,Category Operator,Action Expression,Action Operator,Label Expression,Label Operator,Event Value,Event Value Operator,URL Expression,URL Operator,Minimum Duration In Second,App Platform,App Id,Minimum Pages Viewed  
Format Version,,,,,,,6.0,,,,,,,,,,,,,,,,,,,,,,  
AppInstall Goal,,,,False,Download,False,GoalE,USD,1,FixedValue,Account,,Active,150,367,,,,,,,,,,,,Android,qazwsx,
```

--------------------------------

### Bulk CSV format for App Install Ad

Source: https://learn.microsoft.com/en-us/advertising/bulk-service/app-install-ad

This CSV example demonstrates the structure required to add a new app install ad, including mandatory fields like App Platform and App Id.

```csv
Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Title,Text,Display Url,Destination Url,Promotion,Device Preference,Name,App Platform,App Id,Final Url,Mobile Final Url,Tracking Template,Final Url Suffix,Custom Parameter
Format Version,,,,,,,,,,,,,,6.0,,,,,,,
App Install Ad,Active,,-1111,ParentCampaignNameGoesHere,AdGroupNameGoesHere,ClientIdGoesHere,,Contoso Quick Setup,Find New Customers & Increase Sales!,,,,All,,Android,AppStoreIdGoesHere,FinalUrlGoesHere,,,,{_promoCode}=PROMO1; {_season}=summer
```

--------------------------------

### Initialize Campaign Management Service in Java

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-offline-conversions

This snippet shows the setup for the Campaign Management service client in a Java application.

```java
package com.microsoft.bingads.examples.v13;

import java.util.ArrayList;

import java.util.Calendar;
import java.util.TimeZone;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;

public class OfflineConversions extends ExampleBase {

    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData();
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                        authorizationData, 
                        API_ENVIRONMENT,
                        ICampaignManagementService.class);
```

--------------------------------

### GetUsersInfo

Source: https://learn.microsoft.com/en-us/advertising/customer-management-service/customer-management-service-operations

Gets a list of objects that contains user identification information, for example the user name and identifier of the user.

```APIDOC
## GetUsersInfo

### Description
Gets a list of objects that contains user identification information, for example the user name and identifier of the user.

### Request Limits
- 1 CustomerId
```

--------------------------------

### Get Test Product

Source: https://learn.microsoft.com/en-us/advertising/shopping-content/code-example-manage-products

Creates a sample product object for testing purposes.

```csharp
private static Product GetTestProduct(string titleFormat)
        {
            string id = Guid.NewGuid().ToString();
            return new Product()
            {
                Availability = "in stock",
                Channel = ProductChannel.Online.ToString(),
                Condition = ProductCondition.New.ToString(),
                ContentLanguage = "en",
                Link = "http://www.contoso.com/apperal/men/tshirts.htm",
                ImageLink = "http://www.contoso.com/pics/tees.jpg",
                OfferId = id,
                Price = new Price()
                {
                    Currency = "USD",
                    Value = (decimal)1205.00
                },
                TargetCountry = "US",
                Title = string.Format(titleFormat, id),
                IdentifierExists = false,
                ExpirationDate = DateTime.UtcNow.AddDays(45).ToString("O")
            };
        }
```

--------------------------------

### Manage Client Links in C#

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-client-links

This C# example demonstrates how to invite a client using agency credentials and accept the invitation using client credentials. You must provide a valid ClientAccountId and run the sample as a Super Admin for the respective roles.

```csharp
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.CustomerManagement;
using Microsoft.BingAds;

namespace BingAdsExamplesLibrary.V13
{
    /// <summary>
    /// How to use agency credentials to invite a client, and use client credentials to accept the invitation.
    /// Run this sample multiple times alternating between agency and client credentials 
    /// to update and observe the status change, for example from LinkPending to LinkAccepted to Active. 
    /// </summary>
    public class ClientLinks : ExampleBase
    {
        // REQUIRED: The Client Account Id that you want to access.
        private long ClientAccountId = 0; 

        public override string Description
        {
            get { return "Manage Client | Customer Management V13"; }
        }

        public async override Task RunAsync(AuthorizationData authorizationData)
        {
            try
            {
                OutputStatusMessage("You must edit this example to provide the ClientAccountId for the client link." +
                    "When adding a client link, the client link's ManagingCustomerId is set to the CustomerId " +
                    "of the current authenticated user, who must be a Super Admin of the agency." +
                    "Login as an agency Super Admin user to send a client link invitation, or unlink an existing client link." +
                    "Login as a client Super Admin user to accept a client link invitation.");

                ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;

                CustomerManagementExampleHelper CustomerManagementExampleHelper = new CustomerManagementExampleHelper(
                    OutputStatusMessageDefault: this.OutputStatusMessage);
                CustomerManagementExampleHelper.CustomerManagementService = new ServiceClient<ICustomerManagementService>(
                    authorizationData: authorizationData,
                    environment: environment);

                UpdateClientLinksResponse updateClientLinksResponse = null;

                // Set the client link search criteria.

                var pageInfo = new Paging
                {
                    Index = 0, // The first page
                    Size = 100 // The first 100 client links for this page of results
                };

                var ordering = new OrderBy
                {
                    Field = OrderByField.Number,
                    Order = SortOrder.Ascending
                };

                var predicate = new Predicate
                {
                    Field = "ClientAccountId",
                    Operator = PredicateOperator.In,
                    Value = ClientAccountId.ToString(CultureInfo.InvariantCulture)
                };

                // Search for client links that match the criteria.
```

--------------------------------

### SDK AuthorizationData Setup

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started

Examples of setting the AuthorizationData object with authentication, customer ID, account ID, and developer token in C#, Java, PHP, and Python.

```C#
var authorizationData = new AuthorizationData
{
    Authentication = <AuthenticationGoesHere>, 
    CustomerId = <CustomerIdGoesHere>,
    AccountId = <AccountIdGoesHere>,
    DeveloperToken = "<DeveloperTokenGoesHere>"
};
```

```Java
static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");
```

```PHP
$authorizationData = (new AuthorizationData())
    ->withAuthentication($AuthenticationGoesHere)
    ->withCustomerId($CustomerIdGoesHere)
    ->withAccountId($AccountIdGoesHere)
    ->withDeveloperToken($DeveloperTokenGoesHere);
```

```Python
authorization_data = AuthorizationData(
    authentication = <AuthenticationGoesHere>,
    customer_id = <CustomerIdGoesHere>,
    account_id = <AccountIdGoesHere>,
    developer_token = '<DeveloperTokenGoesHere>'
)
```
Tokens:
Raw