Download Notes on Bing Ads API

Notes on Bing Ads API
Created 06/09/12
Updated 01/25/13, Updated 05/12/14, Updated 09/15/15, Updated 12/26/15
Introduction
Bing Ads (formerly Microsoft adCenter and MSN adCenter) is a service that provides pay per click advertising
on both the Bing and Yahoo! search engines. As of the fourth quarter 2013, Bing Ads has 15.6% market share in the
United States.[1]
Similar to Google AdWords, Bing Ads uses both the maximum amount an advertiser is willing to pay per
click (PPC) on their ad and the advertisement's click-through rate (CTR) to determine how frequently an
advertisement is shown. This system encourages advertisers to write effective ads and to advertise only on searches
which are relevant to their advertisement.[17]
Bing Ads allows advertisers to target their ads by restricting their ads to a given set of demographics and by
increasing their bids whenever the ad is seen by a user of a certain demographic. As of November 2006, no other
PPC advertising system has a similar feature. Similarly, Bing Ads allows advertisers to run their ads on specific days
of the week or certain times of day.
Similar to AdWords Editor, Bing Ads provide an desktop tool to manage campaigns offline, called as Bing Ads
Editor. Using this editor you can make offline changes to your campaigns and later sync it online.
Bing Ads also provides APIs that can be used to manage advertising campaigns.
Concepts
Bing Ads is a pay-per-click (PPC) advertising platform used to display ads based on the keywords used in a user’s
search query. For advertisers placing a large number of ads or developers building advertising tools, the Bing Ads
API provides a programmatic interface to Bing Ads. Using the Bing Ads API is the most efficient way to manage
many large campaigns or to integrate your marketing with other in-house systems. The Bing Ads API also supports
multiple customer accounts making it easy for ad agencies to manage campaigns for many clients. Some
organizations may choose a hybrid approach; using the web UI for most tasks but automating reporting or campaign
optimization with the API.







Page 1
Who should use the Bing Ads API
Where your ads will appear
Enrich your ad layout
Show ads to your target audience
Optimize your campaigns
Join the developer community
Next steps and navigating the content
DataTypes
Account
Campaign
Ad Group
Ads
Keywords
Getting Started
To get started developing Bing Ads applications with Java, install the SDK and either start with the provided
examples or follow one of the application walkthroughs for a web or desktop application. You can also browse
the Java Examples for Bing Ads on MSDN. The examples have been developed with the Bing Ads Java SDK in
the environment described below. Your custom configuration may vary.









