Skip to content

Remove in-depth documentation for AuthUI.java and link to README instead #569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 2, 2017
Merged

Remove in-depth documentation for AuthUI.java and link to README instead #569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c08edfd
Remove in-depth documentation for AuthUI.java and link to README instead
SUPERCILEX Feb 2, 2017
2e41931
Link to ToC and file directly
SUPERCILEX Feb 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion auth/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ and [Web](https://github.com/firebase/firebaseui-web/).

![FirebaseUI authentication demo on Android](demo.gif)

## Table of Content
## Table of Contents

1. [Configuration](#configuration)
2. [Usage instructions](#using-firebaseui-for-authentication)
Expand Down
187 changes: 14 additions & 173 deletions auth/src/main/java/com/firebase/ui/auth/AuthUI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,173 +60,14 @@
import java.util.Set;

/**
* The entry point to the AuthUI authentication flow, and related utility methods.
* If your application uses the default {@link FirebaseApp} instance, an AuthUI instance can
* be retrieved simply by calling {@link AuthUI#getInstance() AuthUI.getInstance()}.
* If an alternative app instance is in use, call
* {@link AuthUI#getInstance(FirebaseApp) AuthUI.getInstance(app} instead, passing the
* appropriate app instance.
* The entry point to the AuthUI authentication flow, and related utility methods. If your
* application uses the default {@link FirebaseApp} instance, an AuthUI instance can be retrieved
* simply by calling {@link AuthUI#getInstance()}. If an alternative app instance is in use, call
* {@link AuthUI#getInstance(FirebaseApp)} instead, passing the appropriate app instance.
* <p>
* <h2>Sign-in</h2>
* <p>
* If a user is not currently signed in (as can be determined by checking
* {@code auth.getCurrentUser() != null}, where {@code auth} is the {@link FirebaseAuth}
* associated with your {@link FirebaseApp}) then the sign-in process can be started by creating
* a sign-in intent using {@link SignInIntentBuilder}. A builder instance can be retrieved by
* calling {@link AuthUI#createSignInIntentBuilder()}.
* <p>
* <p>The builder provides the following customization options for the authentication flow
* implemented by this library:
* <p>
* <ul>
* <li>The set of authentication methods desired can be specified.</li>
* <li>The terms of service URL for your app can be specified, which is included as a link
* in the small-print of the account creation step for new users. If no terms of service
* URL is provided, the associated small-print is omitted.
* </li>
* <li>A custom theme can specified for the flow, which is applied to all the activities in
* the flow for consistent customization of colors and typography.
* </li>
* </ul>
* <p>
* <p>
* <h3>Sign-in examples</h3>
* <p>
* If no customization is required, and only email authentication is required, the sign-in flow
* can be started as follows:
* <p>
* <pre>
* {@code
* startActivityForResult(
* AuthUI.getInstance().createSignInIntentBuilder().build(),
* RC_SIGN_IN);
* }
* </pre>
* <p>
* If Google Sign-in and Facebook Sign-in are also required, then this can be replaced with:
* <p>
* <pre>
* {@code
* startActivityForResult(
* AuthUI.getInstance()
* .createSignInIntentBuilder()
* .setProviders(
* Arrays.asList(
* new IdpConfig.Builder(AuthUI.EMAIL_PROVIDER).build(),
* new IdpConfig.Builder(AuthUI.GOOGLE_PROVIDER).build(),
* new IdpConfig.Builder(AuthUI.FACEBOOK_PROVIDER).build()
* )
* )
* .build(),
* RC_SIGN_IN);
* }
* </pre>
* <p>
* Finally, if a terms of service URL and a custom theme are required:
* <p>
* <pre>
* {@code
* startActivityForResult(
* AuthUI.getInstance()
* .createSignInIntentBuilder()
* .setProviders(...)
* .setTosUrl("https://superapp.example.com/terms-of-service.html")
* .setTheme(R.style.SuperAppTheme)
* .build(),
* RC_SIGN_IN);
* }
* </pre>
* <p>
* <h3>Handling the Sign-in response</h3>
* <p>
* The authentication flow provides only two response codes:
* {@link ResultCodes#OK RESULT_OK} if a user is signed in,
* and {@link ResultCodes#CANCELED RESULT_CANCELLED} if sign in
* failed. No further information on failure is provided as it is not typically useful; the only
* recourse for most apps if sign in fails is to ask the user to sign in again later, or proceed
* with an anonymous account if supported.
* <p>
* <pre>
* {@code
* @Override
* protected void onActivityResult(int requestCode, int resultCode, Intent data) {
* super.onActivityResult(requestCode, resultCode, data);
* if (requestCode == RC_SIGN_IN) {
* if (resultCode == ResultCodes.OK) {
* // user is signed in!
* startActivity(new Intent(this, WelcomeBackActivity.class));
* finish();
* } else {
* // user is not signed in :(
* // Maybe just wait for the user to press "sign in" again, or show a message
* showSnackbar("Sign in is required to use this app.");
* }
* }
* }
* </pre>
* <p>
* <h2>Sign-out</h2>
* <p>
* With the integrations provided by AuthUI, signing out a user is a multi-stage process:
* <p>
* <ol>
* <li>The user must be signed out of the {@link FirebaseAuth} instance.</li>
* <li>Smart Lock for Passwords must be instructed to disable automatic sign-in, in
* order to prevent an automatic sign-in loop that prevents the user from switching
* accounts.
* </li>
* <li>If the current user signed in using either Google or Facebook, the user must also be
* signed out using the associated API for that authentication method. This typically
* ensures that the user will not be automatically signed-in using the current account
* when using that authentication method again from the authentication method picker, which
* would also prevent the user from switching between accounts on the same provider.
* </li>
* </ol>
* <p>
* In order to make this process easier, AuthUI provides a simple
* {@link AuthUI#signOut(Activity) signOut} method to encapsulate this behavior. The method returns
* a {@link Task} which is marked completed once all necessary sign-out operations are completed:
* <p>
* <pre>
* {@code
* public void onClick(View v) {
* if (v.getId() == R.id.sign_out) {
* AuthUI.getInstance()
* .signOut(this)
* .addOnCompleteListener(new OnCompleteListener<AuthResult>() {
* public void onComplete(@NonNull Task<AuthResult> task) {
* // user is now signed out
* startActivity(new Intent(MyActivity.this, SignInActivity.class));
* finish();
* });
* }
* }
* </pre>
* <p>
* <h2>IDP Provider configuration</h2>
* <p>
* Interacting with identity providers typically requires some additional client configuration.
* AuthUI currently supports Google Sign-in and Facebook Sign-in, and currently requires the
* basic configuration for these providers to be specified via string properties:
* <p>
* <ul>
* <p>
* <li>Google Sign-in: If your app build uses the
* <a href="https://developers.google.com/android/guides/google-services-plugin">Google
* Services Gradle Plugin</a>, no additional configuration is required. If not, please override
* {@code R.string.default_web_client_id} to provide your
* <a href="https://developers.google.com/identity/sign-in/web/devconsole-project">Google OAuth
* web client id.</a>
* </li>
* <p>
* <li>Facebook Sign-in: Please override the string resource
* {@code facebook_application_id} to provide the
* <a href="https://developers.facebook.com/docs/apps/register">App ID</a> for your app as
* registered on the
* <a href="https://developers.facebook.com/apps">Facebook Developer Dashboard</a>.
* </li>
* <p>
* </ul>
* See the <a href="https://github.com/firebase/FirebaseUI-Android/blob/master/auth/README.md#table-of-contents">README</a>
* for examples on how to get started with FirebaseUI Auth.
*/
public class AuthUI {

Expand All @@ -252,8 +93,7 @@ public class AuthUI {
public static final String TWITTER_PROVIDER = TwitterAuthProvider.PROVIDER_ID;

/**
* Default value for logo resource, omits the logo from the
* {@link AuthMethodPickerActivity}
* Default value for logo resource, omits the logo from the {@link AuthMethodPickerActivity}.
*/
public static final int NO_LOGO = -1;

Expand Down Expand Up @@ -304,8 +144,8 @@ public static AuthUI getInstance(FirebaseApp app) {
}

/**
* Default theme used by {@link SignInIntentBuilder#setTheme(int)} if no theme
* customization is required.
* Default theme used by {@link SignInIntentBuilder#setTheme(int)} if no theme customization is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a note for the future, including formatting changes like this that are unrelated to the functionality of the PR is distracting. I can normally look around it, but just wanted to point it out.

Is it your IDE settings that do this automatically?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samtstern Yeah, sorry. Intellij, just does that automatically when formatting stuff. (I should poke around and try to find where the setting is to disable it, but I've been lazy. I'll look into it at some point.)

* required.
*/
@StyleRes
public static int getDefaultTheme() {
Expand Down Expand Up @@ -524,9 +364,9 @@ public static class Builder {
/**
* Builds the configuration parameters for an identity provider.
*
* @param providerId An ID of one of the supported identity providers. e.g.
* {@link AuthUI#GOOGLE_PROVIDER}. See {@link AuthUI#SUPPORTED_PROVIDERS} for the
* complete list of supported Identity providers
* @param providerId An ID of one of the supported identity providers. e.g. {@link
* AuthUI#GOOGLE_PROVIDER}. See {@link AuthUI#SUPPORTED_PROVIDERS} for
* the complete list of supported Identity providers
*/
public Builder(@NonNull String providerId) {
if (!SUPPORTED_PROVIDERS.contains(providerId)) {
Expand All @@ -546,7 +386,8 @@ public Builder(@NonNull String providerId) {
* For Google permissions see:
* https://developers.google.com/identity/protocols/googlescopes
* <p>
* Twitter permissions are only configurable through the Twitter developer console.
* Twitter permissions are only configurable through the
* <a href="https://apps.twitter.com/">Twitter developer console</a>.
*/
public Builder setPermissions(List<String> permissions) {
mScopes = permissions;
Expand Down