talkable 0.0.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: e94689a0311b0f5980c51d6c3b3c59eeaad486cd
-  data.tar.gz: 2c75680682ea43977ec09be2593777b26a0b73b7
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Y2MzNjExMDczNTIxNjUwMzA4YWNjYTY1M2MzMzg2Y2M1NDAyM2YxNg==
+  data.tar.gz: !binary |-
+    NTdmZTFiYTIwNzZhNDJmNjhhOWVlNmJkZWQwNzNhYTc2MGNhMTk4Mw==
 SHA512:
-  metadata.gz: 832d25a3e582759ee9805ea37aae94c4c4d86dedf42b9da87a21020f4908930ae55eb5bb224a886ad637787449b5c452a69914575f9dcadf6aa1f699141984b9
-  data.tar.gz: 604b1781a85154c1f744bcdd7c607927ed0ca9fa74972196eb8ea93c22709d3c5b8b0a6975148d5a6a2b0810e0ac37a39a0fe53231a5446e5c0dfebcc21d056d
+  metadata.gz: !binary |-
+    NmNlMGVjMWRiOTZhZTMzOTZhMjZhNGI0ODBhYzRmYzczYjdlOGZkOTg3NDE1
+    NDg3ODIyMzBiMGFhMzMxMzZmMjQ0NTA0NWQ3MWQyOGE5YTFiZTdiZmU1MjVj
+    MGJlYmJjMWFkNzk3M2MwZmZhZjRlNzdjNTQwNDA2MjViNmVhMzA=
+  data.tar.gz: !binary |-
+    OTBjZDU2NDJhYzYzZWU5NGMxOTZmZGNkMzhmM2NkMjMzODY0ODQzMDg5NDU5
+    M2I0ZjNmNzk0YWVjN2ViNzc2MmIyMDRjMDYxZGZjODc0ZWE5YjUxMTc4YWM3
+    OTExYzhhOTYzZGI1N2Q4Nzk0YjQyZWZiNmY0NWQ3ODNhOGJiYWI=

data/.gitignore

@@ -43,8 +43,10 @@ build-iPhoneSimulator/
 # for a library or gem, you might want to ignore these files since the code is
 # intended to run in multiple environments; otherwise, check them in:
 # Gemfile.lock
