twitter-ads 7.0.1 → 10.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b42045b5ca461ee6f6a13ed129264351506089d23622ad2429a1a154e0b2b03f
-  data.tar.gz: 431d8797b1d1aa606c10672780708112053710b0e745e46e13bd602097c48ca9
+  metadata.gz: 41647d8c40a25ad6514610875548e84017bc742bad6dff6c3838a708dce86f1a
+  data.tar.gz: 798fd38acef31c22a0032fa9e2ff9188c5061ec3cc04834c8503b33c8a4e2ab2
 SHA512:
-  metadata.gz: fb703d3ef21d673d313c7223474e5dabbdb0d64233b88550a1135773118273a71272a38b791c927139773de1b62e639f06075fd9a25a94668e9a7cefd9bd0f82
-  data.tar.gz: bcef25e9c1a7a4d3ac331bbf901dbaefbe00121a7f0ca6e66c484f0b93585d5d8e85d7d8e46d3bfe771cc5daa584735626300a3b56743e529e4de5031aff3a36
+  metadata.gz: 1d4fffa9b3eaa288a6ef9d173fb7f6fcbb1cfd2e5286c0167be9b01f4e751179fb83d4efff294f193837c44f84a2b52a696cfa826b3e7a7ff2635696242e931b
+  data.tar.gz: 46f6c010335bbf314877e71decef4692fada6a9317436a38fa8bf31ad334a2742ddec724e61074ebefa23420490b2243d522360b7dce76907cd03f3d289a5a8a

data/README.md

@@ -52,7 +52,7 @@ This project is designed to work with Ruby 2.4.0 or greater. While it may work o
 
 Platform | Versions
 -------- | --------
