bing_ads_ruby_sdk 1.5.0 → 1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a6b39b428d7a606c0072d095766bff29b4d7c9e44dd2f825bdb2654915ad14a
-  data.tar.gz: 7d6c717dbec5df6bceeb13ec38a000bbf1252f83ce2030c1071a55fe3a8386ab
+  metadata.gz: 10064130886df96745297db7c95d5482b3127563383425554e7ee722e36e17ff
+  data.tar.gz: ffd8833ecabc68e2d6ac7760891399070bbffb6f644f79b7f71275270e5e9c95
 SHA512:
-  metadata.gz: d6232334e3e2c510825d83b9d2476ca601eae477c744e7b9b30ac637d0afc3f965127043c5465d5797ec87dc67b4c80150c52dc54f680676c7be49da1f8d6c98
-  data.tar.gz: e3ff1cc382a5099754b37fb42b7858d79c0474dcfd22faef5e05c8498ce9c61a625df852adc638d94463682beb37cbf1d715358d4fa80b6daf022510011640bf
+  metadata.gz: 5dad795cb0dba423784ad86926c397740b083201bfb9c327f04763e94f34149860d857989b2e1386008ed19d96317a9ea91655b1267f39017b32fd14d34b9388
+  data.tar.gz: b5d31b8cd1fad4f64b91debaead3daf4878d427b5d5d17639247e732eedc125a406d16968a1dd5a3d1fc4402059268d5cffa05ee6a0c96ae153836246f232154

data/Gemfile

@@ -3,4 +3,4 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in bing_ads_ruby_sdk.gemspec
 gemspec
 
-gem "standard", "1.16.1"
+gem "standard", "1.31.1"

data/README.md

@@ -16,18 +16,23 @@ Or install it yourself as:
 
     $ gem install bing_ads_ruby_sdk
 
-## Getting Started
+## Usage
+### Getting Started
 
-In order to use Bing's api you need to get your api credentials from bing. From there gem handles the oauth token generation.
+In order to use Microsoft's advertising API you need to 
+[get your API credentials from MS](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13).
 
+From there gem handles OAuth token generation.
 By default, there is only one store in the gem to store the oauth token. It's a file system based store. You can create one yourself to store credentials in a database or wherever you desire. The store class must implement `read` and `write(data)` instance methods.
 
-To get your token, run:
-```ruby
-rake bing_token:get[my_token.json,your_dev_token,your_bing_client_id]
+To get your token, run the `bing_token:get` rake task, then follow the prompts. Here's an example:
 
-```
+```shell
+bin/rake bing_token:get['credentials.json',YOUR_DEVELOPER_TOKEN,YOUR_CLIENT_ID,YOUR_CLIENT_SECRET]
 
+# For example:
+bin/rake bing_token:get['credentials.json',ABC1234,3431b6d0-a2ac-48e1-a1c5-1d0b82f3187f,SECRETVALUEHERE]
+```
 
 Then to use the api:
 ```ruby
@@ -37,13 +42,38 @@ api = BingAdsRubySdk::Api.new(
   developer_token: 'your_dev_token',
   client_id: 'your_bing_client_id'
 )
+```
+
+### Configuration
+```ruby
+BingAdsRubySdk.configure do |conf|
+  conf.log = true
+  conf.logger.level = Logger::DEBUG
+  conf.pretty_print_xml = true
+  # to filter sensitive data before logging
+  conf.filters = ["AuthenticationToken", "DeveloperToken"]
+  
+  # Optionally allow ActiveSupport::Notifications to be emitted by Excon.
+  # These notifications can then be sent on to your profiling system
+  # conf.instrumentor = ActiveSupport::Notifications 
+end
+```
+
+### Account creation and management
+If you want to create an account using the API:
+```ruby
 api.customer_management.signup_customer(
   parent_customer_id: parent_customer_id,
   customer: customer_data, # a hash with your params
   account: account_data.merge("@type" => "AdvertiserAccount")
 )
+```
+
+Otherwise you can [use existing account IDs as explained here](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-ids),
+or use the `customer_management` endpoint as explained above.
 
-# once you have your bing customer and account ids:
+Once you have your MS Advertising customer and account ids:
+```ruby
 api.set_customer(customer_id: customer_id, account_id: account_id )
 
 api.campaign_management.get_campaigns_by_account_id(account_id: account_id)
@@ -54,6 +84,8 @@ You'll see services like `customer_management` implement some methods, but not a
 The methods implemented contain additional code to ease data manipulation but any endpoint can be reached using `call` on a service.
 
 ```ruby
