Simplify README and add iframe info

Author: Grace Yim

CONTRIBUTING.md

@@ -1,70 +1,104 @@
-#ToopherJava
+#ToopherJava [![Build Status](https://travis-ci.org/toopher/toopher-java.png?branch=master)](https://travis-ci.org/toopher/toopher-java)
 
-[![Build
-Status](https://travis-ci.org/toopher/toopher-java.png?branch=master)](https://travis-ci.org/toopher/toopher-java)
+ToopherJava is a Toopher API library that simplifies the task of interfacing with the Toopher API from Java code.  This project wrangles all the dependency libraries and handles the required OAuth and JSON functionality so you can focus on just using the API.
 
-#### Introduction
-ToopherJava is a Toopher API library that simplifies the task of interfacing with the Toopher API from Java code.  This project includes all the dependency libraries and handles the required OAuth and JSON functionality so you can focus on just using the API.
+*Note: ToopherJava is not meant for use in Android.*
 
-Note: ToopherJava is not meant for use in Android.
+### Java Version
+\>=5.0
 
-#### Learn the Toopher API
-Make sure you visit (http://dev.toopher.com) to get acquainted with the Toopher API fundamentals.  The documentation there will tell you the details about the operations this API wrapper library provides.
+### Documentation
+Make sure you visit [https://dev.toopher.com](https://dev.toopher.com) to get acquainted with the Toopher API fundamentals.  The documentation there will tell you the details about the operations this API wrapper library provides.
 
-#### OAuth Authentication
+## ToopherApi Workflow
 
-The first step to accessing the Toopher API is to sign up for an account at the development portal (http://dev.toopher.com) and create a "requester". When that process is complete, your requester is issued OAuth 1.0a credentials in the form of a consumer key and secret. Your key is used to identify your requester when Toopher interacts with your customers, and the secret is used to sign each request so that we know it is generated by you.  This library properly formats each request with your credentials automatically.
-
-#### The Toopher Two-Step
-Interacting with the Toopher web service involves two steps: pairing and authenticating.
-
-##### Pair
-Before you can enhance your website's actions with Toopher, your customers will need to pair their phone's Toopher app with your website.  To do this, they generate a unique, nonsensical "pairing phrase" from within the app on their phone.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher API along with your requester credentials and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
-
-##### Authenticate
-You have complete control over what actions you want to authenticate using Toopher (for example: logging in, changing account information, making a purchase, etc.).  Just send us the user's pairing ID, a name for the terminal they're using, and a description of the action they're trying to perform and we'll make sure they actually want it to happen.
-
-#### Librarified
-This library makes it super simple to do the Toopher two-step.  Check it out:
+### Step 1: Pair
+Before you can enhance your website's actions with Toopher, your customers will need to pair their mobile device's Toopher app with your website.  To do this, they generate a unique pairing phrase from within the app on their mobile device.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher API along with their username and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
 
 ```java
 import com.toopher.*;
 
 // Create an API object using your credentials
 ToopherAPI api = new ToopherAPI("<your consumer key>", "<your consumer secret>");
 
-// Step 1 - Pair with their phone's Toopher app
-// With pairing phrase
+// Step 1 - Pair with their mobile device's Toopher app
 Pairing pairing = api.pair("username@yourservice.com", "pairing phrase");
-// With SMS
-Pairing pairing = api.pair("username@yourservice.com", "555-555-5555")
-// With QR code
-Pairing pairing = api.pair("username@yourservice.com")
+```
+
+### Step 2: Authenticate
+You have complete control over what actions you want to authenticate using Toopher (logging in, changing account information, making a purchase, etc.).  Just send us the username or pairing ID and we'll make sure they actually want it to happen. You can also choose to provide the following optional parameters: terminal name, requester specified ID and action name (*default: "Log in"*).
+
+```java
+// Create an optional Map of extra parameters to provide to the API
+Map<String, String> extras = new HashMap<String, String>();
+extras.put("terminalName", "terminal name");
+extras.put("requesterSpecifiedId", "requester specified ID");
+extras.put("actionName", "action name");
 
 // Step 2 - Authenticate a log in
-// With pairingId and terminal name
-AuthenticationRequest auth = api.authenticate(pairing.id, "my computer");
-// With username and requester specified Id (Returns exception if terminal is not found)
-AuthenticationRequest auth = api.authenticate("username", null, "requesterSpecifiedId")
-// With username, terminal name and requester specified Id (Returns exception if terminal is not found)
-AuthenticationRequest auth = api.authenticate("username", "my computer", "requesterSpecifiedId")
-// With username and terminal name (New terminal is created if terminal is not found)
-AuthenticationRequest auth = api.authenticate("username", "my computer")
+AuthenticationRequest authenticationRequest = api.authenticate("username@yourservice.com", extras);
 
 // Once they've responded you can then check the status
-auth.refreshFromServer()
+authenticationRequest.refreshFromServer();
 if (status.pending == false && status.granted == true) {
     // Success!
 }
 ```
 
-#### Handling Errors
+## ToopherIframe Workflow
+
+### Step 1: Embed a request in an IFRAME
+1. Generate an authentication URL by providing a username.
+2. Display a webpage to your user that embeds this URL within an `<iframe>` element.
+
+```java
+import com.toopher.*;
+
+// Create an API object using your credentials
+ToopherIframe iframeApi = new ToopherIframe("<your consumer key>", "<your consumer secret>");
+
+String authenticationUrl = iframeApi.getAuthenticationUrl("username@yourservice.com");
+
+// Add an <iframe> element to your HTML:
+// <iframe id="toopher_iframe" src=authenticationUrl />
+```
+
+### Step 2: Validate the postback data
+
+The simplest way to validate the postback data is to call `isAuthenticationGranted` to check if the authentication request was granted.
+
+```java
+// Retrieve the postback data as a string from POST parameter 'iframe_postback_data'
+
+// Returns boolean indicating if authentication request was granted by user
+boolean authenticationRequestGranted = iframeApi.isAuthenticationGranted(postback_data);
+
+if (authenticationRequestGranted) {
+    // Success!
+}
+```
+
+### Handling Errors
 If any request runs into an error a `RequestError` will be thrown with more details on what went wrong.
 
-#### Dependencies
+### Demo
+Check out `com.toopher.ToopherAPIDemo.java` for an example program that walks you through the whole process! Just download the contents of this repo, make sure you have the dependencies installed, and run the command below:
+
+```shell
+$ mvn exec:java -Dexec.mainClass="com.toopher.ToopherAPIDemo"
+```
+
+## Contributing
+### Dependencies
+Toopher uses [Maven](https://maven.apache.org/index.html). To install Maven with Homebrew run:
+
+```shell
+$ brew install maven
+```
+
 This library uses the Apache Commons HttpClient and OAuth-Signpost libraries, which are included as JARs in the "lib" directory.  Please add these JARs to your classpath when using our library.
 
-##### Maven
+#### Maven
 Alternatively, you can consume this library using Maven:
 
     <dependency>
@@ -73,21 +107,17 @@ Alternatively, you can consume this library using Maven:
         <version>1.0.0-SNAPSHOT</version>
     </dependency>
 
-#### Try it out
-Check out `com.toopher.ToopherAPIDemo.java` for an example program that walks you through the whole process!
-
-#####Ant
-A runnable jar for the demo can be built and executed in Ant as follows:
+### Tests
+To run the tests using Maven enter:
 ```shell
-$ ant
-$ java -jar dist/toopher-1.0.0.jar
+$ mvn test
 ```
 
-#####Maven
-The demo can be executed in Maven as follows:
+To get coverage reports with the JaCoCo Maven Plugin enter:
 ```shell
-$ mvn exec:java -Dexec.mainClass="com.toopher.ToopherAPIDemo"
+$ mvn clean verify -P all-tests
+$ open target/site/jacoco/index.html
 ```
 
-#### License
-ToopherJava is licensed under the MIT License. See LICENSE.txt for the full license text.
+## License
+ToopherJava is licensed under the MIT License. See LICENSE.txt for the full text.