google-adwords-api 0.21.0 → 0.21.1

data/examples/v201609/advanced_operations/add_html5_ad.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2015, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This code example adds an HTML5 ad to a given ad group.
+# To get ad groups, run basic_operations/get_ad_groups.rb.
+
+require 'adwords_api'
+require 'base64'
+
+def add_html5_ad(ad_group_id)
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
+
+  # The HTML5 zip file contains all the HTML, CSS, and images needed for the
+  # HTML5 ad. For help on creating an HTML5 zip file, check out Google Web
+  # Designer (https://www.google.com/webdesigner).
+  html5_url = 'http://goo.gl/9Y7qI2'
+  html5_data = AdsCommon::Http.get(html5_url, adwords.config)
+  html5_data_base64 = Base64.encode64(html5_data)
+
+  # Create a media bundle containing the zip file with all the HTML5
+  # components.
+  media_bundle = {
+    :xsi_type => 'MediaBundle',
+    :data => html5_data_base64,
+    :entry_point => 'carousel/index.html',
+    :type => 'MEDIA_BUNDLE'
+  }
+
+  # Create the template elements for the ad. You can refer to
+  # https://developers.google.com/adwords/api/docs/appendix/templateads
+  # for the list of available template fields.
+  ad_data = {
+    :unique_name => 'adData',
+    :fields => [
+      {
+        :name => 'Custom_layout',
+        :field_media => media_bundle,
+        :type => 'MEDIA_BUNDLE'
+      },
+      {
+        :name => 'layout',
+        :field_text => 'Custom',
+        :type => 'ENUM'
+      }
+    ]
+  }
+
+  html5_ad = {
+    :xsi_type => 'TemplateAd',
+    :name => 'Ad for HTML5',
+    :template_id => 419,
+    :final_urls => ['http://example.com/html5'],
+    :display_url => 'www.example.com/html5',
+    :dimensions => {
+      :width => 300,
+      :height => 250
+    },
+    :template_elements => [ad_data]
+  }
+
+  ad_group_ad = {
+    :ad_group_id => ad_group_id,
+    :ad => html5_ad,
+    :status => 'PAUSED'
+  }
+
+  operation = {
+    :operator => 'ADD',
+    :operand => ad_group_ad
+  }
+
+  response = ad_group_ad_srv.mutate([operation])
+  if response and !response.empty?
+    response[:value].each do |ad_group_ad|
+      puts "New HTML5 ad with ID %d and display url '%s' was added." %
+          [ad_group_ad[:ad][:id], ad_group_ad[:ad][:display_url]]
+    end
+  else
+    puts "No HTML5 ads were added."
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201609
+
+  begin
+    # Ad group ID to add text ads to.
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    add_html5_ad(ad_group_id)
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201609/advanced_operations/add_responsive_display_ad.rb

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This code example adds an image representing the ad using the MediaService and
+# then adds a responsive display ad to a given ad group.
+# To get ad groups, run basic_operations/get_ad_groups.rb.
+
+require 'adwords_api'
+require 'base64'
+
+def add_responsive_display_ad(ad_group_id)
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
+  media_srv = adwords.service(:MediaService, API_VERSION)
+
+  # Create an image.
+  image_url = 'https://goo.gl/3b9Wfh'
+  raw_image_data = AdsCommon::Http.get(image_url, adwords.config)
+  image = {
+    :xsi_type => 'Image',
+    :data => Base64.encode64(raw_image_data),
+    :type => 'IMAGE'
+  }
+
+  # Upload the image.
+  response = media_srv.upload([image])
+  if response and !response.empty?
+    image = response.first
+  else
+    raise StandardError, "Could not uplooad image. Aborting before creating ad."
+  end
+
+  # Create the responsive display ad.
+  responsive_display_ad = {
+    :xsi_type => 'ResponsiveDisplayAd',
+    # This ad format does not allow the creation of an image using the
+    # Image.data field. An image must first be created using the MediaService,
+    # and Image.mediaId must be populated when creating the ad.
+    :marketing_image => {
+      :media_id => image[:media_id]
+    },
+    :short_headline => 'Travel',
+    :long_headline => 'Traver the World',
+    :description => 'Take to the air!',
+    :business_name => 'Interplanetary Cruises',
+    :final_urls => ['http://www.example.com/']
+  }
+
+  # Create an ad group ad for the responsive display ad.
+  responsive_display_ad_group_ad = {
+    :ad_group_id => ad_group_id,
+    :ad => responsive_display_ad,
+    # Additional propertires (non-required).
+    :status => 'PAUSED'
+  }
+
+  # Create operation.
+  responsive_display_ad_group_ad_operations = {
+    :operator => 'ADD',
+    :operand => responsive_display_ad_group_ad
+  }
+
+  # Add the responsive display ad.
+  result = ad_group_ad_srv.mutate([responsive_display_ad_group_ad_operations])
+
+  # Display results.
+  if result && result[:value]
+    result[:value].each do |ad_group_ad|
+      puts ('New responsive display ad with id %d and short headline %s was ' +
+          'added.') % [ad_group_ad[:ad][:id], ad_group_ad[:ad][:short_headline]]
+    end
+  else
+    puts "No responsive display ads were added."
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201609
+
+  begin
+    # Ad group ID to add text ads to.
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    add_responsive_display_ad(ad_group_id)
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201609/advanced_operations/add_universal_app_campaign.rb

