Gem Version Build Status

Bing::Ads

A Ruby client for Bing Ads API that includes a proxy to all Bing Ads API web services and abstracts low level details of authentication with OAuth.

Installation

Add this line to your application's Gemfile:

gem 'bing-ads'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bing-ads

Usage

Customer Management Service

Initialization

# Authentication token is not supported in sandbox, use `username` and `password` instead
# https://msdn.microsoft.com/en-us/library/dn277356.aspx

options = {
  environment: :sandbox,
  authentication_token: '39b290146bea6ce975c37cfc23',
  developer_token: 'BBD37VB98',
  customer_id: '21027149',
  # client_settings: { logger: LOGGER::STDOUT }
}

service = Bing::Ads::API::V11::Services::CustomerManagement.new(options)

Getting accounts info

response = service.get_accounts_info

Campaign Management Service

Initialization

# Authentication token is not supported in sandbox, use `username` and `password` instead
# https://msdn.microsoft.com/en-us/library/dn277356.aspx

options = {
  environment: :sandbox,
  authentication_token: '39b290146bea6ce975c37cfc23',
  developer_token: 'BBD37VB98',
  customer_id: '21027149',
  account_id: '5278183',
  # client_settings: { logger: LOGGER::STDOUT }
}

service = Bing::Ads::API::V11::Services::CampaignManagement.new(options)

Getting campaigns

 = 5278183
response = service.()

Getting campaigns in an account by ids

 = 5278183
campaign_ids = [813721838, 813721849, 813721850]
response = service.get_campaigns_by_ids(, campaign_ids)

Adding campaigns

 = 5278183
campaigns = [
  {
    budget_type: Bing::Ads::API::V11.constants.campaign_management.budget_limit_type.daily_budget_standard,
    daily_budget: 2000,
    description: 'Amsterdam-based global campaign',
    name: '51 - Global - Chain - Mixed - N -en- Amsterdam - 100 - 26479',
    status: Bing::Ads::API::V11.constants.campaign_management.campaign_status.paused,
    time_zone: Bing::Ads::API::V11.constants.time_zones.amsterdam_berlin_bern_rome_stockholm_vienna
  },
  # ...
]

response = service.add_campaigns(, campaigns)

Updating campaigns

 = 5278183
campaigns = [
  {
    id: 813721838,
    budget_type: Bing::Ads::API::V11.constants.campaign_management.budget_limit_type.daily_budget_standard,
  },
  {
    id: 813721849,
    budget_type: Bing::Ads::API::V11.constants.campaign_management.budget_limit_type.daily_budget_standard,
  },
  # ...
]

response = service.update_campaigns(, campaigns)

Deleting campaigns

 = 5278183
campaign_ids_to_delete = [813721838, 813721813, 813721911]
response = service.delete_campaigns(, campaign_ids_to_delete)

Getting ad groups in a campaign

campaign_id = 813721838
response = service.get_ad_groups_by_campaign_id(campaign_id)

Getting ad groups in a campaign by ids

campaign_id = 813721838
ad_group_ids = [9866221838, 9866221813, 9866221911]
response = service.get_ad_groups_by_ids(campaign_id, ad_group_ids)

Adding ad groups to a campaign

# You can add a maximum of 1,000 ad groups in a single call.
# Each campaign can have up to 20,000 ad groups.
campaign_id = 813721838
ad_groups = [
  {
    ad_distribution: Bing::Ads::API::V11.constants.campaign_management.ad_distribution.search, # required
    ad_rotation: Bing::Ads::API::V11.constants.campaign_management.ad_rotation.optimize_for_clicks, # optional
    bidding_scheme: Bing::Ads::API::V11.constants.campaign_management.bidding_scheme.inherit_from_parent, # optional
    content_match_bid: 100, # optional
    end_date: '31/12/2020',
    status: Bing::Ads::API::V11.constants.campaign_management.ad_group_status.paused,
    language: Bing::Ads::API::V11.constants.languages.english,
    name: 'H=WHotelAmsterdam&AG=1723812002',
    native_bid_adjustment: -50, # optional (-100 to 900)
    remarketing_targeting_setting: Bing::Ads::API::V11.constants.campaign_management.remarketing_target_setting.bid_only, # optional
    search_bid: 100, # optional
    start_date: '5/7/2017',
  },
  # ...
  # https://msdn.microsoft.com/en-us/library/bing-ads-campaign-management-adgroup.aspx
]

response = service.add_ad_groups(campaign_id, ad_groups)

Updating ad groups in a campaign

# You can add a maximum of 1,000 ad groups in a single call.
# Each campaign can have up to 20,000 ad groups.
campaign_id = 813721838
ad_groups = [
  {
    id: 9866221838,
    status: Bing::Ads::API::V11.constants.campaign_management.ad_group_status.active
  },
  # ...
]

