twitter-ads 0.3.4

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Tweet
+
+    # cannot instaniate Tweet, only including class methods for stats
+    extend TwitterAds::Analytics::ClassMethods
+
+    RESOURCE_COLLECTION = '/0/accounts/%{account_id}/tweet/preview'.freeze # @api private
+    RESOURCE_STATS      = '/0/stats/accounts/%{account_id}/organic_tweets'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{account_id}/tweet/preview/%{id}'.freeze # @api private
+    RESOURCE_CREATE     = '/0/accounts/%{account_id}/tweet'.freeze # @api private
+
+    class << self
+
+      # Returns an HTML preview of a tweet, either new or existing
+      #
+      # @example
+      #   Tweet.preview(account, status: 'potatoes can be deadly...')
+      #   Tweet.preview(account, id: 634798319504617472)
+      #
+      # @param client [Client] The Client object instance.
+      # @param account [Account] The Account object instance.
+      # @param opts [Hash] A hash of options.
+      #
+      # @option opts [Integer] :id The ID of an existing Tweet you want to preview.
+      # @option opts [String] :status The text of your status update, up to 140 characters.
+      # @option opts [Array] :media_ids A list of up to four media IDs to associate with the Tweet.
+      # @option opts [String] :card_id The base-36 ID of a revenue card to be embedded in the Tweet.
+      # @option opts [String] :preview_target The target to render the Tweet preview
+      #   for (eg. TWITTER_TIMELINES).
+      #
+      # @return [Array] An array containing platforms & their respective tweet previews
+      #
+      # @since 0.2.0
+      # @see https://dev.twitter.com/ads/reference/get/accounts/%3Aaccount_id/tweet/preview
+      def preview(account, opts = {})
+        resource = opts.key?(:id) ? RESOURCE : RESOURCE_COLLECTION
+        resource = resource % { account_id: account.id, id: opts.delete(:id) }
+
+        # url encodes status message if present
+        opts[:status] = URI.escape(opts[:status]) if opts.key?(:status)
+
+        # handles array to string conversion for media IDs
+        if opts.key?(:media_ids) && opts[:media_ids].respond_to?(:join)
+          opts[:media_ids] = opts[:media_ids].join(',')
+        end
+
+        response = TwitterAds::Request.new(account.client, :get, resource, params: opts).perform
+        response.body[:data]
+      end
+
+      # Creates a "Promoted-Only" Tweet using the specialized Ads API end point.
+      #
+      # @param status [String] The main Tweet body (max: 140 characters).
+      # @param opts [Hash] A hash of options.
+      #
+      # @option opts [Array] :media_ids A list of up to four media IDs to associate with the Tweet.
+      # @option opts [Integer] :as_user_id The user ID whom you are posting the Tweet on behalf of.
+      # @option opts [Boolean] :trim_user Excludes the user object from the hydrated Tweet response.
+      # @option opts [String] :video_id The Video UUID to be associated with thie Tweet.
+      # @option opts [String] :video_title An optional title to be included.
+      # @option opts [String] :video_description An optional description to be included.
+      # @option opts [String] :video_cta An optional CTA value for the associated video.
+      # @option opts [String] :video_cta_value The value for the corresponding CTA.
+      #
+      # @since 0.3.0
+      #
+      # @see https://dev.twitter.com/ads/reference/post/accounts/%3Aaccount_id/tweet
+      #
+      # @return [Hash] A hash containing the newly created Tweet object.
+      def create(account, status, opts = {})
+        params   = { status: status }.merge!(opts)
+        resource = RESOURCE_CREATE % { account_id: account.id }
+        response = TwitterAds::Request.new(account.client, :post, resource, params: params).perform
+        response.body[:data]
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+
+  # The Ads API Client class which functions as a
+  # container for basic API consumer information.
+  class Client
+
+    attr_accessor :consumer_key,
+                  :consumer_secret,
+                  :access_token,
+                  :access_token_secret,
+                  :options,
+                  :logger
+
+    # Creates a new Ads API client instance.
+    #
+    # @param consumer_key nil [String] The application consumer key value.
+    # @param consumer_secret nil [String] The application consumer secret value.
+    # @param access_token nil [String] The access token value.
+    # @param access_token_secret nil [String] The access token secret value.
+    #
+    # @param opts [Hash] An optional Hash of extended options.
+    # @option opts [Boolean] :sandbox When true, enables sandbox mode for all requests.
+    # @option opts [Boolean] :trace When true, enables verbose request tracing for all requests.
+    #
+    # @since 0.1.0
+    #
+    # @return [Client] The newly created client instance.
+    def initialize(consumer_key, consumer_secret, access_token, access_token_secret, opts = {})
+      @consumer_key        = consumer_key
+      @consumer_secret     = consumer_secret
+      @access_token        = access_token
+      @access_token_secret = access_token_secret
+      @options             = opts
+      validate
+      self
+    end
+
+    # Returns the Logger instance for request logging.
+    #
+    # @since 0.2.0
+    #
+    # @return [Logger] The logger instance.
+    def logger
+      @logger ||= Logger.new(STDOUT)
+      @logger.progname = 'twitter-ads' unless @logger.progname
+      @logger
+    end
+
+    # Returns an inspection string for the current Client instance.
+    #
+    # @example
+    #   client.inspect
+    #
+    # @since 0.1.0
+    #
+    # @return [String] The inspection string.
+    def inspect
+      "#<#{self.class.name}:0x#{object_id} consumer_key=\"#{@consumer_key}\">"
+    end
+
+    # Returns a collection of advertiser Accounts available to the current access token.
+    #
+    # @example
+    #   client.accounts
+    #   client.accounts('3ofs6l')
+    #   client.accounts('3ofs6l', with_deleted: true)
+    #
+    # @param id=nil [String] The account ID string.
+    # @param opts={} [Hash] Hash of optional values.
+    #
+    # @option opts [String] :with_deleted Indicates whether or not to included deleted objects.
+    #
+    # @since 0.1.0
+    #
+    # @return [Account] The instance of the Account object.
+    def accounts(id = nil, opts = {})
+      id ? Account.load(self, id) : Account.all(self, opts)
+    end
+
+    private
+
+    def validate
+      [:consumer_key, :consumer_secret, :access_token, :access_token_secret].each do |name|
+        fail(ArgumentError, "Error! Missing required #{name}.") unless send(name)
+      end
+    end
+  end
+
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class AppDownloadCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, 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 :name
+      property :app_country_code
+      property :iphone_app_id
+      property :iphone_deep_link
+      property :ipad_app_id
+      property :ipad_deep_link
+      property :googleplay_app_id
+      property :googleplay_deep_link
+      property :app_cta
+      property :custom_icon_media_id
+      property :custom_app_description
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/cards/app_download'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/cards/app_download/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class ImageAppDownloadCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, 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 :name
+      property :app_country_code
+      property :iphone_app_id
+      property :iphone_deep_link
+      property :ipad_app_id
+      property :ipad_deep_link
+      property :googleplay_app_id
+      property :googleplay_deep_link
+      property :app_cta
+      property :wide_app_image_media_id
+
+      RESOURCE_COLLECTION =
+        '/0/accounts/%{account_id}/cards/image_app_download'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/cards/image_app_download/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class ImageConversationCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, read_only: true
+      property :image, 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 :name
+      property :title
+      property :first_cta
+      property :first_cta_tweet
+      property :second_cta
+      property :second_cta_tweet
+      property :thank_you_text
+      property :thank_you_url
+      property :image_media_id
+
+      RESOURCE_COLLECTION =
+        '/0/accounts/%{account_id}/cards/image_conversation'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/cards/image_conversation/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class LeadGenCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, 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 :name
+      property :image_media_id
+      property :cta
+      property :fallback_url
+      property :privacy_policy_url
+      property :title
+      property :submit_url
+      property :submit_method
+      property :custom_destination_url
+      property :custom_destination_text
+      property :custom_key_screen_name
+      property :custom_key_name
+      property :custom_key_email
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/cards/lead_gen'.freeze # @api private
+      RESOURCE            = '/0/accounts/%{account_id}/cards/lead_gen/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class PromotedAccount
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+      include TwitterAds::Analytics
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :approval_status, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+      property :deleted, type: :bool, read_only: true
+
+      property :line_item_id
+      property :user_id
+      property :paused, type: :bool
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/promoted_accounts'.freeze # @api private
+      RESOURCE_STATS = '/0/stats/accounts/%{account_id}/promoted_accounts'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/promoted_accounts/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class PromotedTweet
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+      include TwitterAds::Analytics
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :approval_status, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+      property :deleted, type: :bool, read_only: true
+
+      property :line_item_id
+      property :tweet_id
+      property :paused, type: :bool
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/promoted_tweets'.freeze # @api private
+      RESOURCE_STATS      = '/0/stats/accounts/%{account_id}/promoted_tweets'.freeze # @api private
+      RESOURCE            = '/0/accounts/%{account_id}/promoted_tweets/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+      # Saves or updates the current object instance depending on the presence of `object.id`.
+      #
+      # @example
+      #   object.save
+      #
+      # @return [self] Returns the instance refreshed from the API.
+      #
+      # Note: override to handle the inconsistency of the promoted tweet endpoint. (see REVAPI-5348)
+      #
+      # @since 0.2.4
+      def save
+        # manually check for missing params (due to API discrepancy)
+        validate
+
+        # convert to `tweet_ids` param
+        params = to_params
+        params[:tweet_ids] = *params.delete(:tweet_id) if params.key?(:tweet_id)
+
+        if @id
+          resource = self.class::RESOURCE % { account_id: account.id, id: id }
+          response = Request.new(account.client, :put, resource, params: params).perform
+          from_response(response.body[:data])
+        else
+          resource = self.class::RESOURCE_COLLECTION % { account_id: account.id }
+          response = Request.new(account.client, :post, resource, params: params).perform
+          from_response(response.body[:data].first)
+        end
+      end
+
+      private
+
+      def validate
+        details = []
+
+        unless @line_item_id
+          details << { code: 'MISSING_PARAMETER',
+                       message: '"line_item_id" is a required parameter',
+                       parameter: 'line_item_id' }
+        end
+
+        unless @tweet_id
+          details << { code: 'MISSING_PARAMETER',
+                       message: '"tweet_id" is a required parameter',
+                       parameter: 'tweet_id' }
+        end
+
+        raise TwitterAds::ClientError.new(nil, details, 400) unless details.empty?
+      end
+
+    end
+
+  end
+end