-# .ruby-version
-# .ruby-gemset
+.ruby-version
+.ruby-gemset
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+.DS_Store

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in testic.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,126 @@
+PATH
+  remote: .
+  specs:
+    talkable (0.9.0)
+      furi (~> 0.2)
+      hashie (~> 3.4)
+      rack (>= 1.5.2, < 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (4.2.7.1)
+      actionview (= 4.2.7.1)
+      activesupport (= 4.2.7.1)
+      rack (~> 1.6)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (4.2.7.1)
+      activesupport (= 4.2.7.1)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activesupport (4.2.7.1)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.4.0)
+    ammeter (1.1.3)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-rails (>= 2.2)
+    builder (3.2.2)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    erubis (2.7.0)
+    furi (0.2.0)
+    haml (4.0.7)
+      tilt
+    hashdiff (0.3.0)
+    hashie (3.4.4)
+    i18n (0.7.0)
+    json (1.8.3)
+    loofah (2.0.3)
+      nokogiri (>= 1.5.9)
+    mini_portile2 (2.1.0)
+    minitest (5.9.0)
+    nokogiri (1.6.8)
+      mini_portile2 (~> 2.1.0)
+      pkg-config (~> 1.1.7)
+    pkg-config (1.1.7)
+    rack (1.6.4)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.7)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (4.2.7.1)
+      actionpack (= 4.2.7.1)
+      activesupport (= 4.2.7.1)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (11.2.2)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.1)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-rails (3.5.2)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    safe_yaml (1.0.4)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tilt (2.0.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    webmock (2.1.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ammeter
+  bundler (~> 1.12)
+  haml
+  json (~> 1.8.3)
+  rake (~> 11.2)
+  rspec (~> 3.4)
+  simplecov (~> 0.12)
+  talkable!
+  webmock (~> 2.1)
+
+BUNDLED WITH
+   1.12.5

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Talkable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -1,12 +1,23 @@
-# Talkable Referral Programe API Gem
+# Talkable Referral Program API Gem
+[![](https://ci.solanolabs.com:443/Talkable/talkable-ruby/badges/branches/master?badge_token=c2445aee31992aafe3d8fda62fcde2708f6254f6)](https://ci.solanolabs.com:443/Talkable/talkable-ruby/suites/484176)
 
 Talkable Ruby Gem to make your own referral program in Sinatra or Rails application
 
+## Demo
 
+Example of usage at http://github.com/talkable/talkable-spree-example
 
-## Demo
+Live demo available at http://spree-example.talkable.com
+
+## Requirements
+
+Gem requires:
+ - `Ruby` version since `1.9.3`
+ - `Rack` version since `1.5.2`
 
-Take a spree demo app and intall Talkable
+Gem supports:
+ - `Ruby on Rails` since `4.0.0`
+ - `Sinatra` since `1.4.0`
 
 ## Intallation
 
@@ -14,232 +25,180 @@ Take a spree demo app and intall Talkable
 gem "talkable"
 ```
 
-## Using Generator
+### Step by step instruction
 
-``` sh
-rails generate talkable:install
-Your talkable site slug (http://talkable.com): 
-You API token (http://talkable.com/sites/zz/edit):
-Do you want a different site to be used for non-production env? (y/n)
-Your staging site slug:
-Your staging site API token:
+- [Setup configuration file __*__](#configuration)
+- [Add Middleware __*__](#add-talkable-middleware)
+- [Load an offer __*__](#load-an-offer)
+- [Display a share page __*__](#display-an-offer-inside-view)
+- [Integrate Conversion Points](#integrate-conversion-points)
+ - [Registering a purchase](#registering-a-purchase)
+ - [Registering other events](#registering-other-events)
+
+__*__ - Automated in Ruby On Rails by using the generator
 
+## Using the Ruby On Rails Generator
 
-create config/initializers/talkable.rb
-update app/controllers/application_controller.rb
+Talkable gem provides Ruby On Rails generator to automate an integration process.
 
-create app/controllers/talkable_invite.rb
-create app/views/talkable_invite/show.html.erb
-update app/layouts/application.html.erb # floating widget install
-update app/layouts/_talkable_floating_widget.html.erb
-update config/routes.rb
+``` sh
+rails generate talkable:install
+```
+``` sh
+Your Talkable site slug: spree-example
+Your Talkable API Key: SOME-API-KEY
+Do you have a custom domain? [Y/n] n
+```
+``` sh
+      create  config/initializers/talkable.rb
+      insert  app/controllers/application_controller.rb
+      insert  app/controllers/application_controller.rb
+      create  app/views/shared
+      create  app/views/shared/_talkable_offer.html.erb
+      insert  app/views/layouts/application.html.erb
+      create  app/controllers/invite_controller.rb
+      create  app/views/invite/show.html.erb
+       route  get '/invite' => 'invite#show'
 ```
 
 ## Configuration
 
 ``` ruby
-Talkable.configure do |c|
-  # required
-  c.site_slug = 'hello'
-  # or
-  c.site_slug = Rails.env.production? ? "hello" : "hello-staging"
-  # required
-  c.api_token = Rails.env.production? ? "1235" : "6789" 
-  # required
-  c.server = 'http://invite.site.com' # fetched from site settings automatically using generator
-  # optional
-  c.js_integration_library = 'http://d2jj/integration/hello.js'  # default
-end
-```
-
+Talkable.configure do |config|
+  # site slug is taken form ENV["TALKABLE_SITE_SLUG"]
+  config.site_slug  = "spree-example"
 
+  # api key is taken from ENV["TALKABLE_API_KEY"]
+  # config.api_key  =
 
-``` ruby
-class ApplicationController < ActionController::Base
-
-  initialize_talkable_api
+  # custom server address - by default https://www.talkable.com
+  # config.server   =
 
+  # manually specified per-client integration library
+  # config.js_integration_library =
 end
 
-# GEM internals
-class Talkable
-  module ActionControllerExtension
-    def self.initialize_talkable_api
-      before_action :talkable_before_request
-    end
-
-    def talkable_before_request
-      cookies[:talkable_visitor_uuid] = params[:talkable_visitor_uuid] || talkable_visitor_uuid
-      Talkable.with_uuid(talkable_visitor_uuid) do
-        yield
-      end
-    end
-
-    def talkable_visitor_uuid
-      cookies[:talkable_visitor_uuid] ||= Talkable.find_or_generate_uuid
-    end
-  end
-end
 ```
 
+## Manual Integration
 
-
-
-## API
-
-Full API support according to DOC
-
+### Add Talkable Middleware
 
 ``` ruby
-origin = Talkable::API.register_purchase(
-    {
-      email: 'a@b.com',
-      subtotal: 100.53,
-      coupon_codes: [],
-      traffic_source: 'zz'
-    },
-    )
-origin = Talkable::API.register_event()
-origin = Talkable::API.register_affiliate_member(
-offer = origin.offer
-    {
-      email: '...'
-      sharing_channels: ['facebook', 'embedded_email', 'sms', 'other']
-    }
-    )
-
-offer.claim_links # =>
-                  # {
-                  #   twitter: "http://invite.site.com/x/12356"
-                  #   facebook: "http://invite.site.com/x/12356"
-                  #   embedded_email: "http://invite.site.com/x/12356"
-                  #   twitter: "http://invite.site.com/x/12356"
-                  # }
+  class Application < Rails::Application
+    config.middleware.use Talkable::Middleware
+  end
 ```
 
-## AD Offer Share page
+### Load an offer
 
+Floating widget at every page
 
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :load_talkable_offer
 
-User facing GEM API
+  protected
 
-``` erb
-<%= offer.advocate_share_iframe %>
+  def load_talkable_offer
+    origin = Talkable.register_affiliate_member(campaign_tags: 'popup')
+    @offer ||= origin.offer if origin
+  end
 
+end
 ```
 
-Generated code:
+or invite page at specific path
 
-
-```  html
-<div class='talkable-offer-xxx'>
-  <!-- result of the JS evaluation - not ruby evaluation -->
-  <iframe src="https://invite.site.com/x/38828?current_visitor_uuid=<uuid>"></iframe>
-</div>
-
-<script>
-_talkableq.push(['init', {
-  server: '...',
-  site_id: '...',
-  visitor_uuid: '...'
-}])
-_talkableq.push(['show_offer'], "https://invite.site.com/x/38828", {container: 'talkable-offer-xxx'})
-</script>
+```ruby
+class InviteController < ApplicationController
+  def show
+    origin = Talkable.register_affiliate_member(campaign_tags: 'invite')
+    @offer = origin.offer if origin
+  end
+end
 ```
 
-## integration.js extension
+### Getting information about an offer
 
-`integration.js` additions. Suppose to be never used directly if using talkable gem
-
-``` js
-talkable.showOffer(offer.show_url)
+```ruby
+offer = origin.offer
+offer.claim_links # => { facebook: "https://www.talkable.com/x/kqiYhR", sms: "https://www.talkable.com/x/PFxhNB" }
 ```
 
+### Display an offer inside view
 
-## Self-Serve UI
-
+Provide iframe options to show a share page in specific place
 
-``` ruby
-offer.configure(
-  facebook: {
-    title: ['An offer for all my friends', 'Claim your reward'], # AB test
-    description: 'Click this link and get #{campaign.friend_incentive.description} off on the merchant.com'
-    image: "http://merchant.com/assets/fb_image.jpg"
-  },
-  twitter: {
-    message: 'Click #{offer.claim_links.twitter} and get {{friend_incentive.description}} off on the merchant.com'
-  },
-)
-
-
-offer.configure(
-  twitter: {
-    message: 'Click #{offer.claim_links.twitter} and get {{friend_incentive.description}} off on the merchant.com'
-  },
-
-)
+```erb
+<div id="talkable-inline-offer-container"></div>
+<%== offer.advocate_share_iframe(iframe: {container: 'talkable-inline-offer-container'}) %>
 ```
 
+## Integrate Conversion Points
 
+### Registering a purchase
 
+Registering a purchase has to be implemented manually based on your platform.
+> It's highly required to have submitted purchases for closing a referral loop.
 
-``` js
-
-offer = Talkable.offer(<%= offer.to_json %>)
-$('.js-share-via-facebook').click(
-    offer.shareViaFacebook()
-)
-$('.js-share-via-twitter').click(
-    offer.shareViaTwitter()
-)
-$('.js-share-via-sms').click(
-    offer.shareViaSms()
-)
-offer.bindClickLink($('.js-plain-offer-link'))
+```ruby
+Talkable::API::Origin.create(Talkable::API::Origin::PURCHASE, {
+  email: 'customer@email.com',
+  order_number: 'ORDER-12345',
+  subtotal: 123.45,
+  coupon_code: 'SALE10', # optional
+  ip_address: request.remote_ip, # optional
+  shipping_zip: '94103', # optional
+  shipping_address: '290 Division St., Suite 405, San Francisco, California, 94103, United States', # optional
+  items: order_items.map do |item|
+    {
+      price: item.price,
+      quantity: item.quantity,
+      product_id: item.product_id,
+      title: item.title,
+    }
+  end # optional
+})
 ```
 
-
-``` haml
-%h1= offer.localize('offer_title')
-%h1= offer.ab_test("Share with friends", "Get yourself a discount %{advocate_amount}", advocate_amount: campaign.advocate_incentive.description)
-%p
-  Share this offer with friends and get <%= campaign.advocate_incentive.description %>
-
-
-%a.js-share-via-facebook Facebook
-%a.js-share-via-twitter Twitter
-%a.js-share-via-sms Twitter
+### Registering other events
+
+```ruby
+Talkable::API::Origin.create(Talkable::API::Origin::EVENT, {
+  email: 'customer@email.com',
+  event_number: 'N12345',
+  event_category: 'user_signuped',
+  subtotal: 123.45, # optional
+  coupon_code: 'SALE10', # optional
+  ip_address: request.remote_ip, # optional
+  shipping_zip: '94103', # optional
+  shipping_address: '290 Division St., Suite 405, San Francisco, California, 94103, United States', # optional
+  items: order_items.map do |item|
+    {
+      price: item.price,
+      quantity: item.quantity,
+      product_id: item.product_id,
+      title: item.title,
+    }
+  end # optional
+})
 ```
 
+## API
 
-``` ruby
-# routes.rb
-mount Talkable::Rack => 'talkable'
+Full API support according to [DOC](http://docs.talkable.com/api_v2.html)
+
+```ruby
+Talkable::API::Origin.create(Talkable::API::Origin::PURCHASE, {
+  email: 'customer@domain.com',
+  order_number: '123',
+  subtotal: 34.56,
+})
+Talkable::API::Offer.find(short_url_code)
+Talkable::API::Share.create(short_url_code, Talkable::API::Share::CHANNEL_SMS)
+Talkable::API::Reward.find(visitor_uuid: '8fdf75ac-92b4-479d-9974-2f9c64eb2e09')
+Talkable::API::Person.find(email)
+Talkable::API::Person.update(email, unsubscribed: true)
+Talkable::API::Referral.update(order_number, Talkable::API::Referral::APPROVED)
 ```
-
-
-## TODO
-
-Functionality:
-
-* [ ] Gem infrustructure
-* [ ] Configuration
-* [ ] API
-  * Custom Traffic Source
-  * Custom User Agent
-  * Visitors
-  * Origins
-  * Shares
-  * Rewards
-* [ ] Controller uuid hook
-* [ ] Offer Share Iframe
-  * [ ] Integration JS additions
-  * [ ] Ruby iframe generation method
-* [ ] Generator
-* [ ] Documentation
-  * Post-Checkout integration instructions
-  * Events integration instructions
-* [ ] Setup demo with the most popular ruby shopping cart gem
-
-Caveats:
-* [ ] Prevent API call to create visitor on first request. Delay until user interacts with RAF.