Merge pull request LinusU#139 from harrowmykel/master

🌹 Add troubleshooting documentation

Author: LinusU

README.md

@@ -113,3 +113,119 @@ close the window.
 Redirection URL passed to the authentication service must be the same as the URL on which the application is running (schema, host, port if necessary) and the path must point to created HTML file, `/auth.html` in this case. The `callbackUrlScheme` parameter of the `authenticate()` method does not take into account, so it is possible to use a schema for native platforms in the code.
 
 For the Sign in with Apple in web_message response mode, postMessage from https://appleid.apple.com is also captured, and the authorization object is returned as a URL fragment encoded as a query string (for compatibility with other providers).
+
+## Troubleshooting
+
+When you use this package for the first time, there are some problems you may have. These are some of the common solutions
+
+### Troubleshooting `callbackUrlScheme`
+
+- `callbackUrlScheme` must be a valid schema string or else this wont work.
+- A valid RFC 3986 URL scheme must consist of "a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-")."
+- scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
+- This means you can not use underscore "_", space " " or uppercase "ABCDEF...". You can not also start with a number. See [RFC3986#page-17](https://www.rfc-editor.org/rfc/rfc3986#page-17)
+- examples of VALID  `callbackUrlScheme` are `callback-scheme`, `another.scheme`, `examplescheme`
+- examples of INVALID  `callbackUrlScheme` are `callback_scheme`,`1another.scheme`, `exampleScheme`
+
+### Troubleshooting Flutter App
+
+- You have to tell the `FlutterWebAuth.authenticate` function what your `callbackUrlScheme` is.
+- Example if your `callbackUrlScheme` is  `valid-callback-scheme`, your dart code will look like
+
+    ```dart
+    import 'package:flutter_web_auth/flutter_web_auth.dart';
+
+    // Present the dialog to the user
+    final result = await FlutterWebAuth.authenticate(url: "https://my-custom-app.com/connect", callbackUrlScheme: "valid-callback-scheme");
+    ```
+
+### Troubleshooting Android
+
+- You are required to update your `AndroidManifest.xml` to include the `com.linusu.flutter_web_auth.CallbackActivity` activity something like
+
+    ```xml
+    <manifest>
+      <application>
+
+        <!-- add the com.linusu.flutter_web_auth.CallbackActivity activity -->
+        <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
+          <intent-filter android:label="flutter_web_auth">
+            <action android:name="android.intent.action.VIEW" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+            <data android:scheme="YOUR_CALLBACK_URL_SCHEME_HERE" />
+          </intent-filter>
+        </activity>
+
+      </application>
+    </manifest>
+    ```
+
+- Example of valid `AndroidManifest.xml` with VALID `callbackUrlScheme`. in the example below `valid-callback-scheme` is our `callbackUrlScheme`
+
+    ```xml
+    <manifest>
+      <application>
+
+        <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
+          <intent-filter android:label="flutter_web_auth">
+            <action android:name="android.intent.action.VIEW" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+            <data android:scheme="valid-callback-scheme" />
+          </intent-filter>
+        </activity>
+
+      </application>
+    </manifest>
+    ```
+
+### Troubleshooting OAuth redirects
+
+- Your OAuth Provider must redirect to the valid  `callbackUrlScheme` + `://`. This mean if your  `callbackUrlScheme` is `validscheme`, your OAuth Provider must redirect to `validscheme://`
+- Example with `php`
+    ```php
+    <?php
+
+    header("Location: validscheme://?data1=value1&data2=value2");
+    ```
+
+### Troubleshooting HTML redirects
+
+- If you are using HTML hyperlinks, it must be a valid `callbackUrlScheme` + `://`. This mean if your `callbackUrlScheme` is `customappname`, your html hyperlink should be `customappname://`
+- example with `HTML`
+
+    ```html
+    <a href="customappname://?data1=value1&data2=value2">Go Back to App</a>
+    ```
+
+### Troubleshooting passing data to app
+
+- You can pass data back to your app by adding GET query parameters. This means by adding name=value type of data after your `callbackUrlScheme` + `://` + `?`
+- example to pass `access-token` to your app a valid url for that could be
+
+    ```text
+    my-callback-schema://?access-token=jdu9292s
+    ```
+
+- You can pass multipe data by concatenating with `&`
+
+    ```text
+    my-callback-schema://?data1=value1&data2=value2
+    ```
+
+- example to pass `access-token` and `user_id` to your app a valid url for that could be
+
+    ```text
+    my-callback-schema://?access-token=jdu9292s&user_id=23
+    ```
+
+- You can get the data in your app by using `Uri.parse(result).queryParameters`
+
+    ```dart
+    // Present the dialog to the user
+    final result = await FlutterWebAuth.authenticate(url: "https://my-custom-app.com/connect", callbackUrlScheme: "valid-callback-scheme");
+    // Extract token from resulting url
+    String accessToken = Uri.parse(result).queryParameters['access-token'];
+    String userId = Uri.parse(result).queryParameters['user_id'];
+    ```