+@cm = api.customer_management
+
 @cm.call(:find_accounts_or_customers_info, filter: 'name', top_n: 1)
 # => { account_info_with_customer_data: { account_info_with_customer_data: [{ customer_id: "250364751", :
 
@@ -64,22 +96,76 @@ The methods implemented contain additional code to ease data manipulation but an
 
 ```
 
+### Reporting
+You can generate the report following the 
+[process recommended by Microsoft](https://learn.microsoft.com/en-us/advertising/guides/request-download-report?view=bingads-13):
+
+That would mean coding something like this:
 
-## Configure the gem
 ```ruby
-BingAdsRubySdk.configure do |conf|
-  conf.log = true
-  conf.logger.level = Logger::DEBUG
-  conf.pretty_print_xml = true
-  # to filter sensitive data before logging
-  conf.filters = ["AuthenticationToken", "DeveloperToken"]
-  
-  # Optionally allow ActiveSupport::Notifications to be emitted by Excon.
-  # These notifications can then be sent on to your profiling system
-  # conf.instrumentor = ActiveSupport::Notifications 
+submission_response = api.reporting
+  .call(:submit_generate_report,
+     account_performance_report_request: {
+       exclude_report_header: true,
+       exclude_report_footer: true,
+       exclude_column_headers: true,
+       format: "Csv",
+       aggregation: "Daily",
+       filter: nil,
+       columns: [
+         {
+           account_performance_report_column: "TimePeriod"
+         },
+         {
+           account_performance_report_column: "AccountId"
+         },
+         {
+           account_performance_report_column: "DeviceType"
+         },
+         {
+           account_performance_report_column: "Clicks"
+         }
+       ],
+       scope: {
+         # Your account ID here
+         account_ids: [{long: 1000000}]
+       },
+       time: {
+         custom_date_range_start: {
+           day: 7,
+           month: 5,
+           year: 2023
+         },
+         custom_date_range_end: {
+           day: 8,
+           month: 5,
+           year: 2023
+         }
+       }
+     }
+  )
+
+report_request_id = submission_response.fetch(:report_request_id)
+
+# Then you can poll the API to check the status of the report generation
+poll_response = api.reporting.call(:poll_generate_report, report_request_id: report_request_id)
+
+# When it is ready you can download it
+report_request_status = poll_response.fetch(:report_request_status)
+
+report_generation_status = report_request_status[:status].downcase.to_sym 
+# => One of these: :pending, :error, :success
+
+if report_generation_status == :success
+  url = report_request_status[:report_download_url]
+  # => The URL to download the report (with the library of your choice)
 end
 ```
 
+🛈 Report request example [here in the API docs](https://learn.microsoft.com/en-us/advertising/reporting-service/accountperformancereportrequest?view=bingads-13)
+
+🛈 Hint: convert parameter names from PascalCase to snake_case when consulting the API docs
+
 ## Development
 You can run `bin/console` for an interactive prompt that will allow you to experiment.
 

data/Rakefile

@@ -1,7 +1,7 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "./lib/bing_ads_ruby_sdk"
-import "tasks/bing_ads_ruby_sdk.rake"
+import "lib/bing_ads_ruby_sdk/tasks/bing_ads_ruby_sdk.rake"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/bing_ads_ruby_sdk.gemspec

@@ -4,7 +4,7 @@ require "bing_ads_ruby_sdk/version"
 
 Gem::Specification.new do |spec|
   spec.name = "bing_ads_ruby_sdk"
-  spec.required_ruby_version = ">= 2.3"
+  spec.required_ruby_version = ">= 3"
 
   spec.version = BingAdsRubySdk::VERSION
   spec.authors = %w[Effilab developers]
@@ -15,7 +15,15 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/Effilab/bing_ads_ruby_sdk"
   spec.license = "MIT"
 
-  spec.files = `git ls-files`.split($/)
+  spec.files = Dir[
+    "bing_ads_ruby_sdk.gemspec",
+    "changelog.md",
+    "README.md",
+    "Gemfile",
+    "Rakefile",
+    "LICENSE.txt",
+    "{bin,lib,tasks}/**/*"
+  ]
   spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 

data/changelog.md

@@ -1,3 +1,11 @@
+## V1.6 Release
+- Updated documentation
+- Fixed an envkey/dotenv related bug preventing the gem from starting
+- Dropped support for Ruby 2
+
+## V1.5.1 Release
+- Bug fix: Rake task missing
+
 ## V1.5.0 Release
 - Breaking: Now raises functional errors
 - Breaking: Now raises an error if not able to read the store in order to refresh the token

data/lib/Rakefile

@@ -0,0 +1,4 @@
+require "bing_ads_ruby_sdk"
+
+path = File.expand_path(__dir__)
+Dir.glob("#{path}/tasks/**/*.rake").each { |f| import f }

data/lib/bing_ads_ruby_sdk/errors/errors.rb

@@ -67,7 +67,7 @@ module BingAdsRubySdk
 
           # Call sometimes returns an empty string instead of
           # nil for empty lists
-          list.nil? || list.empty? ? nil : list
+          (list.nil? || list.empty?) ? nil : list
         end.compact
       end
 

data/lib/bing_ads_ruby_sdk/oauth2/fs_store.rb

@@ -23,7 +23,7 @@ module BingAdsRubySdk
       # @return [nil] if the file doesn't exist.
       def read
         return nil unless File.file?("./#{filename}")
-        JSON.parse(IO.read(filename))
+        JSON.parse(File.read(filename))
       end
 
       private

data/lib/bing_ads_ruby_sdk/railtie.rb

@@ -0,0 +1,13 @@
+require "bing_ads_ruby_sdk"
+require "rails"
+
+module BingAdsRubySdk
+  class Railtie < Rails::Railtie
+    railtie_name :bing_ads_ruby_sdk
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/bing_ads_ruby_sdk/string_utils.rb

@@ -7,6 +7,8 @@ module BingAdsRubySdk
     end
 
     def self.snakize(string)
+      raise "Unexpected string length : #{string.length} for string '#{string[0..200]}...'" if string.length > 1000
+
       string.gsub(MULTIPLE_CAPSREGEX, MATCHING_PATTERN)
         .gsub(SPLIT_REGEX, MATCHING_PATTERN)
         .tr("-", "_")

data/{tasks → lib/bing_ads_ruby_sdk/tasks}/bing_ads_ruby_sdk.rake

@@ -1,7 +1,11 @@
-require "dotenv/load"
+begin
+  require "dotenv/load"
+rescue LoadError
+  puts "Unable to load .env file, resuming..."
+end
 
 namespace :bing_token do
-  desc "Gets and stores Bing OAuth token in file"
+  desc "Gets OAuth token from MS and stores it in a JSON file defined by filename parameter"
   task :get, [:filename, :bing_developer_token, :bing_client_id, :bing_client_secret] do |task, args|
     filename = args[:filename] || ENV.fetch("BING_STORE_FILENAME")
     developer_token = args[:bing_developer_token] || ENV.fetch("BING_DEVELOPER_TOKEN")

data/lib/bing_ads_ruby_sdk/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module BingAdsRubySdk
-  VERSION = "1.5.0"
+  VERSION = "1.6"
   DEFAULT_SDK_VERSION = :v13
 end

data/lib/bing_ads_ruby_sdk.rb

@@ -7,8 +7,12 @@ require "bing_ads_ruby_sdk/version"
 require "bing_ads_ruby_sdk/configuration"
 require "bing_ads_ruby_sdk/api"
 require "bing_ads_ruby_sdk/string_utils"
+require "bing_ads_ruby_sdk/railtie" if defined?(Rails)
 
 module BingAdsRubySdk
+  TYPE_KEY = "@type"
+  ROOT_PATH = File.join(__dir__, "..")
+
   def self.config
     @configuration ||= BingAdsRubySdk::Configuration.new
   end
@@ -17,9 +21,9 @@ module BingAdsRubySdk
     yield(config)
   end
 
-  def self.log(level, *args, &block)
+  def self.log(level, ...)
     return unless config.log
-    config.logger.send(level, *args, &block)
+    config.logger.send(level, ...)
   end
 
   def self.root_path
@@ -29,7 +33,4 @@ module BingAdsRubySdk
   def self.type_key
     TYPE_KEY
   end
-
-  TYPE_KEY = "@type"
-  ROOT_PATH = File.join(__dir__, "..")
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bing_ads_ruby_sdk
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: '1.6'
 platform: ruby
 authors:
 - Effilab
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-04 00:00:00.000000000 Z
+date: 2023-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: signet
@@ -188,11 +188,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".circleci/config.yml"
-- ".github/.keep"
-- ".github/renovate.json"
-- ".gitignore"
-- ".rspec"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -201,6 +196,7 @@ files:
 - bin/setup
 - bing_ads_ruby_sdk.gemspec
 - changelog.md
+- lib/Rakefile
 - lib/bing_ads_ruby_sdk.rb
 - lib/bing_ads_ruby_sdk/api.rb
 - lib/bing_ads_ruby_sdk/augmented_parser.rb
@@ -216,6 +212,7 @@ files:
 - lib/bing_ads_ruby_sdk/postprocessors/snakize.rb
 - lib/bing_ads_ruby_sdk/preprocessors/camelize.rb
 - lib/bing_ads_ruby_sdk/preprocessors/order.rb
+- lib/bing_ads_ruby_sdk/railtie.rb
 - lib/bing_ads_ruby_sdk/services/ad_insight.rb
 - lib/bing_ads_ruby_sdk/services/base.rb
 - lib/bing_ads_ruby_sdk/services/bulk.rb
@@ -225,6 +222,7 @@ files:
 - lib/bing_ads_ruby_sdk/services/reporting.rb
 - lib/bing_ads_ruby_sdk/soap_client.rb
 - lib/bing_ads_ruby_sdk/string_utils.rb
+- lib/bing_ads_ruby_sdk/tasks/bing_ads_ruby_sdk.rake
 - lib/bing_ads_ruby_sdk/version.rb
 - lib/bing_ads_ruby_sdk/wsdl/v13/production/ad_insight.xml
 - lib/bing_ads_ruby_sdk/wsdl/v13/production/bulk.xml
@@ -246,83 +244,6 @@ files:
 - lib/bing_ads_ruby_sdk/wsdl/v13/test/reporting.xml
 - lib/bing_ads_ruby_sdk/wsdl/wsdl_source.txt
 - lib/bing_ads_ruby_sdk/wsdl_operation_wrapper.rb
-- spec/bing_ads_ruby_sdk/api_spec.rb
-- spec/bing_ads_ruby_sdk/errors/error_handler_spec.rb
-- spec/bing_ads_ruby_sdk/errors/errors_spec.rb
-- spec/bing_ads_ruby_sdk/header_spec.rb
-- spec/bing_ads_ruby_sdk/http_client_spec.rb
-- spec/bing_ads_ruby_sdk/oauth2/fs_store_spec.rb
-- spec/bing_ads_ruby_sdk/postprocessors/cast_long_arrays_spec.rb
-- spec/bing_ads_ruby_sdk/postprocessors/snakize_spec.rb
-- spec/bing_ads_ruby_sdk/preprocessors/camelize_spec.rb
-- spec/bing_ads_ruby_sdk/preprocessors/order_spec.rb
-- spec/bing_ads_ruby_sdk/services/bulk_spec.rb
-- spec/bing_ads_ruby_sdk/services/campaign_management_spec.rb
-- spec/bing_ads_ruby_sdk/services/customer_management_spec.rb
-- spec/bing_ads_ruby_sdk_spec.rb
-- spec/examples/1_customer_creation/customer_spec.rb
-- spec/examples/2_with_customer/budget_spec.rb
-- spec/examples/2_with_customer/campaigns_spec.rb
-- spec/examples/2_with_customer/customer_management_spec.rb
-- spec/examples/2_with_customer/uet_tags_spec.rb
-- spec/examples/3_with_uet_tag/conversion_goal_spec.rb
-- spec/examples/3_with_uet_tag/uet_tags_spec.rb
-- spec/examples/4_with_conversion_goal/conversion_goals_spec.rb
-- spec/examples/5_with_campaign/ad_extension_spec.rb
-- spec/examples/5_with_campaign/ad_group_spec.rb
-- spec/examples/5_with_campaign/campaign_criterions_spec.rb
-- spec/examples/5_with_campaign/campaign_spec.rb
-- spec/examples/6_with_ad_group/ad_group_spec.rb
-- spec/examples/6_with_ad_group/ads_spec.rb
-- spec/examples/6_with_ad_group/keywords_spec.rb
-- spec/examples/examples.rb
-- spec/fixtures/bulk/download_campaigns_by_account_ids/standard.xml
-- spec/fixtures/bulk/download_campaigns_by_account_ids/standard_response.xml
-- spec/fixtures/bulk/get_bulk_download_status/standard.xml
-- spec/fixtures/bulk/get_bulk_download_status/standard_response.xml
-- spec/fixtures/campaign_management/add_ad_extensions/standard.xml
-- spec/fixtures/campaign_management/add_ad_extensions/standard_response.xml
-- spec/fixtures/campaign_management/add_conversion_goals/standard.xml
-- spec/fixtures/campaign_management/add_conversion_goals/standard_response.xml
-- spec/fixtures/campaign_management/add_shared_entity/standard.xml
-- spec/fixtures/campaign_management/add_shared_entity/standard_response.xml
-- spec/fixtures/campaign_management/add_uet_tags/standard.xml
-- spec/fixtures/campaign_management/add_uet_tags/standard_response.xml
-- spec/fixtures/campaign_management/get_ad_extension_ids_by_account_id/standard.xml
-- spec/fixtures/campaign_management/get_ad_extension_ids_by_account_id/standard_response.xml
-- spec/fixtures/campaign_management/get_ad_extensions_associations/standard.xml
-- spec/fixtures/campaign_management/get_ad_extensions_associations/standard_response.xml
-- spec/fixtures/campaign_management/get_budgets_by_ids/standard.xml
-- spec/fixtures/campaign_management/get_budgets_by_ids/standard_response.xml
-- spec/fixtures/campaign_management/get_campaigns_by_account_id/standard.xml
-- spec/fixtures/campaign_management/get_campaigns_by_account_id/standard_response.xml
-- spec/fixtures/campaign_management/get_conversion_goals_by_ids/standard.xml
-- spec/fixtures/campaign_management/get_conversion_goals_by_ids/standard_response.xml
-- spec/fixtures/campaign_management/get_shared_entities_by_account_id/standard.xml
-- spec/fixtures/campaign_management/get_shared_entities_by_account_id/standard_response.xml
-- spec/fixtures/campaign_management/get_shared_entity_associations_by_entity_ids/standard.xml
-- spec/fixtures/campaign_management/get_shared_entity_associations_by_entity_ids/standard_response.xml
-- spec/fixtures/campaign_management/get_uet_tags_by_ids/standard.xml
-- spec/fixtures/campaign_management/get_uet_tags_by_ids/standard_response.xml
-- spec/fixtures/campaign_management/set_ad_extensions_associations/standard.xml
-- spec/fixtures/campaign_management/set_ad_extensions_associations/standard_response.xml
-- spec/fixtures/campaign_management/set_shared_entity_associations/standard.xml
-- spec/fixtures/campaign_management/set_shared_entity_associations/standard_response.xml
-- spec/fixtures/campaign_management/update_conversion_goals/standard.xml
-- spec/fixtures/campaign_management/update_conversion_goals/standard_response.xml
-- spec/fixtures/campaign_management/update_uet_tags/standard.xml
-- spec/fixtures/campaign_management/update_uet_tags/standard_response.xml
-- spec/fixtures/customer_management/find_accounts_or_customers_info/standard.xml
-- spec/fixtures/customer_management/find_accounts_or_customers_info/standard_response.xml
-- spec/fixtures/customer_management/get_account/standard.xml
-- spec/fixtures/customer_management/get_account/standard_response.xml
-- spec/fixtures/customer_management/signup_customer/standard.xml
-- spec/fixtures/customer_management/signup_customer/standard_response.xml
-- spec/fixtures/customer_management/update_account/standard.xml
-- spec/fixtures/customer_management/update_account/standard_response.xml
-- spec/spec_helper.rb
-- spec/support/spec_helpers.rb
-- tasks/bing_ads_ruby_sdk.rake
 homepage: https://github.com/Effilab/bing_ads_ruby_sdk
 licenses:
 - MIT
@@ -335,14 +256,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: Bing Ads Ruby SDK

data/.circleci/config.yml

@@ -1,54 +0,0 @@
-version: 2.1
-
-commands:
-  build:
-    steps:
-      - checkout
-      # We can't use restore_cache because we don't include a Gemfile.lock in the Gem repo
-      - run:
-          name: install dependencies
-          command: |
-            bundle install --jobs=4 --retry=3 --path vendor/bundle
-      - run: bundle exec standardrb
-      - run:
-          name: run tests
-          command: |
-            mkdir log/
-            mkdir /tmp/test-results
-            TEST_FILES="$(circleci tests glob "spec/bing_ads_ruby_sdk/**/*_spec.rb" | \
-              circleci tests split --split-by=timings)"
-
-            bundle exec rspec \
-              --format progress \
-              --format RspecJunitFormatter \
-              --out /tmp/test-results/rspec.xml \
-              --format progress \
-              $TEST_FILES
-      # collect reports
-      - store_test_results:
-          path: /tmp/test-results
-      - store_artifacts:
-          path: /tmp/test-results
-          destination: test-results
-
-jobs:
-  build_2_x:
-    docker:
-      - image: ruby:2.7.6
-    working_directory: ~/repo
-    steps:
-      - build
-
-  build_3_x:
-    docker:
-      - image: ruby:3.1.2
-    working_directory: ~/repo
-    steps:
-      - build
-
-workflows:
-  version: 2
-  build:
-    jobs:
-      - build_2_x
-      - build_3_x