Get Started Using Java with Bing Ads API

Important

We recommend that you use Java 11 or later. The minimum version of Java we support is 1.8. You need to exlude CXF from your dependencies when using 1.8. You can build this example file with Maven.

To get started developing Bing Ads API applications with Java, you can start with the provided examples or follow one of the application walkthroughs for a Web or Desktop application.

You will need user credentials with access to Microsoft Advertising either in production or sandbox. For the production environment you will need a production developer token. All sandbox clients can use the universal sandbox developer token i.e., BBD37VB98. For more information, please see Get Started With the Bing Ads API and Sandbox.

To authenticate via OAuth, you must also 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 details about registering an application in production and the authorization code grant flow, see Authentication with OAuth and Authentication With the SDKs. Although in production you must use your own application ID (a.k.a. client ID), all Microsoft Advertising customers can use the public "Tutorial Sample App" client ID in sandbox i.e., 00001111-aaaa-2222-bbbb-3333cccc4444. For more information, please see Sandbox.

Install 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 Walkthrough: Bing Ads API Web Application in Java or Walkthrough: Bing Ads API Desktop Application in Java application examples.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>com.microsoft.bingads</groupId>
      <artifactId>microsoft.bingads</artifactId>
      <version>13.0.10</version>
    </dependency>
  </dependencies>
</project>

Note

Version 13.0.10 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 Bing Ads API Code Examples, download the examples from GitHub, or follow one of the application walkthroughs for a Web or Desktop application.

Configuring Sandbox

To use the Sandbox environment, create a new text file named bingads.properties within your project source root directory e.g. ProjectName\src\bingads.properties and add the following text. The following are the complete contents of the bingads.properties file. If the sandbox environment setting is malformed or missing, the default environment is production.

environment=Sandbox

You can also set the environment for each ServiceClient individually as follows.

CustomerService = new ServiceClient<ICustomerManagementService>(
    authorizationData,
    ApiEnvironment.SANDBOX,
    ICustomerManagementService.class
);

Whether you set the ServiceClient environment globally or individually, separately you'll also need to set the OAuth environment to sandbox.

final OAuthDesktopMobileAuthCodeGrant oAuthDesktopMobileAuthCodeGrant = new OAuthDesktopMobileAuthCodeGrant(
    ClientId, 
    ApiEnvironment.SANDBOX
);

Web applications with a client secret and custom redirect URI should use OAuthWebAuthCodeGrant as follows.

OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(
    ClientId, 
    ClientSecret, 
    new URL(RedirectUri),
    ApiEnvironment.SANDBOX
);

Log the request and response headers in the console. TrackingId is included in the response headers.

MessageHandler.getInstance().setTraceOn(true);

Customizing HTTP client

For most applications, we recommend using the default HTTP client implementation in the Bing Ads Java SDK, which relies on the Apache CXF JAX-RS client. You may want to customize the HTTP client to configure some features such as enabling compression if you use a different JAX-RS implementation, to change HTTP timeout, proxy configuration, or other settings.

To do so, you can create a custom HttpClientProvider object and pass it to GlobalSettings.setHttpClientProvider() before making service calls. For example:

GlobalSettings.setHttpClientProvider(new HttpClientProvider() 
{ 
    @Override 
    protected ClientBuilder configureClientBuilder(ClientBuilder clientBuilder) { 
        return super.configureClientBuilder(clientBuilder) 
            // override default connect timeout 
            .connectTimeout(90, TimeUnit.SECONDS)
            // override default read timeout
            .readTimeout(5, TimeUnit.MINUTES) 
            // enable compression (if using Jersey client)
            .register(org.glassfish.jersey.message.GZipEncoder.class)
            .register(org.glassfish.jersey.client.filter.EncodingFilter.class);
    }
}); 

Logging service calls

To enable logging for request and response messages, you can set the com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump property to true:

System.setProperty("com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump", "true");

By default, Bing Ads Java SDK uses Apache CXF to make service calls, which relies on Simple Logging Facade for Java for writing its logs. To output logged messages to the console, you can add the slf4j-simple implementation to your application dependencies. For example:

<dependency> 
    <groupId>org.slf4j</groupId> 
    <artifactId>slf4j-simple</artifactId> 
    <version>2.0.12</version> 
</dependency> 

See Also

Bing Ads API Client Libraries
Bing Ads API Code Examples
Bing Ads API Web Service Addresses
Handling Service Errors and Exceptions
Sandbox