response = service.update_ad_groups(campaign_id, ad_groups)

Deleting ad groups from a campaign

campaign_id = 813721838
ad_group_ids_to_delete = [9866221838, 9866221839, 9866221840]
response = service.delete_ad_groups(campaign_id, ad_group_ids_to_delete)

Getting ads in an ad group

ad_group_id = 9866221838
response = service.get_ads_by_ad_group_id(ad_group_id)

Getting ads in an ad group by ids

ad_group_id = 9866221838
ad_ids = [454873284248, 454873284249, 454873284250]
response = service.get_ads_by_ids(ad_group_id, ad_ids)

Adding ads to an ad group

# You can add a maximum of 50 ads in an ad group.
ad_group_id = 9866221838
expanded_text_ads = [
  {
    type: Bing::Ads::API::V11.constants.campaign_management.ad_types.expanded_text_ad, # ExpandedTextAd
    path_1: 'Amsterdam',
    path_2: 'Hotels',
    text: 'Compare over 150 booking sites! Find guaranteed low hotel rates.',
    title_part_1: 'Hotels in Amsterdam',
    title_part_2: 'Best Deals. Book now',
    final_urls: [
      'http://www.findhotel.net/Places/Amsterdam.htm'
    ]
  },
  # ...
  # Expanded text ads
  # https://msdn.microsoft.com/en-us/library/bing-ads-campaign-management-expandedtextad.aspx
  # For other ad types:
  # https://msdn.microsoft.com/en-us/library/bing-ads-campaign-management-ad.aspx
]

# Returns IDs of ads added to ad group
# { ad_ids: [], partial_errors: [] }
response = service.add_ads(ad_group_id, expanded_text_ads)

Updating ads in an ad group

ad_group_id = 9866221838
updated_expanded_text_ads = [
  {
    id: 454873284248,
    final_urls: [
      'https://www.findhotel.net/Places/Amsterdam.htm'
    ]
  },
  # ...
]

response = service.update_ads(ad_group_id, updated_expanded_text_ads)

Deleting ads from an ad group

ad_group_id = 9866221838
ad_ids_to_delete = [454873284248, 454873284249, 454873284250]
response = service.delete_ads(ad_group_id, ad_ids_to_delete)

Getting keywords in an ad group

ad_group_id = 9866221838
response = service.get_keywords_by_ad_group_id(ad_group_id)

Getting keywords in an ad group by ids

ad_group_id = 9866221838
keyword_ids = [234873284248, 234873284249, 234873284250]
response = service.get_keywords_by_ids(ad_group_id, keyword_ids)

Adding keywords to an ad group

ad_group_id = 9866221838
keywords = [
  {
    bidding_scheme: Bing::Ads::API::V11.constants.campaign_management.bidding_scheme.inherit_from_parent,
    bid: 5,
    # optional, ad final urls used if this is not set
    final_urls: [
      'https://www.findhotel.net/Places/Amsterdam.htm?attrs=pet-friendly'
    ],
    match_type: Bing::Ads::API::V11.constants.campaign_management.match_types.exact, # also broad, content, phrase
    status: Bing::Ads::API::V11.constants.campaign_management.keyword_statuses.active,
    text: 'Pet-friendly Hotels in Amsterdam'
  },
  # ...
  # https://msdn.microsoft.com/en-us/library/bing-ads-campaign-management-keyword.aspx
  # https://msdn.microsoft.com/en-us/library/bing-ads-campaign-management-addkeywords.aspx
]

# Returns IDs of keywords added to ad group
# { keyword_ids: [], partial_errors: [] }
response = service.add_keywords(ad_group_id, keywords)

Updating keywords in an ad group

ad_group_id = 9866221838
updated_keywords = [
  {
    id: 234873284248,
    # updated attributes
  },
  # ...
]

response = service.update_keywords(ad_group_id, updated_keywords)

Deleting keywords from an ad group

ad_group_id = 9866221838
keyword_ids_to_delete = [234873284248, 234873284249, 234873284250]
response = service.delete_keywords(ad_group_id, keyword_ids_to_delete)

Bulk Service

Not yet supported

Reporting Service

Not yet supported. Use: https://github.com/FindHotel/bing-ads-reporting

Errors raised

  • Bing::Ads::API::Errors::AuthenticationParamsMissing No username/password or authentication_token.
  • Bing::Ads::API::Errors::AuthenticationTokenExpired Authentication token needs to be refreshed.
  • Bing::Ads::API::Errors::LimitError An API limit has been exceeded on a specific request. Check message for details.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run bundle exec rake install.

Tests

Endpoints were manually tested but although RSpec is installed as a test framework, there are no tests written yet.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/FindHotel/bing-ads.