Ads API v9 (#246)

* updated version to v9

* renamed/removed line item props

* moved props out of beta

* updated enums

* added support for cards endpoint

* renamed tailored audiences to custom audiences

* removed old tailored audiences endpoint

* added new cards endpoint with examples

* updated tailored audiences to custom audiences

* updated tests

* merge conflicts

Co-authored-by: John Babich <jbabich@twitter.com>

Author: tushdante

examples/audience_permissions.rb

@@ -22,10 +22,10 @@
 # load up the account instance
 account = client.accounts(ADS_ACCOUNT)
 
-tailored_audience_id = '36n4f'
+custom_audience_id = '36n4f'
 
 # fetch all permissions
-permissions = TwitterAds::TailoredAudiencePermission.all(account, tailored_audience_id)
+permissions = TwitterAds::CustomAudiencePermission.all(account, custom_audience_id)
 
 permissions.each { |data|
   p data.id
@@ -34,10 +34,10 @@
 }
 
 # create instance
-permission = TwitterAds::TailoredAudiencePermission.new(account)
+permission = TwitterAds::CustomAudiencePermission.new(account)
 
 # set required params
-permission.tailored_audience_id = tailored_audience_id
+permission.custom_audience_id = custom_audience_id
 permission.granted_account_id = '18ce54uvbwu'
 permission.permission_level = PermissionLevel::READ_ONLY
 

examples/cards.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# Copyright (C) 2019 Twitter, Inc.
+require 'twitter-ads'
+
+CONSUMER_KEY        = 'your consumer key'
+CONSUMER_SECRET     = 'your consumer secret'
+ACCESS_TOKEN        = 'user access token'
+ACCESS_TOKEN_SECRET = 'user access token secret'
+ADS_ACCOUNT         = 'ads account id'
+
+# initialize the twitter ads api client
+client = TwitterAds::Client.new(
+  CONSUMER_KEY,
+  CONSUMER_SECRET,
+  ACCESS_TOKEN,
+  ACCESS_TOKEN_SECRET
+)
+
+# load up the account instance, campaign and line item
+account = client.accounts(ADS_ACCOUNT)
+
+# create the card
+name = 'video website card'
+components = [
+  {
+    type: 'MEDIA',
+    media_key: '13_794652834998325248'
+  },
+  {
+    type: 'DETAILS',
+    title: 'Twitter',
+    destination: {
+      type: 'WEBSITE',
+      url: 'http://twitter.com/'
+    }
+  }
+]
+
+vwc = TwitterAds::Creative::Cards.new(account)
+video_website_card = vwc.create(account, name, components)
+
+# get user_id for as_user_id parameter
+user_id = TwitterRestApi::UserIdLookup.load(account, screen_name: 'your_screen_name').id
+
+# create a draft tweet using this new card
+tweet = TwitterAds::Creative::DraftTweet.new(account)
+tweet.text = 'Created from SDK'
+tweet.as_user_id = user_id
+tweet.card_uri = video_website_card.card_uri
+tweet.save

examples/tailored_audience.rb examples/custom_audience.rbexamples/tailored_audience.rb renamed to examples/custom_audience.rb

@@ -22,9 +22,9 @@
 # load up the account instance
 account = client.accounts(ADS_ACCOUNT)
 
-# create a new placeholder tailored audience
+# create a new placeholder custom audience
 audience =
-  TwitterAds::TailoredAudience.create(account, 'Test TA')
+  TwitterAds::CustomAudience.create(account, 'Test TA')
 
 # sample user
 # all values musth be sha256 hashede except 'partner_user_id'
@@ -42,6 +42,6 @@
   }
 }]
 
-# update the tailored audience
+# update the custom audience
 success_count, total_count = audience.users(user)
 print "Successfully added #{total_count} users" if success_count == total_count

lib/twitter-ads.rb

@@ -29,7 +29,7 @@
 
 require 'twitter-ads/restapi.rb'
 
-require 'twitter-ads/audiences/tailored_audience'
+require 'twitter-ads/audiences/custom_audience'
 
 require 'twitter-ads/campaign/app_list'
 require 'twitter-ads/campaign/campaign'
@@ -58,6 +58,7 @@
 
 require 'twitter-ads/creative/account_media'
 require 'twitter-ads/creative/cards_fetch'
+require 'twitter-ads/creative/cards'
 require 'twitter-ads/creative/image_app_download_card'
 require 'twitter-ads/creative/image_conversation_card'
 require 'twitter-ads/creative/media_creative'

lib/twitter-ads/account.rb

@@ -232,18 +232,18 @@ def app_lists(id = nil, opts = {})
       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.
     #
     # @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

…itter-ads/audiences/tailored_audience.rb …twitter-ads/audiences/custom_audience.rblib/twitter-ads/audiences/tailored_audience.rb renamed to lib/twitter-ads/audiences/custom_audience.rb lib/twitter-ads/audiences/tailored_audience.rb renamed to lib/twitter-ads/audiences/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,19 +19,19 @@ class TailoredAudience
 
     property :audience_size, read_only: true
     property :audience_type, read_only: true
-    property :metadata, read_only: true
-    property :owner_account_id, 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(
@@ -55,17 +55,17 @@ def initialize(account)
 
     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 }
@@ -76,7 +76,7 @@ def create(account, name)
 
     end
 
-    # Deletes the current tailored audience instance.
+    # Deletes the current custom audience instance.
     #
     # @example
     #   audience.delete!
@@ -85,7 +85,7 @@ def create(account, name)
     #
     # @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
@@ -95,11 +95,11 @@ def delete!
     # 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,
     #     [
     #       {
@@ -194,7 +194,7 @@ def load(account, tailored_audience_id, params)
     end
   end
 
-  class TailoredAudiencePermission
+  class CustomAudiencePermission
 
     include TwitterAds::DSL
     include TwitterAds::Resource
@@ -207,16 +207,16 @@ class TailoredAudiencePermission
     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
@@ -226,22 +226,22 @@ def initialize(account)
     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])
@@ -250,7 +250,7 @@ def all(account, tailored_audience_id, opts = {})
     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
@@ -261,14 +261,14 @@ def all(account, tailored_audience_id, opts = {})
     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!
@@ -281,7 +281,7 @@ def save
     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

lib/twitter-ads/campaign/line_item.rb

@@ -18,18 +18,19 @@ class LineItem < Analytics
 
     property :advertiser_domain
     property :android_app_store_identifier
+    property :audience_expansion
     property :automatically_select_bid
     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 +39,7 @@ class LineItem < Analytics
 
     # 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

lib/twitter-ads/client.rb

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