Page 2
Setting Up the Development Environment
Installing the SDK
Walkthroughs
Using AuthorizationData
Using OAuth
Using ServiceClient
Using BulkServiceManager
Using ReportingServiceManager
Configuring Sandbox
Setting Up the Development Environment
You need user credentials with access to Bing Ads either in production or sandbox. You also need a developer
token. For more information, please see Getting Started With the Bing Ads API and Sandbox.
To authenticate with a Microsoft Account in production, the Microsoft account user must sign up or be invited to
manage an existing Bing Ads account. You also must register an application and get the corresponding client
identifier. You also need to take note of the client secret and redirect URI if you are developing a web application.
For more information, see Managing User Authentication with OAuth.
You must install a Java Runtime Environment (JRE), version 1.6 or later.
The Java Examples for Bing Ads are developed and run with the Eclipse Java EE IDE for Web Developers, Luna
Service Release 1 (4.4.1). For Eclipse downloads, see http://www.eclipse.org/downloads/.
For Managing User Authentication with OAuth in a web application, you will need to deploy to a server with a
publicly available redirection URL. For more information, see Deploying a Web Application.
Installing the SDK
The Bing Ads Java SDK depends on the libraries listed at the Maven Repository.
When you create a Maven project and include the microsoft.bingads Maven artifact as shown below, additional
dependencies are installed automatically. If you are not using a Maven project, you must include the correct version
of each dependency. For more information, please see the web or desktop application examples.
XML
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven4.0.0.xsd"> ... <dependencies>
<dependency>
<artifactId>microsoft.bingads</artifactId>
<groupId>com.microsoft.bingads</groupId>
<version>10.4.1</version>
</dependency>
</dependencies> </project>
Note
Version 10.4.1 is included as an example. For details about the latest SDK dependency
version, please see the Bing Ads Java SDK GitHub README.md.
Walkthroughs
Once you have the Bing Ads Java SDK installed, you can either browse the Java Examples for Bing Ads,
download the examples (Code Gallery | GitHub) or follow one of the application walkthroughs for
a web or desktop application.
Page 3
Using AuthorizationData
You must initialize a new instance of ServiceClient or BulkServiceManager with AuthorizationData.
The class contains properties that Bing Ads uses to authorize a user.
The ServiceClient, BulkServiceManager, and ReportingServiceManager classes handle common
request header fields for you, allowing you to specify the Authentication, CustomerId, AccountId,
and DeveloperTokenproperties in the AuthorizationData object once for each service. For more information,
see Using ServiceClient, Using BulkServiceManager, and Using ReportingServiceManager.
The following code block shows how to create an instance of AuthorizationData and
set its Authentication, CustomerId, AccountId, and DeveloperToken properties.
java
static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");
The code example below shows the high level procedural workflow for requesting access and refresh tokens in a
web application using the OAuthWebAuthCodeGrant class.
java
// Create an instance of OAuthWebAuthCodeGrant, that will be used to manage Microsoft Account user
authorization. // Replace ClientId, ClientSecret>, and RedirectionUri with the values configured while
registering your application. OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new
OAuthWebAuthCodeGrant(
ClientId,
ClientSecret,
URL(RedirectionUri)); if (authorizationData == null) {
new
// Request user consent by
connecting to the Microsoft Account authorization endpoint through a web browser control.
if
(request.getParameter("code") == null) {
URL
authorizationEndpoint = oAuthWebAuthCodeGrant.getAuthorizationEndpoint();
response.sendRedirect(authorizationEndpoint.toString());
return;
authorizationData = new AuthorizationData();
authorizationData.setDeveloperToken(DeveloperToken);
authorizationData.setAuthentication(oAuthWebAuthCodeGrant);
}}
Using ServiceClient
You can use an instance of the ServiceClient class to call any methods in one of the
following client service interfaces:
 IAdIntelligenceService
 IBulkService
 ICampaignManagementService
 ICustomerBillingService
 ICustomerManagementService
Page 4
// Use th


IOptimizerService
IReportingService
The ServiceClient class handles common request header fields for you, allowing to
specify the Authentication, CustomerId,AccountId, and DeveloperToken properties
in the AuthorizationData object once for each service. For more information,
see Using AuthorizationData.
For example the following sample shows how to use the Customer Management service
to get the current authenticated user.
java
ServiceClient<ICustomerManagementService> CustomerService = new
ServiceClient<ICustomerManagementService>(
ICustomerManagementService.class);
authorizationData,
java.lang.Long userId = null; final GetUserRequest
getUserRequest = new GetUserRequest(); getUserRequest.setUserId(userId); User user =
CustomerService.getService().getUser(getUserRequest).getUser();
Using BulkServiceManager
Take advantage of the Bulk service to efficiently manage ads and keywords for all campaigns in an account. The
client library provides classes to accelerate productivity for downloading and uploading entities. For example
the DownloadFileAsync method of theBulkServiceManager class will submit your download request to the
bulk service, poll the service until completed, and download the file to the local directory that you specified in the
request. Use the BulkFileReader class instead of writing a file parser to read the download results.
The BulkFileReader provides access to the bulk file records in BulkEntity derived classes, which contain data
objects and values sets corresponding to the Campaign Management service.
The BulkServiceManager class handles common request header fields for you, allowing to specify
the Authentication, CustomerId,AccountId, and DeveloperToken properties in
the AuthorizationData object once for each service. For more information, see Using AuthorizationData.
The BulkServiceManager automatically polls in 1000 millisecond intervals for the first five attempts, and that
behavior is not configurable. The StatusPollIntervalInMilliseconds property determines the time interval
between each polling attempt after the initial five attempts. The default value is 5000, so if you do not set this value
the BulkServiceManager will poll in the following sequence: 1, 2, 3, 4, 5, 10, 15, 20, and so on. If you set this
value to 10000, the BulkServiceManager will poll in the following sequence: 1, 2, 3, 4, 5, 15, 25, 35, and so on.
The minimum poll interval is 1000, and if you specify a value less than 1000 an exception will be thrown.
Questions and Open Issues
To be filled in
Page 5