Merge f974fde into 267f120

README.md

@@ -33,6 +33,7 @@ Unsplash.configure do |config|
   config.application_id     = "YOUR APPLICATION ID"    
   config.application_secret = "YOUR APPLICATION SECRET"
   config.application_redirect_uri = "https://your-application.com/oauth/callback"
+  config.utm_source = "alices_terrific_client_app"
 end
 ```
 

lib/unsplash/configuration.rb

@@ -4,6 +4,7 @@ class Configuration # :nodoc:
     attr_accessor :application_secret
     attr_accessor :application_redirect_uri
     attr_accessor :logger
+    attr_accessor :utm_source
     attr_writer   :test
 
     def initialize

lib/unsplash/connection.rb

@@ -22,8 +22,8 @@ def initialize(version: DEFAULT_VERSION, api_base_uri: DEFAULT_API_BASE_URI, oau
       @application_secret = Unsplash.configuration.application_secret
       @api_version        = version
       @api_base_uri       = api_base_uri
-      
-      oauth_base_uri     = oauth_base_uri
+
+      oauth_base_uri = oauth_base_uri
       @oauth = ::OAuth2::Client.new(@application_id, @application_secret, site: oauth_base_uri) do |http|
         http.request :multipart
         http.request :url_encoded
@@ -100,6 +100,13 @@ def delete(path, params = {})
     def request(verb, path, params = {})
       raise ArgumentError.new "Invalid http verb #{verb}" if ![:get, :post, :put, :delete].include?(verb)
 
+      params.merge!(utm_params)
+
+      if !Unsplash.configuration.utm_source
+        url = "https://community.unsplash.com/developersblog/unsplash-api-guidelines"
+        Unsplash.configuration.logger.warn "utm_source is required as part of API Terms: #{url}"
+      end
+
       headers = {
         "Accept-Version" => @api_version
         # Anything else? User agent?
@@ -110,7 +117,6 @@ def request(verb, path, params = {})
 
         param_key = verb == :post ? :body : :params
         @oauth_token.public_send(verb,  @api_base_uri + path, param_key => params, headers: headers)
-
       else
         self.class.public_send verb, path, query: params, headers: public_auth_header
       end
@@ -134,6 +140,14 @@ def public_auth_header
       { "Authorization" => "Client-ID #{@application_id}" }
     end
 
+    def utm_params
+      {
+        utm_source:   Unsplash.configuration.utm_source || "api_app",
+        utm_medium:   "referral",
+        utm_campaign: "api-credit"
+      }
+    end
+
     def refresh_token!
       return if !@oauth_token.expired?
 

spec/lib/connection_spec.rb

@@ -4,6 +4,45 @@
 
   let(:connection) { Unsplash::Client.connection }
 
+  describe "utm params", utm: true do
+    before :each do
+      response = double("response", status: 200, headers: {})
+      allow(Unsplash::Connection).to receive(:get).and_return(response)
+      Unsplash.configuration.logger = double("logger", warn: nil)
+    end
+
+    after :each do
+      Unsplash.configuration.utm_source = "unsplash_rb_specs"
+      Unsplash.configuration.logger = Logger.new(STDOUT)
+    end
+
+    it "warns if you don't have a utm_source" do
+      Unsplash.configuration.utm_source = nil
+      connection.get("/example.json")
+      expect(Unsplash.configuration.logger).to have_received(:warn)
+    end
+
+    it "does not warn if you do have a utm_source" do
+      Unsplash.configuration.utm_source = "my_app"
+      connection.get("/example.json")
+      expect(Unsplash.configuration.logger).to_not have_received(:warn)
+    end
+
+    it "appends the utm params" do
+      headers = { "Authorization"=> "Client-ID #{Unsplash.configuration.application_id}" }
+      params = {
+        foo: "bar",
+        utm_source:   "my_app",
+        utm_medium:   "referral",
+        utm_campaign: "api-credit"
+      }
+
+      Unsplash.configuration.utm_source = "my_app"
+      connection.get("/example.json", { foo: "bar" })
+      expect(Unsplash::Connection).to have_received(:get).with("/example.json", query: params, headers: headers)
+    end
+  end
+
   describe "#extract_token" do
     context "with an established connection" do
       it "returns @oauth_token converted to a hash" do

spec/spec_helper.rb

@@ -8,6 +8,7 @@
 Unsplash.configure do |config|
   config.application_id = "baaa6a1214d50b3586bec6e06157aab859bd4d86dc0b755360f103f38974edc3"
   config.application_secret = "bb834160d12304045c55d0c0ec2eb0fe62a5fe249bc1a392386120d55eb2793a"
+  config.utm_source = "unsplash_rb_specs"
 end
 
 VCR.configure do |config|
@@ -26,12 +27,15 @@
 
   config.order = "random"
 
-  config.before :each do
+  config.before :each do |example|
     Unsplash::Client.connection = Unsplash::Connection.new(
                                   api_base_uri:   "http://api.lvh.me:3000",
                                   oauth_base_uri: "http://www.lvh.me:3000")
-  end
 
+    if !example.metadata[:utm]
+      allow_any_instance_of(Unsplash::Connection).to receive(:utm_params).and_return({})
+    end
+  end
 end