Freigeben über

Introducing the Bing Ads Java SDK

  • Artikel

Update: April 3rd, 2015

We are excited to announce that our Java SDK is now out of Beta and is generally available for our developers.

 

We are excited to announce the availability of the Bing Ads Java SDK Beta today. This SDK client library will improve your Bing Ads developer experience by providing high-level access to features such as:

This post is an overview of the main features available within the Bing Ads Java SDK. You can find more details about these and other features on our MSDN page. Our Bing Ads Java SDK is distributed through Maven and the open source code can be downloaded from github.

Bulk API

Since its first announcement, the Bulk API has offered an efficient way to manage your campaigns, keywords and other entities, transferring large amounts of data up to ten times faster than traditional SOAP APIs. However, as a text-based API, the Bulk API requires a lot of work on the client side to parse and process the files containing the Bing Ads entities. On the other hand, traditional SOAP APIs can be easily accessed using an automatically generated object model.

The Bing Ads SDK closes this gap by providing an infrastructure for accessing the Bulk API using the same object model as our SOAP APIs. Here’s a feedback from one of our partners 'Marin Software' who took part in our Java SDK Beta early preview program.

“ We were able to leverage the Java SDK for a new feature that significantly improved our performance in communicating with Bing's API. The availability of the SDK greatly reduced the technical challenges of this recent feature, and we're excited to leverage it for more features on our roadmap ”  

Our SDK makes it very easy now to migrate your existing code working with the SOAP API objects to take advantage of the Bulk API. For example, one of the most popular requests from advertisers is the ability to quickly update keyword bids under their account based on their performance. Here’s how it can be done using the Bing Ads SDK:

First we instantiate a BulkServiceManager object:

BulkServiceManager = new BulkServiceManager(authorizationData);

Then download the keywords including their performance data during the last month:

DownloadParameters downloadParameters = new DownloadParameters();
downloadParameters.setDataScope(EnumSet.of(
                 DataScope.ENTITY_DATA, DataScope.ENTITY_PERFORMANCE_DATA));
ArrayList<BulkDownloadEntity> bulkDownloadEntities = new ArrayList<BulkDownloadEntity>();
bulkDownloadEntities.add(BulkDownloadEntity.KEYWORDS);
downloadParameters.setEntities(bulkDownloadEntities);
PerformanceStatsDateRange performanceStatsDateRange = new PerformanceStatsDateRange();
performanceStatsDateRange.setPredefinedTime(ReportTimePeriod.LAST_MONTH);
downloadParameters.setPerformanceStatsDateRange(performanceStatsDateRange);
BulkEntityIterable entities =  BulkService.downloadEntitiesAsync(downloadParameters, null).get();

And finally upload the keywords back, while increasing the bids by 10 for the keywords that had received more than 100 clicks:

ArrayList<BulkEntity> keywords = new ArrayList<BulkEntity>();
for(BulkEntity entity : entities){ 
    if(entity instanceof BulkKeyword && ((BulkKeyword) entity).getPerformanceData().getClicks()  > 100)  
    {
               Bid updatedBid = new Bid();
               updatedBid.setAmount(((BulkKeyword) entity).getKeyword().getBid().getAmount() + 10);
               ((BulkKeyword) entity).getKeyword().setBid(updatedBid);
               keywords.add((BulkKeyword)entity);
    }
}

The SDK also  provides an easy way to write your objects to the bulk files or parse existing bulk files. Please check out the MSDN documentation for the BulkFileReader and BulkFileWriter.

OAuth Authorization

As you may already know, Bing Ads is now actively transitioning to the OAuth Authorization model, a better and more secure way to handle user authentication than the traditional username/password authentication.

To make this transition easier for our customers, the Bing Ads SDK includes high-level implementations of standard OAuth 2.0 grant flows, including the authorization code grant flow for both web and desktop applications and the implicit grant flow for desktop applications.

