talkable 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c94781742a33ea0f05537d873950e547a8fd44a9557ee5a420dbcf26533ef29b
-  data.tar.gz: 62d3776c5c8cad349f8c72c78c431d26a655134505ed5e9c06fd310c0527f2a7
+  metadata.gz: 85ca74c86aaaea53adef7d531ac81e669245683507ad1077bfa3113e95c48f4c
+  data.tar.gz: 1f846f63f097e27030fc5f55deca20674e4eaf6f1a3b6a0b53fde728deddb9d8
 SHA512:
-  metadata.gz: 80a4c188451af2bf7c1fcbfb88bfb12673d24900588dc9e72ed541429570fcd6263bf07cf697b45cd6f175699afa951640145c44e9d957cdc67992a528c5ad2f
-  data.tar.gz: e521fc595017bb499a1dff07f5f2ecbe9b868142f1119daf7e057da48f0972bb839c1d050cc46e2734695415c9d4c3b2e178149d52f49442c04b762c7249c0cb
+  metadata.gz: 5a29bbe1f0812a95e3255ae66fc956d76819ff134eb630ea6b0c8005d763d974dbaf21bcb15a08e7990dcb8da604ae35c4b9f5663bbe71b6fffae971817980d5
+  data.tar.gz: 9b38ec27c7bba78cb0db4f5cbed0064fc795b00aa3ea7703d3165a4c716d8931157297ea52c7975a2e0b1cf77ee2aec882968b2b40032944edb11df9e97bb456

data/.gitignore

@@ -9,6 +9,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+.idea/
 
 # Used by dotenv library to load environment variables.
 # .env

data/README.md

