From bed91663ceb03e53505c3cdcc0507722c2cdd096 Mon Sep 17 00:00:00 2001
From: Aidan Follestad <afollestad@squareup.com>
Date: Tue, 14 May 2019 15:16:56 -0700
Subject: [PATCH] Add rationale stuff to the README

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 4a76fc3..2fb9715 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ Assent is designed to make Android's runtime permissions easier and take less co
 2. [The Basics](#the-basics)
 3. [Using Results](#using-results)
 4. [Under the Hood Extras](#under-the-hood-extras)
+5. [Rationales](#rationales)
 
 ---
 
@@ -113,3 +114,31 @@ askForPermissions(CALL_PHONE) { _ -> }
 ```
 
 ...Assent would wait until the first permission request is done before executing the second request.
+
+---
+
+## Rationales
+
+Google recommends showing rationales for permissions when it may not be obvious to the user why 
+you need them. 
+
+Assent supports extensible rationale handlers, it comes with two out-of-the-box: 
+* `SnackBarRationaleHandler`
+* `AlertDialogRationaleHandler`
+
+```kotlin
+// Could also use createDialogRationale(...) here, 
+// or provide your own implementation of RationaleHandler. 
+val rationaleHandler = createSnackBarRationale(rootView) {
+  onPermission(READ_CONTACTS, "Test rationale #1, please accept!")
+  onPermission(WRITE_EXTERNAL_STORAGE, "Test rationale #1, please accept!")
+  onPermission(READ_SMS, "Test rationale #3, please accept!")
+}
+
+askForPermissions(
+    READ_CONTACTS, WRITE_EXTERNAL_STORAGE, READ_SMS,
+    rationaleHandler = rationaleHandler
+) { result ->
+  // Use result
+}
+```