-MRI | 2.4.x, 2.5.x, 2.6.x
+MRI | 2.4.x, 2.5.x, 2.6.x, 2.7, 3.0
 Rubinius | 2.4.x, 2.5.x
 
 All releases adhere to strict [semantic versioning](http://semver.org). For Example, major.minor.patch-pre (aka. stick.carrot.oops-peek).
@@ -89,7 +89,7 @@ Like the [Response](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/mast
 
 The MIT License (MIT)
 
-Copyright (C) 2019 Twitter, Inc.
+Copyright (C) 2021 Twitter, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/twitter-ads/account.rb

@@ -10,7 +10,6 @@ module TwitterAds
 
     property :id, read_only: true
     property :name, read_only: true
-    property :salt, read_only: true
     property :timezone, read_only: true
     property :timezone_switch_at, type: :time, read_only: true
     property :created_at, type: :time, read_only: true
@@ -218,6 +217,23 @@ module TwitterAds
       load_resource(LineItem, id, opts)
     end
 
+    # Returns a collection of tracking tags available to the
+    # current account.
+    #
+    # @param id [String] The LineItem ID value.
+    # @param opts [Hash] A Hash of extended options.
+    # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+    # @option opts [String] :sort_by The object param to sort the API response by.
+    # @option opts [String] :line_item_ids The object param to sort the API response by.
+    # @option opts [String] :tracking_tag_ids The object param to sort the API response by.
+    #
+    # @return A Cursor or object instance.
+    #
+    # @since 10.0.0
+    def tracking_tags(id = nil, opts = {})
+      load_resource(TrackingTag, id, opts)
+    end
+
     # Returns a collection of app lists available to the current account.
     #
     # @param id [String] The AppList ID value.
@@ -232,9 +248,9 @@ module TwitterAds
       load_resource(AppList, id, opts)
     end
 
-    # Returns a collection of tailored audiences available to the current account.
+    # Returns a collection of custom audiences available to the current account.
     #
-    # @param id [String] The TailoredAudience ID value.
+    # @param id [String] The CustomAudience ID value.
     # @param opts [Hash] A Hash of extended options.
     # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
     # @option opts [String] :sort_by The object param to sort the API response by.
@@ -242,8 +258,8 @@ module TwitterAds
     # @since 0.3.0
     #
     # @return A Cursor or object instance.
-    def tailored_audiences(id = nil, opts = {})
-      load_resource(TailoredAudience, id, opts)
+    def custom_audiences(id = nil, opts = {})
+      load_resource(CustomAudience, id, opts)
     end
 
     def authenticated_user_access

data/lib/twitter-ads/audiences/{tailored_audience.rb → custom_audience.rb}

@@ -2,7 +2,7 @@
 # Copyright (C) 2019 Twitter, Inc.
 
 module TwitterAds
-  class TailoredAudience
+  class CustomAudience
 
     include TwitterAds::DSL
     include TwitterAds::Resource
@@ -19,18 +19,19 @@ module TwitterAds
 
     property :audience_size, read_only: true
     property :audience_type, read_only: true
-    property :metadata, read_only: true
     property :partner_source, read_only: true
     property :reasons_not_targetable, read_only: true
     property :targetable, type: :bool, read_only: true
     property :targetable_types, read_only: true
+    property :permission_level, read_only: true
+    property :owner_account_id, read_only: true
 
     RESOURCE_COLLECTION  = "/#{TwitterAds::API_VERSION}/" \
-                           'accounts/%{account_id}/tailored_audiences' # @api private
+                           'accounts/%{account_id}/custom_audiences' # @api private
     RESOURCE             = "/#{TwitterAds::API_VERSION}/" \
-                           'accounts/%{account_id}/tailored_audiences/%{id}' # @api private
+                           'accounts/%{account_id}/custom_audiences/%{id}' # @api private
     RESOURCE_USERS       = "/#{TwitterAds::API_VERSION}/" \
-                           'accounts/%{account_id}/tailored_audiences/' \
+                           'accounts/%{account_id}/custom_audiences/' \
                            '%{id}/users' # @api private
 
     LIST_TYPES = %w(
@@ -54,17 +55,17 @@ module TwitterAds
 
     class << self
 
-      # Creates a new tailored audience.
+      # Creates a new custom audience.
       #
       # @example
-      #   audience = TailoredAudience.create(account, 'my list')
+      #   audience = CustomAudience.create(account, 'my list')
       #
       # @param account [Account] The account object instance.
-      # @param name [String] The tailored audience name.
+      # @param name [String] The custom audience name.
       #
       # @since 4.0
       #
-      # @return [TailoredAudience] The newly created tailored audience instance.
+      # @return [CustomAudience] The newly created custom audience instance.
       def create(account, name)
         audience = new(account)
         params = { name: name }
@@ -75,7 +76,7 @@ module TwitterAds
 
     end
 
-    # Deletes the current tailored audience instance.
+    # Deletes the current custom audience instance.
     #
     # @example
     #   audience.delete!
@@ -84,21 +85,21 @@ module TwitterAds
     #
     # @since 0.3.0
     #
-    # @return [self] Returns the tailored audience instance refreshed from the API.
+    # @return [self] Returns the custom audience instance refreshed from the API.
     def delete!
       resource = RESOURCE % { account_id: account.id, id: id }
       response = Request.new(account.client, :delete, resource).perform
       from_response(response.body[:data])
     end
 
-    # This is a private API and requires whitelisting from Twitter.
+    # This is a private API and requires allowlisting from Twitter.
     #
     # This endpoint will allow partners to add, update and remove users from a given
-    # tailored_audience_id.
+    # custom_audience_id.
     # The endpoint will also accept multiple user identifier types per user as well.
     #
     # @example
-    #   tailored_audience.users(
+    #   custom_audience.users(
     #     account,
     #     [
     #       {
@@ -137,9 +138,63 @@ module TwitterAds
       [success_count, total_count]
     end
 
+    # Retrieves the entites targeting the current tailored audience instance.
+    #
+    # @example
+    #   audience.targeted(with_active=true)
+    #
+    # @param with_active [bool] Include active/inactive
+    #
+    # @since 8.0.0
+    #
+    # @return [self] Returns a Cursor instance of the targeted entities.
+    def targeted(opts = {})
+      validate_loaded
+      params = {}.merge!(opts)
+      TargetedTailoredAudience.load(account, id, params)
+    end
+
+    def validate_loaded
+      raise ArgumentError.new(
+        "Error! #{self.class} object not yet initialized, " \
+        "call #{self.class}.load first") if id.nil?
+    end
+  end
+
+  class TargetedTailoredAudience
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+
+    attr_reader :account
+
+    # read-only
+    property :campaign_id, read_only: true
+    property :campaign_name, read_only: true
+    property :line_items, read_only: true
+
+    RESOURCE_TARGETED = "/#{TwitterAds::API_VERSION}/" \
+                        'accounts/%{account_id}/tailored_audiences/%{id}/targeted' # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    class << self
+
+      def load(account, tailored_audience_id, params)
+        resource = RESOURCE_TARGETED % { account_id: account.id, id: tailored_audience_id }
+        request = TwitterAds::Request.new(account.client,
+                                          :get,
+                                          resource,
+                                          params: params)
+        Cursor.new(self, request, init_with: [account])
+      end
+    end
   end
 
-  class TailoredAudiencePermission
+  class CustomAudiencePermission
 
     include TwitterAds::DSL
     include TwitterAds::Resource
@@ -152,16 +207,16 @@ module TwitterAds
     property :deleted, type: :bool, read_only: true
 
     property :id
-    property :tailored_audience_id
+    property :custom_audience_id
     property :granted_account_id
     property :permission_level
 
     RESOURCE_COLLECTION  = "/#{TwitterAds::API_VERSION}/" \
-                           'accounts/%{account_id}/tailored_audiences/' \
-                           '%{tailored_audience_id}/permissions' # @api private
+                           'accounts/%{account_id}/custom_audiences/' \
+                           '%{custom_audience_id}/permissions' # @api private
     RESOURCE             = "/#{TwitterAds::API_VERSION}/" \
-                           'accounts/%{account_id}/tailored_audiences/' \
-                           '%{tailored_audience_id}/permissions/%{id}' # @api private
+                           'accounts/%{account_id}/custom_audiences/' \
+                           '%{custom_audience_id}/permissions/%{id}' # @api private
 
     def initialize(account)
       @account = account
@@ -171,22 +226,22 @@ module TwitterAds
     class << self
 
       # Retrieve details for some or
-      # all permissions associated with the specified tailored audience.
+      # all permissions associated with the specified custom audience.
       #
       # @exapmle
-      #   permissions = TailoredAudiencePermission.all(account, '36n4f')
+      #   permissions = CustomAudiencePermission.all(account, '36n4f')
       #
       # @param account [Account] The account object instance.
-      # @param tailored_audience_id [String] The tailored audience id.
+      # @param custom_audience_id [String] The custom audience id.
       #
       # @since 5.2.0
       #
-      # @return [TailoredAudiencePermission] The tailored audience permission instance.
-      def all(account, tailored_audience_id, opts = {})
+      # @return [CustomAudiencePermission] The custom audience permission instance.
+      def all(account, custom_audience_id, opts = {})
         params = {}.merge!(opts)
         resource = RESOURCE_COLLECTION % {
           account_id: account.id,
-          tailored_audience_id: tailored_audience_id
+          custom_audience_id: custom_audience_id
         }
         request = Request.new(account.client, :get, resource, params: params)
         Cursor.new(self, request, init_with: [account])
@@ -195,7 +250,7 @@ module TwitterAds
     end
 
     # Saves or updates the current object instance
-    # depending on the presence of `object.tailored_audience_id`.
+    # depending on the presence of `object.custom_audience_id`.
     #
     # @exapmle
     #   object.save
@@ -206,14 +261,14 @@ module TwitterAds
     def save
       resource = RESOURCE_COLLECTION % {
         account_id: account.id,
-        tailored_audience_id: tailored_audience_id
+        custom_audience_id: custom_audience_id
       }
       params = to_params
       response = Request.new(account.client, :post, resource, params: params).perform
       from_response(response.body[:data])
     end
 
-    # Deletes the current or specified tailored audience permission.
+    # Deletes the current or specified custom audience permission.
     #
     # @example
     #   object.delete!
@@ -226,7 +281,7 @@ module TwitterAds
     def delete!
       resource = RESOURCE % {
         account_id: account.id,
-        tailored_audience_id: tailored_audience_id,
+        custom_audience_id: custom_audience_id,
         id: @id
       }
       response = Request.new(account.client, :delete, resource).perform

data/lib/twitter-ads/campaign/campaign.rb

@@ -23,6 +23,7 @@ module TwitterAds
     property :end_time, type: :time
     property :start_time, type: :time
     property :entity_status
+    property :effective_status
     property :currency
     property :standard_delivery
     property :daily_budget_amount_local_micro

data/lib/twitter-ads/campaign/line_item.rb

@@ -18,18 +18,18 @@ module TwitterAds
 
     property :advertiser_domain
     property :android_app_store_identifier
-    property :automatically_select_bid
+    property :audience_expansion
     property :bid_amount_local_micro
-    property :bid_unit
+    property :bid_strategy
     property :campaign_id
     property :categories
-    property :charge_by
     property :end_time, type: :time
     property :entity_status
+    property :goal
     property :ios_app_store_identifier
     property :name
     property :objective
-    property :optimization
+    property :pay_by
     property :placements
     property :primary_web_event_tag
     property :product_type
@@ -38,9 +38,6 @@ module TwitterAds
 
     # beta (not yet generally available)
     property :advertiser_user_id
-    property :bid_type
-    property :tracking_tags
-    property :audience_expansion
 
     # sdk only
     property :to_delete, type: :bool
@@ -95,5 +92,8 @@ module TwitterAds
       id ? TargetingCriteria.load(account, id, opts) : TargetingCriteria.all(account, @id, opts)
     end
 
+    def tracking_tags(id = nil, opts = {})
+      id ? TrackingTag.load(account, id, opts) : TrackingTag.all(account, @id, opts)
+    end
   end
 end

data/lib/twitter-ads/campaign/targeting_criteria.rb

@@ -21,6 +21,7 @@ module TwitterAds
     property :line_item_id
     property :targeting_type
     property :targeting_value
+    property :operator_type
     property :tailored_audience_expansion, type: :bool
     property :location_type
 

data/lib/twitter-ads/campaign/tracking_tags.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+module TwitterAds
+  class TrackingTag
+
+    include TwitterAds::DSL
+    include TwitterAds::Resource
+    include TwitterAds::Persistence
+
+    attr_reader :account
+
+    property :id, read_only: true
+    property :deleted, type: :bool, read_only: true
+    property :created_at, type: :time, read_only: true
+    property :updated_at, type: :time, read_only: true
+
+    property :line_item_id
+    property :tracking_tag_type
+    property :tracking_tag_url
+
+    # sdk only
+    property :to_delete, type: :bool
+
+    RESOURCE_COLLECTION  = "/#{TwitterAds::API_VERSION}/" \
+                           'accounts/%{account_id}/tracking_tags' # @api private
+    RESOURCE             = "/#{TwitterAds::API_VERSION}/" \
+                           'accounts/%{account_id}/tracking_tags/%{id}' # @api private
+
+    def initialize(account)
+      @account = account
+      self
+    end
+
+    # Creates a new Tracking Tag
+    #
+    # @param line_item_id [String] The line item id to create tags for.
+    # @param tracking_tag_url [String] tracking tag URL.
+    #
+    # @return [self] Returns the instance refreshed from the API
+    def create(line_item_id, tracking_tag_url)
+      resource = self.class::RESOURCE_COLLECTION % { account_id: account.id }
+      params = to_params.merge!(
+        line_item_id: line_item_id,
+        tracking_tag_url: tracking_tag_url,
+        tracking_tag_type: 'IMPRESSION_TAG'
+      )
+      response = Request.new(account.client, :post, resource, params: params).perform
+      from_response(response.body[:data])
+    end
+
+    class << self
+
+      # Returns a Cursor instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param line_item_ids [String] A String or String array of Line Item IDs.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [Cursor] A Cusor object ready to iterate through the API response.
+      #
+      # @since 0.3.1
+      # @see Cursor
+      # @see https://dev.twitter.com/ads/basics/sorting Sorting
+      def all(account, line_item_ids, opts = {})
+        if !line_item_ids.empty?
+          params = { line_item_ids: Array(line_item_ids).join(',') }.merge!(opts)
+        end
+        resource = RESOURCE_COLLECTION % { account_id: account.id }
+        request = Request.new(account.client, :get, resource, params: params)
+        Cursor.new(self, request, init_with: [account])
+      end
+
+      # Returns an object instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param id [String] The ID of the specific object to be loaded.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [self] The object instance for the specified resource.
+      #
+      # @since 0.3.1
+      def load(account, id, opts = {})
+        params   = { with_deleted: true }.merge!(opts)
+        resource = RESOURCE % { account_id: account.id, id: id }
+        response = Request.new(account.client, :get, resource, params: params).perform
+        new(account).from_response(response.body[:data])
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/client.rb

@@ -3,7 +3,7 @@
 
 module TwitterAds
 
-  API_VERSION = '7'
+  API_VERSION = '10'
 
   # The Ads API Client class which functions as a
   # container for basic API consumer information.

data/lib/twitter-ads/creative/cards.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class Cards
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :card_uri, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :deleted, type: :bool, read_only: true
+      property :updated_at, type: :time, read_only: true
+      # these are writable, but not in the sense that they can be set on an object and then saved
+      property :name, read_only: true
+      property :components, read_only: true
+
+      RESOURCE = "/#{TwitterAds::API_VERSION}/" +
+                 'accounts/%{account_id}/cards' # @api private
+
+      def load(*)
+        raise ArgumentError.new(
+          "'Cards' object has no attribute 'load'")
+      end
+
+      def reload(*)
+        raise ArgumentError.new(
+          "'Cards' object has no attribute 'reload'")
+      end
+
+      def create(account, name, components)
+        resource = RESOURCE % { account_id: account.id }
+        params = { 'name': name, 'components': components }
+        headers = { 'Content-Type' => 'application/json' }
+        response = Request.new(account.client,
+                               :post,
+                               resource,
+                               headers: headers,
+                               body: params.to_json).perform
+        from_response(response.body[:data])
+      end
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/creative/cards_fetch.rb

@@ -35,10 +35,8 @@ module TwitterAds
       property :image, read_only: true
       property :image_display_height, read_only: true
       property :image_display_width, read_only: true
-      property :ipad_app_id, read_only: true
-      property :ipad_deep_link, read_only: true
-      property :iphone_app_id, read_only: true
-      property :iphone_deep_link, read_only: true
+      property :ios_app_store_identifier, read_only: true
+      property :ios_deep_link, read_only: true
       property :name, read_only: true
       property :recipient_user_id, read_only: true
       property :second_choice, read_only: true

data/lib/twitter-ads/creative/image_app_download_card.rb

@@ -26,10 +26,8 @@ module TwitterAds
       property :app_cta
       property :googleplay_app_id
       property :googleplay_deep_link
-      property :iphone_app_id
-      property :iphone_deep_link
-      property :ipad_app_id
-      property :ipad_deep_link
+      property :ios_app_store_identifier
+      property :ios_deep_link
       property :name
       property :media_key
 

data/lib/twitter-ads/creative/promoted_tweet.rb

@@ -48,7 +48,7 @@ module TwitterAds
 
         # convert to `tweet_ids` param
         params = to_params
-        params[:tweet_ids] = *params.delete(:tweet_id) if params.key?(:tweet_id)
+        params[:tweet_ids] = params.delete(:tweet_id) if params.key?(:tweet_id)
 
         if @id
           raise TwitterAds::NotFound.new(nil, 'Method PUT not allowed.', 404)

data/lib/twitter-ads/creative/video_app_download_card.rb

@@ -25,10 +25,8 @@ module TwitterAds
       property :country_code
       property :app_cta
       property :poster_media_key
-      property :ipad_app_id
-      property :ipad_deep_link
-      property :iphone_app_id
-      property :iphone_deep_link
+      property :ios_app_store_identifier
+      property :ios_deep_link
       property :googleplay_app_id
       property :googleplay_deep_link
       property :name

data/lib/twitter-ads/cursor.rb

@@ -56,13 +56,13 @@ module TwitterAds
     # @return [Cursor] The current Cursor instance.
     #
     # @since 0.1.0
-    def each(offset = 0)
+    def each(offset = 0, &block)
       return to_enum(:each, offset) unless block_given?
       @collection[offset..-1].each { |element| yield(element) }
       unless exhausted?
         offset = [@collection.size, offset].max
         fetch_next
-        each(offset, &Proc.new)
+        each(offset, &block)
       end
       self
     end