@@ -1,55 +1,58 @@
-# Talkable Referral Program API Gem
+# Talkable Referral Marketing 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
+Referral marketing is one of the most powerful strategies for ecommerce sales growth. [Talkable]( https://www.talkable.com) provides a rich platform for referral marketing. You can integrate sophisticated referral marketing into your own ecommerce site using the Talkable Ruby gem for a Rails or Sinatra application.
 
 ## Demo
 
-Example of usage at http://github.com/talkable/talkable-spree-example
+See an example application at http://github.com/talkable/talkable-spree-example.
 
-Live demo available at http://spree-example.talkable.com
+See a live demo at http://spree-example.talkable.com.
+
+## Tutorial
+
+See a [detailed tutorial](https://railsapps.github.io/talkable-referral-marketing/) by [Learn Ruby on Rails](http://learn-rails.com/learn-ruby-on-rails.html) author Daniel Kehoe.
 
 ## Requirements
 
-Gem requires:
- - `Ruby` version since `2.3.0`
- - `Rack` version since `1.6.1`
+The gem requires:
+ - Ruby version 2.3 or newer
+ - Rack version 1.6.1 or newer
 
-Gem supports:
- - `Ruby on Rails` since `4.0.0`
- - `Sinatra` since `1.4.0`
+For integration with:
+ - Ruby on Rails 5.0 or newer
+ - Sinatra 1.4 or newer
 
-## Intallation
+## Gem Installation
 
-``` ruby
+Add to your project *Gemfile*:
+
+```ruby
 gem "talkable"
 ```
 
-### Step by step instruction
-
-- [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)
+Then run:
 
-__*__ - Automated in Ruby On Rails by using the generator
+```console
+$ bundle install
+```
 
-## Using the Ruby On Rails Generator
+## Using the Rails Generator
 
-Talkable gem provides Ruby On Rails generator to automate an integration process.
+The Talkable gem provides a Ruby On Rails generator to automate the integration process.
 
-``` sh
-rails generate talkable:install
-```
-``` sh
+```console
+$ rails generate talkable:install
 Your Talkable site slug: spree-example
 Your Talkable API Key: SOME-API-KEY
 Do you have a custom domain? [Y/n] n
 ```
-``` sh
+
+The Talkable "site slug" is your Account Name (the name of your website, brand or company). You'll also need an API key which you'll find on the Account Settings page when you log in to your account. The generator will ask if you have a custom domain. If your website has a domain like example.com or www.example.com, you can answer, "no." If your website is at shop.example.com, you have a custom domain.
+
+The generator adds and modifies several files:
+
+```console
       create  config/initializers/talkable.rb
       insert  app/controllers/application_controller.rb
       insert  app/controllers/application_controller.rb
@@ -61,9 +64,21 @@ Do you have a custom domain? [Y/n] n
        route  get '/invite' => 'invite#show'
 ```
 
-## Configuration
+## Manual Integration
+
+Here are the steps that are automated by the Ruby On Rails generator.
 
-``` ruby
+- [Initializer](#initializer)
+- [Add Middleware](#add-middleware)
+- [Referral Offer](#referral-offer)
+- [Invite Page](#invite-page)
+
+### Initializer
+
+You'll need an initializer file to set the Talkable API configuration variables.
+
+```ruby
+### config/initializers/talkable.rb
 Talkable.configure do |config|
   # site slug is taken form ENV["TALKABLE_SITE_SLUG"]
   config.site_slug  = "spree-example"
@@ -79,22 +94,28 @@ Talkable.configure do |config|
 end
 
 ```
+For security, you should set these configuration variables from the Unix environment or use the Rails [encrypted credentials](https://www.engineyard.com/blog/rails-encrypted-credentials-on-rails-5.2) feature so the API key isn't stored in your GitHub repository.
 
-## Manual Integration
+### Add Middleware
 
-### Add Talkable Middleware
+Here's how you can add Talkable middleware manually.
 
-``` ruby
-  class Application < Rails::Application
-    config.middleware.use Talkable::Middleware
-  end
+_Note that if you're using Devise, it's important to load Talkable middleware before `Warden::Manager`, otherwise you can just go with `app.middleware.use Talkable::Middleware`._
+
+```ruby
+if defined? ::Warden::Manager
+  app.middleware.insert_before Warden::Manager, Talkable::Middleware
+else
+  app.middleware.use Talkable::Middleware
+end
 ```
 
-### Load an offer
+### Referral Offer
 
-Floating widget at every page
+Add code to retrieve a campaign and display a referral offer on every page of the application.
 
 ```ruby
+### app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
   before_action :load_talkable_offer
 
@@ -108,9 +129,26 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-or invite page at specific path
+```erb
+### app/views/shared/_talkable_offer.html.erb
+<%- options ||= {} %>
+<%- if offer %>
+  <%== offer.advocate_share_iframe(options) %>
+<% end -%>
+```
+
+### Invite Page
+
+You can add an invite page by implementing an Invite Controller, with route and view files.
+
+Add a route to the *config/routes.rb* file:
+
+```ruby
+ get '/invite' => 'invite#show'
+```
 
 ```ruby
+### app/controllers/invite_controller.rb
 class InviteController < ApplicationController
   def show
     # Make sure you have configured Campaign Placements at Talkable site
@@ -122,31 +160,48 @@ class InviteController < ApplicationController
 end
 ```
 
-### Getting information about an offer
+```erb
+### app/views/invite/show.html.erb
+<div id="talkable-inline-offer-container"></div>
+<%= render 'shared/talkable_offer',
+  offer: @invite_offer,
+  options: {iframe: {container: 'talkable-inline-offer-container'}} %>
+```
+
+## Customize Your Integration
+
+### Getting Information About an Offer
 
 ```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
+### Display an Offer Inside a View
 
-Provide iframe options to show a share page in specific place
+Provide iframe options to show a share page in specific place.
 
 ```erb
 <div id="talkable-inline-offer-container"></div>
 <%== offer.advocate_share_iframe(iframe: {container: 'talkable-inline-offer-container'}) %>
 ```
 
-## Integrate Conversion Points
+## API Examples
+
+See the [API docs](http://docs.talkable.com/api_v2.html) for full details.
+
+- [Registering a purchase](#registering-a-purchase)
+- [Registering other events](#registering-other-events)
+- [Working with referrals](#working-with-referrals)
+- [Working with shares](#shares)
+- [More API examples](#more-api-examples)
 
 ### 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.
+Here's how to register a purchase. We recommend you have submitted purchases for closing a referral loop.
 
 ```ruby
-Talkable::API::Origin.create(Talkable::API::Origin::PURCHASE, {
+Talkable.register_purchase(
   email: 'customer@email.com',
   order_number: 'ORDER-12345',
   subtotal: 123.45,
@@ -162,13 +217,15 @@ Talkable::API::Origin.create(Talkable::API::Origin::PURCHASE, {
       title: item.title,
     }
   end # optional
-})
+)
 ```
 
 ### Registering other events
 
+Here's how to register other events.
+
 ```ruby
-Talkable::API::Origin.create(Talkable::API::Origin::EVENT, {
+Talkable.register_event(
   email: 'customer@email.com',
   event_number: 'N12345',
   event_category: 'user_signuped',
@@ -185,23 +242,38 @@ Talkable::API::Origin.create(Talkable::API::Origin::EVENT, {
       title: item.title,
     }
   end # optional
-})
+)
 ```
 
-## API
+### Working with referrals
 
-Full API support according to [DOC](http://docs.talkable.com/api_v2.html)
+```ruby
+Talkable.approve_referral('test-slug')
+Talkable.void_referral('test-slug')
+Talkable.unblock_referral('test-slug')
+```
+
+### Shares
+
+```ruby
+Talkable::API::Share.social(short_url_code, channel: Talkable::API::Share::VIA_SMS)
+Talkable::API::Share.direct(short_url_code, channel: Talkable::API::Share::SEND_EMAIL, recipients: 'friend1@example.com,friend2@example.com', subject: 'Hello!', body: 'World!', reminder: false)
+```
+When sharing via email, the email channel is set to default because for now email is the only channel for direct shares.
+
+### More API examples
+
+Here are more API examples.
 
 ```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)
+Talkable::API::Reward.find(visitor_uuid: '8fdf75ac-92b4-479d-9974-2f9c64eb2e09')
 ```
+
+For more information see the tests. 
+
+## Questions? Need Help? Found a bug?
+
+If you've got questions about integration, or need any other information, please feel free to [open an issue](https://github.com/talkable/talkable-ruby/issues) so we can reply. Found a bug? Go ahead and submit an [issue](https://github.com/talkable/talkable-ruby/issues).

data/TUTORIAL.md

@@ -0,0 +1,253 @@
+# Referral Marketing with the Talkable Gem
+
+## Introduction
+
+This is the third of three tutorials that introduce referral marketing with [Talkable](https://www.talkable.com/). Referral marketing is a powerful sales driver for SaaS and ecommerce sites. Talkable is a referral marketing platform that supports the complex requirements of the largest and most sophisticated SaaS and ecommerce sites. The [first tutorial](https://railsapps.github.io/talkable-referral-marketing-basics/) introduces basic concepts using the Talkable JavaScript integration library. This tutorial introduces the Talkable API and the Talkable Ruby gem.
+
+Read the [first tutorial](https://railsapps.github.io/talkable-referral-marketing-basics/) to grasp the basic concepts you'll need to know to use the Talkable platform. This tutorial shows how to build an application with the same functionality as the first tutorial application, but instead of using the JavaScript integration library you'll use the Ruby gem and the Talkable API.
+
+The [second tutorial](https://railsapps.github.io/talkable-referral-marketing-gem/) is an older version of this one before we added an example campaign on account creation and corresponding generators in the gem. The second tutorial has more details about what happens under the hood and could still be interesting for this reason.
+
+This third tutorial will mature partly into self-serve users landing page and partly into our documentation in a course of several next releases.
+
+## Requirements
+
+You'll need Ruby 2.3+ and Rails 5.0+. You can integrate Talkable in your existing project right away, but a fresh Rails 5 app will also do just fine.
+You'll need only beginner skills as a Rails developer to follow this tutorial.
+
+## Create an Account
+
+First you'll need to [set up an account at Talkable](https://admin.talkable.com/register?self_serve).
+
+When asked to choose a platform, choose "other" for Rails integration. Then you can provide details such as email address and password.
+
+Your site name can be the name of your website, brand or company. You'll be able to add additional sites to your account after you create the first site.
+
+For this tutorial, set the Site URL to `http://localhost:3000/` so you can develop and test the application locally.
+
+![talkable-create-account](tutorial_images/talkable-create-account.png)
+
+**An example campaign is created automatically for you.**
+
+## Fraud Settings
+
+This part of the tutorial won't be needed in a few days as we will be setting different default fraud settings, but it is needed for now.
+
+Talkable prevents common (and not-so-common) referral fraud like self-referrals. For example, for product sales sites, referral marketing isn't profitable if shoppers can give themselves discounts by entering their own alternative email addresses.
+
+For our tutorial, we'll want to enter our own alternative email addresses and visit the application using the same web browser and the same IP address. We'll change the Fraud Settings to allow this.
+
+![talkable-menu-fraud](tutorial_images/talkable-menu-fraud.png)
+
+Set the "Fraud Profiles" (in the upper left corner) to "Low." Then set each individual fraud rule for Advocate and Friend to "Skip," specifically "Matching Email or Cookie on Friend Purchase" and "Matching Cookie on Friend Claim Page." This will allow self-referrals for testing the tutorial application in your local development environment.
+
+Be sure to click the "Save Changes" button to save the fraud settings.
+
+## Launch the Campaign
+
+You are done with the Talkable administrative interface for now and can launch your example campaign, even though your web application isn't ready yet.
+
+Select "Campaigns" from the top navigation bar.
+
+![talkable-menu-campaigns](tutorial_images/talkable-menu-campaigns.png)
+
+"Launch" is hidden behind three dots under the "Action" label.
+
+![talkable-menu-launch](tutorial_images/talkable-menu-launch.png)
+
+Ignore any warnings, accept the defaults, and click the orange "Launch campaign" button.
+
+![talkable-campaign-launch](tutorial_images/talkable-campaign-launch.png)
+
+You'll see a warning, "No Integration Found." Ignore the warning. Talkable checks if an Integration script is present on a production site but our development site is not running or accessible to Talkable. Click the green "Launch Now" button.
+
+You campaign will be live and waiting for events triggered by advocates (recommendations) or friends (claiming rewards). All events generated by the Talkable JavaScript integration library will be tracked and captured by Talkable for analysis and optimization. Talkable is designed to gather all data so there is no option to erase or reset campaign data once the campaign is live. However, you can create a new campaign when you are done with experimenting and ready to deploy to production.
+
+Next, we will set up the tutorial application to use the Talkable campaign. After that, we can return to the Talkable site to see reports of all activity.
+
+## Install the Talkable Ruby Gem
+
+You can use the [Talkable Ruby Gem](https://github.com/talkable/talkable-ruby) to add a referral program to any Ruby application.
+
+Add the gem to the project *Gemfile* and run `bundle install`.
+
+`gem 'talkable', github: 'talkable/talkable-ruby'`
+
+`$ bundle install`
+
+Your gem is installed. Let's configure your application.
+
+## Get Your Site Slug and API Key
+
+The Talkable gem provides a Ruby On Rails generator for basic configuration of the gem. You'll need to know your "site slug" (a site identifier). The "site slug" can differ from your account name. The "site slug" is the alphanumeric identifier Talkable uses for your website. Your account can support multiple sites and and each has its own "site slug."
+
+### Site Slug
+
+You can easily find the "site slug." You'll see the Dashboard page when you log in. The site slug is labelled "Site ID" in the upper left corner.
+
+![talkable-menu-dashboard](tutorial_images/talkable-menu-dashboard.png)
+
+![talkable-siteslug](tutorial_images/talkable-siteslug.png)
+
+### API Key
+
+You'll also need an API key. You can find the Account Settings page from the main menu.
+
+![talkable-account-settings](tutorial_images/talkable-account-settings.png)
+
+You'll find the API Key under Basic Settings. You won't need the Public API Key (that's just for iOS or Android developers).
+
+![talkable-account-settings-more](tutorial_images/talkable-account-settings-more.png)
+
+With your site slug and API key you are ready to run the generator.
+
+## Run the Generator
+
+Run the install generator from the terminal:
+
+`$ rails generate talkable:install`
+
+The generator will prompt you for your "site slug" and API key.
+
+The generator will ask if you have a custom domain. You can answer, "no." Custom domains are an advanced feature for Talkable integration.
+
+In order for example setup to work you'll need to run two more generators.
+
+`$ rails generate talkable:invite_standalone`
+
+Invite standalone generator will add a controller and a view where your campaign will be rendered.
+The placement of where to render the campaign is controlled in your campaign settings on Talkable site.
+For the example campaign we chose to use `/invite` as our placement.
+
+`$ rails generate talkable:example_newsletter_signup`
+
+Example newsletter signup will add a controller, routes and views to your app.
+Our example campaign is configured in a way that will redirect the `friend` to `/example_newsletter_signup` after the claim. On that page a user will be prompted to fake email signup. By default this `signup` only sends a corresponding event via Talkable API.
+
+We encourage you to inspect all the stuff produced by generators up close (this section is more detailed in the original ruby gem tutorial).
+Here are a few important details.
+
+The file *app/views/invite/show.html.erb* renders the view. It contains a reference to the view partial in the file *shared/talkable_offer*.
+
+Your Invite page will display a Talkable referral offer in an iframe, if the following conditions are met:
+
+* The Talkable initialization script is in place
+* A Talkable Invite Standalone campaign exists
+* A Talkable Campaign Placement specifies the `http://localhost:3000/invite` URL
+* The Invite page contains `<div id="talkable-offer"></div>`
+
+We'll use the Invite page to display a referral offer from the Invite Standalone campaign. You can add links to this page anywhere in your application where you want to encourage visitors to refer a friend.
+
+It is important to set a User ID or other unchanging string as an `event_number` each time the page is requested by a visitor. With an unchanging User ID, Talkable will recognize the page requests as repeat visits by the same visitor and will record the visits accordingly.
+
+We add the integer 100 to the `current_user.id` to create an `event_number` just for the purpose of this tutorial. If you implemented the tutorial application in our [first tutorial](https://railsapps.github.io/talkable-referral-marketing-basics/), you may have already recorded events for the Invite Standalone campaign. If you build a new application and sign up using event numbers that are already recorded, the Talkable API will respond with an error message "Talkable::API::BadRequest." Adding 100 helps us avoid the issue for anyone who tried the application in the first tutorial.
+
+That's all the code we need for our simple refer-a-friend feature. We can try out the tutorial application. But first, let's review the fundamental concept of the *referral loop*.
+
+## Understanding The Referral Loop
+
+It's helpful to understand the *referral loop* to grasp the principles of referral marketing. In its most basic form, as we've used it here:
+
+* An advocate opens the referral loop by clicking the referral offer on the Invite page and sending a recommendation to a friend.
+
+* A friend receives the recommendation and clicks a link on a "claim page"; a cookie is set by Talkable.
+
+* The friend gets redirected to the site. On any page they visit, Talkable will recognize the friend's visit by the presence of the cookie.
+
+* The friend signs up for an example newsletter (a *conversion event*) and the API request signals Talkable, closing the referral loop.
+
+Building on this simple referral loop, you can develop more sophisticated referral marketing campaigns. For example, you can add incentives for the friend or advocate. For a product sales site, you could offer a discount coupon, a rebate, or a non-monetary incentive such as stickers or a t-shirt. You can track an advocate's multiple referrals or even chains of referrals among friends. Talkable supports almost any referral marketing program you can imagine.
+
+Now let's try out the tutorial application.
+
+## Time to test how it all works
+
+Make sure your campaign is launched. Now go to `http://localhost:3000/invite`
+
+### Advocate Invites a Friend
+
+You should now see our campaign page for the Advocate.
+
+![talkable-referral-offer](tutorial_images/talkable-referral-offer.png)
+
+Enter your name and email address in the form and click "Invite Friends".
+
+The Advocate Share offer will appear on the Invite page.
+
+Below you can find the scenario when you share the offer via email. Alternatively you can share via `Copy a Link`. You copy the link and open it in another browser or in the incognito mode. You should be able to claim your reward right away.
+
+![talkable-advocate-share](tutorial_images/talkable-advocate-share.png)
+
+Click "Share via Email" and fill in the form with a friend's email address. To try out the application, you should enter your own alternative email address. If you use Gmail, you can use the Gmail "plus" trick to create alternative addresses that will be delivered in your inbox. For example, add a "+foobar" to use "yourname+foobar@gmail.com". This will open a referral loop by registering your email address as an advocate and the friend's email address as a pending invitation.
+
+![talkable-advocate-friend](tutorial_images/talkable-advocate-friend.png)
+
+You are done with the Invite page. Sign out of the application so you can pretend to be the friend next time you visit the web application.
+
+### Friend Receives Email
+
+Check your email inbox. Less than a minute after submitting the form with the friend email address, you should receive an email message from Talkable. There will be a prominent "Claim Your Gift" button in the message body. The claim button is a link to the Talkable server that will track the action and redirect to your web application.
+
+### Friend Clicks Link
+
+Click the "Claim Your Gift" button in the email message and you will visit the newsletter signup page of your application.
+
+### Friend Signs Up
+
+Now sign up for an example newsletter.
+
+You'll see the Thank You page. Behind the scenes, the Talkable controller will make an API request to Talkable to record the signup event. This closes a referral loop because Talkable recognizes the friend's email address from the advocate's invitation.
+
+Next let's view reports on the Talkable site and see the events that Talkable has recorded.
+
+## Talkable Reports
+
+Sign in to the Talkable site and select "Reports" from the top navigation bar.
+
+![talkable-menu-reports](tutorial_images/talkable-menu-reports.png)
+
+View some of the reports under the "Support" heading.
+
+The **People** report will show the email addresses of the advocates and friends.
+
+The **Events** report will show the signup activities.
+
+The **Advocate Offers** report will show the email address of each advocate and the name of the campaign to which each responded.
+
+The **Offer Shares** report will show the linked advocates and friends.
+
+The **Referrals** report will show the complete details of each referral event. If any event indicates "Campaign doesn't offer Self-Referral Incentive," you will need to check the Fraud Settings from the main menu. You can adjust the Fraud Settings to allow self-referrals for the purpose of testing.
+
+Take a few minutes to view the reports and see how the referral activity is logged for analysis and action. If Talkable was integrated correctly in your application, all the referral activity should be reflected in the reports.
+
+## Campaign Performance
+
+Finally, to see a high-level analysis of your referral marketing campaign, find the Campaign Performance summary. Select "Campaigns" from the top navigation bar.
+
+![talkable-menu-campaigns](tutorial_images/talkable-menu-campaigns.png)
+
+Click the "Invite Standalone" campaign to see a campaign summary.
+
+![talkable-campaign-summary](tutorial_images/talkable-campaign-summary.png)
+
+The Campaign Performance summary shows the funnel of impressions (page visits), advocates (sharers), sharing events, and visits by friends. The Campaign Performance isn't the end point of a typical referral marketing campaign. It is the beginning point for further testing and optimization to refine a referral marketing campaign.
+
+With this introduction to referral marketing and the Talkable platform, you've seen the basics of referral marketing.
+
+The functionality of the tutorial application is minimal but you’ve learned enough to add simple referral marketing to any Rails application.
+
+## Troubleshooting
+
+Troubleshooting options are limited with the Ruby gem.
+
+### Verification Query
+
+In the [first tutorial](https://railsapps.github.io/talkable-referral-marketing-basics/), we were able to use a verification query to check that the Talkable initialization script is connecting to the Talkable server and recognizing your account. For example:
+
+* [http://localhost:3000/?tkbl_verify_integration=true](http://localhost:3000/?tkbl_verify_integration=true)
+
+However, this verification query doesn't work with the Ruby gem.
+
+## Support
+
+Was this tutorial helpful? For questions or more information, contact <a href="mailto:support@talkable.com">support@talkable.com</a>.

data/lib/talkable/api/origin.rb

@@ -19,7 +19,6 @@ module Talkable
 
         def default_data
           {
-            uuid: Talkable.visitor_uuid,
             traffic_source: DEFAULT_TRAFFIC_SOURCE,
           }
         end

data/lib/talkable/api/share.rb

@@ -1,18 +1,40 @@
+# More at http://docs.talkable.com/api_v2/shares.html
 module Talkable
   module API
     class Share < Base
-      CHANNEL_FACEBOOK          = "facebook".freeze
-      CHANNEL_FACEBOOK_MESSAGE  = "facebook_message".freeze
-      CHANNEL_TWITTER           = "twitter".freeze
-      CHANNEL_SMS               = "sms".freeze
-      CHANNEL_OTHER             = "other".freeze
+      # social
+      VIA_FACEBOOK    = "facebook"
+      VIA_FB_MESSAGE  = "facebook_message"
+      VIA_TWITTER     = "twitter"
+      VIA_LINKEDIN    = "linkedin"
+      VIA_WHATSAPP    = "twitter"
+      VIA_SMS         = "sms"
+      VIA_OTHER       = "other"
+
+      # direct
+      SEND_EMAIL      = "email"
 
       class << self
         def create(short_url_code, channel)
-          post "/offers/#{short_url_code}/shares", {
+          warn "[DEPRECATION] `create` is deprecated.  Please use `social` or `direct` instead."
+          social(short_url_code, channel: channel)
+        end
+
+        def social(short_url_code, channel:)
+          post "/offers/#{short_url_code}/shares/social", {
             channel: channel,
           }
         end
+
+        def direct(short_url_code, channel: SEND_EMAIL, recipients:, subject: nil, body: nil, reminder: nil)
+          raise ArgumentError, 'Email is the only supported sharing channel' unless channel == SEND_EMAIL
+          post "/offers/#{short_url_code}/shares/#{channel}", {
+            recipients: recipients,
+            subject: subject,
+            body: body,
+            reminder: reminder,
+          }
+        end
       end
     end
   end

data/lib/talkable/configuration.rb

@@ -13,7 +13,7 @@ module Talkable
     def initialize
       self.site_slug  = ENV["TALKABLE_SITE_SLUG"]
       self.api_key    = ENV["TALKABLE_API_KEY"]
-      self.server     = "https://www.talkable.com"
+      self.server     = DEFAULT_SERVER
     end
 
     def apply(config)
@@ -35,6 +35,5 @@ module Talkable
     def default_js_integration_library
       "//d2jjzw81hqbuqv.cloudfront.net/integration/clients/#{site_slug}.min.js"
     end
-
   end
 end

data/lib/talkable/generators/example_newsletter_signup_generator.rb

@@ -0,0 +1,22 @@
+require 'talkable/generators/shared_generator_methods'
+
+module Talkable
+  class ExampleNewsletterSignupGenerator < Rails::Generators::Base
+    include Talkable::SharedGeneratorMethods
+
+    source_root File.expand_path("../templates", __FILE__)
+    class_option :haml, type: :boolean, default: false
+    class_option :slim, type: :boolean, default: false
+
+    def add_invite_controller
+      ext = template_lang
+
+      copy_file "app/controllers/example_newsletter_signup_controller.rb", "app/controllers/example_newsletter_signup_controller.rb"
+      copy_file "app/views/example_newsletter_signup/register.html.#{ext}", "app/views/example_newsletter_signup/register.html.#{ext}"
+      copy_file "app/views/example_newsletter_signup/thank_you.html.#{ext}", "app/views/example_newsletter_signup/thank_you.html.#{ext}"
+      route "get '/example_newsletter_signup/thank_you' => 'example_newsletter_signup#thank_you'"
+      route "get '/example_newsletter_signup' => 'example_newsletter_signup#register'"
+      route "post '/example_newsletter_signup' => 'example_newsletter_signup#submit'"
+    end
+  end
+end

data/lib/talkable/generators/install_generator.rb

@@ -1,5 +1,9 @@
+require 'talkable/generators/shared_generator_methods'
+
 module Talkable
   class InstallGenerator < Rails::Generators::Base
+    include Talkable::SharedGeneratorMethods
+
     source_root File.expand_path("../templates", __FILE__)
     class_option :haml, type: :boolean, default: false
     class_option :slim, type: :boolean, default: false
@@ -52,30 +56,5 @@ RUBY
         end
       end
     end
-
-    def add_invite_controller
-      ext = template_lang
-
-      copy_file "app/controllers/invite_controller.rb", "app/controllers/invite_controller.rb"
-      copy_file "app/views/invite/show.html.#{ext}", "app/views/invite/show.html.#{ext}"
-      route "get '/invite' => 'invite#show'"
-    end
-
-    protected
-
-    def template_lang
-      @template_lang ||= if options[:haml]
-        'haml'
-      elsif options[:slim]
-        'slim'
-      else
-        Rails::Generators.options[:rails][:template_engine].to_s.downcase
-      end
-    end
-
-    def erb?
-      template_lang == 'erb'
-    end
-
   end
 end

data/lib/talkable/generators/invite_standalone_generator.rb

@@ -0,0 +1,19 @@
+require 'talkable/generators/shared_generator_methods'
+
+module Talkable
+  class InviteStandaloneGenerator < Rails::Generators::Base
+    include Talkable::SharedGeneratorMethods
+
+    source_root File.expand_path("../templates", __FILE__)
+    class_option :haml, type: :boolean, default: false
+    class_option :slim, type: :boolean, default: false
+
+    def add_invite_controller
+      ext = template_lang
+
+      copy_file "app/controllers/invite_controller.rb", "app/controllers/invite_controller.rb"
+      copy_file "app/views/invite/show.html.#{ext}", "app/views/invite/show.html.#{ext}"
+      route "get '/invite' => 'invite#show'"
+    end
+  end
+end

data/lib/talkable/generators/shared_generator_methods.rb

@@ -0,0 +1,15 @@
+module Talkable::SharedGeneratorMethods
+  def template_lang
+    @template_lang ||= if options[:haml]
+     'haml'
+    elsif options[:slim]
+     'slim'
+    else
+     Rails::Generators.options[:rails][:template_engine].to_s.downcase
+    end
+  end
+
+  def erb?
+    template_lang == 'erb'
+  end
+end

data/lib/talkable/generators/templates/app/controllers/example_newsletter_signup_controller.rb

@@ -0,0 +1,17 @@
+class ExampleNewsletterSignupController < ApplicationController
+  def register
+  end
+
+  def submit
+    Talkable.register_event(
+      email: params[:email],
+      event_number: Digest::MD5.hexdigest(params[:email]),
+      event_category: 'example_newsletter_signup'
+    )
+
+    redirect_to example_newsletter_signup_thank_you_path
+  end
+
+  def thank_you
+  end
+end

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.erb

@@ -0,0 +1,5 @@
+<h3>Example newsletter signup (this form will just submit an event to talkable)</h3>
+<%= form_tag :example_newsletter_signup do %>
+  <%= email_field_tag :email %>
+  <%= submit_tag 'SignUp' %>
+<% end %>

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.haml

@@ -0,0 +1,4 @@
+%h3 Example newsletter signup (this form will just submit an event to talkable)
+= form_tag :example_newsletter_signup do
+  = email_field_tag :email
+  = submit_tag 'SignUp'

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.slim

@@ -0,0 +1,4 @@
+h3 Example newsletter signup (this form will just submit an event to talkable)
+= form_tag :example_newsletter_signup do
+  = email_field_tag :email
+  = submit_tag 'SignUp'

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.erb

@@ -0,0 +1 @@
+<h3>You should now have a closed referral loop, see talkable admin for more details</h3>

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.haml

@@ -0,0 +1 @@
+%h3 You should now have a closed referral loop, see talkable admin for more details

data/lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.slim

@@ -0,0 +1 @@
+h3 You should now have a closed referral loop, see talkable admin for more details

data/lib/talkable/integration.rb

@@ -23,6 +23,7 @@ module Talkable
 
     def default_params
       {
+        uuid: Talkable.visitor_uuid,
         r: Talkable.current_url,
       }
     end

data/lib/talkable/middleware.rb

@@ -73,7 +73,7 @@ module Talkable
     end
 
     def sync_uuid_url(uuid)
-      Furi.update("https://www.talkable.com/public/1x1.gif", query: {current_visitor_uuid: uuid})
+      Furi.update("#{Talkable.configuration.server}/public/1x1.gif", query: {current_visitor_uuid: uuid})
     end
 
     def sync_uuid_content(uuid)

data/lib/talkable/railtie.rb

@@ -2,10 +2,16 @@ module Talkable
   class Railtie < Rails::Railtie
     generators do
       require 'talkable/generators/install_generator'
+      require 'talkable/generators/invite_standalone_generator'
+      require 'talkable/generators/example_newsletter_signup_generator'
     end
 
     initializer "talkable.add_middleware" do |app|
-      app.middleware.use Talkable::Middleware
+      if defined? ::Warden::Manager
+        app.middleware.insert_before Warden::Manager, Talkable::Middleware
+      else
+        app.middleware.use Talkable::Middleware
+      end
     end
   end
 end

data/lib/talkable/referrals.rb

@@ -0,0 +1,21 @@
+module Talkable
+  class << self
+    def approve_referral(origin_slug)
+      update_referral(origin_slug, Talkable::API::Referral::APPROVED)
+    end
+
+    def void_referral(origin_slug)
+      update_referral(origin_slug, Talkable::API::Referral::VOIDED)
+    end
+
+    def unblock_referral(origin_slug)
+      update_referral(origin_slug, Talkable::API::Referral::UNBLOCKED)
+    end
+
+    private
+
+    def update_referral(origin_slug, status)
+      Talkable::API::Referral.update(origin_slug, status)
+    end
+  end
+end

data/lib/talkable/version.rb

@@ -1,3 +1,3 @@
 module Talkable
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: talkable
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Talkable
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-19 00:00:00.000000000 Z
+date: 2018-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -163,6 +163,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- TUTORIAL.md
 - lib/talkable.rb
 - lib/talkable/api.rb
 - lib/talkable/api/base.rb
@@ -174,8 +175,18 @@ files:
 - lib/talkable/api/share.rb
 - lib/talkable/api/visitor.rb
 - lib/talkable/configuration.rb
+- lib/talkable/generators/example_newsletter_signup_generator.rb
 - lib/talkable/generators/install_generator.rb
+- lib/talkable/generators/invite_standalone_generator.rb
+- lib/talkable/generators/shared_generator_methods.rb
+- lib/talkable/generators/templates/app/controllers/example_newsletter_signup_controller.rb
 - lib/talkable/generators/templates/app/controllers/invite_controller.rb
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.erb
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.haml
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/register.html.slim
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.erb
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.haml
+- lib/talkable/generators/templates/app/views/example_newsletter_signup/thank_you.html.slim
 - lib/talkable/generators/templates/app/views/invite/show.html.erb
 - lib/talkable/generators/templates/app/views/invite/show.html.haml
 - lib/talkable/generators/templates/app/views/invite/show.html.slim
@@ -186,12 +197,48 @@ files:
 - lib/talkable/integration.rb
 - lib/talkable/middleware.rb
 - lib/talkable/railtie.rb
+- lib/talkable/referrals.rb
 - lib/talkable/resources.rb
 - lib/talkable/resources/offer.rb
 - lib/talkable/resources/origin.rb
 - lib/talkable/version.rb
 - solano.yml
 - talkable.gemspec
+- tutorial_images/logo.png
+- tutorial_images/navbar.png
+- tutorial_images/rails-signup-thankyou-1.png
+- tutorial_images/rails-stripe-checkout-1.png
+- tutorial_images/talkable-account-settings-more.png
+- tutorial_images/talkable-account-settings.png
+- tutorial_images/talkable-advocate-friend.png
+- tutorial_images/talkable-advocate-share.png
+- tutorial_images/talkable-campaign-launch.png
+- tutorial_images/talkable-campaign-summary.png
+- tutorial_images/talkable-coupon-settings.png
+- tutorial_images/talkable-create-account.png
+- tutorial_images/talkable-integration-general.png
+- tutorial_images/talkable-menu-campaigns.png
+- tutorial_images/talkable-menu-dashboard.png
+- tutorial_images/talkable-menu-fraud.png
+- tutorial_images/talkable-menu-integration.png
+- tutorial_images/talkable-menu-launch.png
+- tutorial_images/talkable-menu-placement.png
+- tutorial_images/talkable-menu-reports.png
+- tutorial_images/talkable-menu-site.png
+- tutorial_images/talkable-new-campaign-advocate.png
+- tutorial_images/talkable-new-campaign-editor.png
+- tutorial_images/talkable-new-campaign-incentive-1.png
+- tutorial_images/talkable-new-campaign-incentive-2.png
+- tutorial_images/talkable-new-campaign-incentive.png
+- tutorial_images/talkable-new-campaign-invite.png
+- tutorial_images/talkable-new-campaign-save.png
+- tutorial_images/talkable-new-campaign-standalone.png
+- tutorial_images/talkable-new-campaign.png
+- tutorial_images/talkable-new-placement.png
+- tutorial_images/talkable-new-site.png
+- tutorial_images/talkable-referral-offer.png
+- tutorial_images/talkable-siteslug.png
+- tutorial_images/talkable-verify-modal.png
 homepage: https://github.com/talkable/talkable-ruby
 licenses:
 - MIT