For example, to start using the OAuth authorization code grant flow, you have to first instantiate the corresponding OAuth object. If you are building a web app:

OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(ClientId, ClientSecret, new URL(RedirectionUri));

Or if you are working on a desktop app:

OAuthDesktopMobileAuthCodeGrant oAuthDesktopMobileAuthCodeGrant = new OAuthDesktopMobileAuthCodeGrant(ClientId);

Then you can get the url to direct the user to the Microsoft Account authorization page:

URL authorizationEndpoint = oAuthWebAuthCodeGrant.getAuthorizationEndpoint();
response.sendRedirect(authorizationEndpoint.toString());

And once you are called back by the Microsoft Account authorization server, you can request the OAuth tokens by using the received authorization response uri:

OAuthTokens tokens = oAuthWebAuthCodeGrant.requestAccessAndRefreshTokens(new URL(request.getRequestURL() + "?" + request.getQueryString()));

When using the OAuth objects with the ServiceClient class (described in the next section), your access and refresh tokens will be automatically refreshed upon the access token expiration. You can use the NewOAuthTokensReceived event to get notified whenever new tokens are received, to make sure you always have the latest refresh token.

Please check our Getting Started Guides on MSDN for complete examples of using the OAuth classes in your web or desktop application.

SOAP APIs

One of our goals in the Bing Ads SDK is to make sure it’s easy to access the SOAP APIs without doing any additional work. We have included generated proxy classes for all of our SOAP APIs, so there is no need for API users to manually run “svcutil” or another tool of choice.

We have also included the ServiceClient class that provides uniform access to all of our SOAP services. It also handles common request header fields for you, allowing to specify the values for fields such as CustomerId, AccountId, DeveloperToken etc. in the AuthorizationData object only once.

Here is an example of initializing the AuthorizationData object:  

static AuthorizationData authorizationData;
authorizationData = new AuthorizationData();
authorizationData.setDeveloperToken(DeveloperToken);
authorizationData.setAuthentication(oAuthWebAuthCodeGrant);
//authorizationData.setAuthentication(new PasswordAuthentication(UserName, Password));
authorizationData.setAccountId(AccountId);
authorizationData.setCustomerId(CustomerId); 

The Authentication property can hold one of the OAuth Authorization objects (for authorization code grants or implicit grants, also described in the previous section) or the PasswordAuthentication object (if you want to use the user name/password authentication).

Now that we have the AuthorizationData object, we can create the ServiceClient and call API operations without passing the same information with every request: 

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

 java.lang.Long userId = null;
final GetUserRequest getUserRequest = new GetUserRequest();
getUserRequest.setUserId(userId);
User user = CustomerService.getService().getUser(getUserRequest).getUser(); 

Note that we only set the UserId field on the GetUserRequest. All other fields will be taken from the AuthorizationData object that we provided earlier. Whenever the current access token expires, ServiceClient<IService> and BulkServiceManager will request a new set of access and refresh tokens from the Microsoft Account authorization server on your behalf. Using BulkServiceManager it will happen automatically without any required interaction from your side. The tokens will be refreshed anytime you call getService() on the corresponding ServiceClient<IService> instance. You should listen for new tokens received using the NewOAuthTokensReceivedListener to always obtain the latest refresh token, and then store it securely.

Please check our Getting Started Guideson MSDN for complete examples of using the ServiceClient with the AuthorizationData and OAuth classes in your web or desktop application.

Additional Resources

Please check our MSDN pages for more information about working with the Bing Ads SDK:

Coming soon

Our .Net SDK will be out of beta and released for general availability next week. We are also currently working on the Python version of the SDK, which will be available soon.

 

Feedback

Please let us know what you think about the Bing Ads SDK by sending an email to bing_ads_sdk@microsoft.com or leaving a comment below. We want to know about your experience coding with the Bing Ads SDK and what we can do to
help you minimize your coding time and maximize conversions.