@@ -0,0 +1,215 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example adds a universal app campaign.
+#
+# To get campaigns, run get_campaigns.rb. To upload image assets for this
+# campaign, run upload_image.rb.
+
+require 'adwords_api'
+require 'date'
+
+def add_universal_app_campaigns()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  campaign_srv = adwords.service(:CampaignService, API_VERSION)
+  budget_srv = adwords.service(:BudgetService, API_VERSION)
+
+  # Create a budget.
+  budget = {
+    :name => 'Interplanetary budget #%d' % (Time.new.to_f * 1000).to_i,
+    :amount => {:micro_amount => 50000000},
+    :delivery_method => 'STANDARD',
+    # Universal app campaigns don't support shared budgets.
+    :is_explicitly_shared => false
+  }
+  budget_operation = {:operator => 'ADD', :operand => budget}
+
+  # Add the budget.
+  return_budget = budget_srv.mutate([budget_operation])
+  budget_id = return_budget[:value].first[:budget_id]
+
+  # Create campaigns.
+  universal_app_campaign = {
+    :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
+    :status => 'PAUSED',
+    # Set the advertising channel and subchannel types for universal app
+    # campaigns.
+    :advertising_channel_type => 'MULTI_CHANNEL',
+    :advertising_channel_sub_type => 'UNIVERSAL_APP_CAMPAIGN',
+    # Set the campaign's bidding strategy. Universal app campaigns only support
+    # the TARGET_CPA bidding strategy.
+    :bidding_strategy_configuration => {
+      :bidding_scheme => {
+        :xsi_type => 'TargetCpaBiddingScheme',
+        :target_cpa => {
+          :micro_amount => 1000000
+        }
+      }
+    },
+    # Budget (required) - note only the budget ID is required.
+    :budget => {:budget_id => budget_id},
+    # Optional fields:
+    :start_date =>
+        DateTime.parse((Date.today + 1).to_s).strftime('%Y%m%d'),
+    :end_date =>
+        DateTime.parse((Date.today + 365).to_s).strftime('%Y%m%d')
+  }
+
+  universal_app_setting = {
+    # Set the campaign's assets and ad text ideas. These values will be used to
+    # generate ads.
+    :xsi_type => 'UniversalAppCampaignSetting',
+    :app_id => 'com.interplanetarycruise.booking',
+    :description1 => 'Best Space Cruise Line',
+    :description2 => 'Visit all the planets',
+    :description3 => 'Trips 7 days a week',
+    :description4 => 'Buy your tickets now!'
+    # Optional: You can set up to 10 image assets for your campaign. See
+    # upload_image.rb for an example on how to upload images.
+    #
+    # :image_media_ids => [INSERT_IMGAGE_MEDIA_ID(s)_HERE]
+  }
+
+  # Optimize this campaign for getting new users for your app.
+  universal_app_setting[:universal_app_bidding_strategy_goal_type] =
+      'OPTIMIZE_FOR_INSTALL_CONVERSION_VOLUME'
+
+  # Optional: If you select OPTIMIZE_FOR_IN_APP_CONVERSION_VOLUME goal type,
+  # then also specify your in-app conversion types so AdWords can focus your
+  # campaign on people who are most likely to complete the corresponding in-app
+  # actions.
+  # Conversion type IDs can be retrieved using ConversionTrackerService.get.
+  #
+  # universal_app_campaign[:selective_optimization] = {
+  #   :conversion_type_ids => [INSERT_CONVERSION_TYPE_ID(s)_HERE]
+  # }
+
+  # Optional: Set the campaign settings for Advanced location options.
+  geo_setting = {
+    :xsi_type => 'GeoTargetTypeSetting',
+    :positive_geo_target_type => 'DONT_CARE',
+    :negative_geo_target_type => 'DONT_CARE'
+  }
+
+  universal_app_campaign[:settings] = [
+    universal_app_setting,
+    geo_setting
+  ]
+
+  # Construct the operation and add the campaign.
+  operations = [{
+    :operator => 'ADD',
+    :operand => universal_app_campaign
+  }]
+
+  campaigns = campaign_srv.mutate(operations)[:value]
+
+  if campaigns
+    campaigns.each do |campaign|
+      puts "Universal app campaign with name '%s' and ID %d was added." %
+          [campaign[:name], campaign[:id]]
+      set_campaign_targeting_criteria(adwords, campaign)
+    end
+  else
+    raise new StandardError, 'No universal app campaigns were added.'
+  end
+end
+
+def set_campaign_targeting_criteria(adwords, campaign)
+  campaign_criterion_service =
+      adwords.service(:CampaignCriterionService, API_VERSION)
+
+  criteria = [
+    {
+      :xsi_type => 'Location',
+      :id => 21137 # California
+    },
+    {
+      :xsi_type => 'Location',
+      :id => 2484 # Mexico
+    },
+    {
+      :xsi_type => 'Language',
+      :id => 1000 # English
+    },
+    {
+      :xsi_type => 'Language',
+      :id => 1003 # Spanish
+    }
+  ]
+
+  operations = criteria.map do |criterion|
+    {
+      :operator => 'ADD',
+      :operand => {
+        :campaign_id => campaign[:id],
+        :criterion => criterion
+      }
+    }
+  end
+
+  response = campaign_criterion_service.mutate(operations)
+
+  if response and response[:value]
+    # Display the added campaign targets.
+    response[:value].each do |criterion|
+      puts 'Campaign criteria of type "%s" and id %d was added.' % [
+          criterion[:criterion][:criterion_type],
+          criterion[:criterion][:id]
+      ]
+    end
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201609
+
+  begin
+    add_universal_app_campaigns()
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end