@@ -6,182 +6,145 @@ A Flutter plugin for [Google Sign In](https://developers.google.com/identity/).
66| -------------| ---------| -------| --------| -----|
77| ** Support** | SDK 21+ | 12.0+ | 10.15+ | Any |
88
9- ## Platform integration
9+ ## Setup
1010
11- ### Android integration
12-
13- To access Google Sign-In, you'll need to make sure to
14- [ register your application] ( https://firebase.google.com/docs/android/setup ) .
15-
16- You don't need to include the google-services.json file in your app unless you
17- are using Google services that require it. You do need to enable the OAuth APIs
18- that you want, using the
19- [ Google Cloud Platform API manager] ( https://console.developers.google.com/ ) . For
20- example, if you want to mimic the behavior of the Google Sign-In sample app,
21- you'll need to enable the
22- [ Google People API] ( https://developers.google.com/people/ ) .
23-
24- Make sure you've filled out all required fields in the console for
25- [ OAuth consent screen] ( https://console.developers.google.com/apis/credentials/consent ) .
26- Otherwise, you may encounter ` APIException ` errors.
27-
28- ### iOS integration
29-
30- Please see [ instructions on integrating Google Sign-In for iOS] ( https://pub.dev/packages/google_sign_in_ios#ios-integration ) .
31-
32- #### iOS additional requirement
33-
34- Note that according to
35- https://developer.apple.com/sign-in-with-apple/get-started , starting June 30,
36- 2020, apps that use login services must also offer a "Sign in with Apple" option
37- when submitting to the Apple App Store.
38-
39- Consider also using an Apple sign in plugin from pub.dev.
40-
41- The Flutter Favorite
42- [ sign_in_with_apple] ( https://pub.dev/packages/sign_in_with_apple ) plugin could
43- be an option.
44-
45- ### macOS integration
46-
47- Please see [ instructions on integrating Google Sign-In for macOS] ( https://pub.dev/packages/google_sign_in_ios#macos-setup ) .
48-
49- ### Web integration
11+ ### Import the package
5012
51- The new SDK used by the web has fully separated Authentication from Authorization,
52- so ` signIn ` and ` signInSilently ` no longer authorize OAuth ` scopes ` .
13+ To use this plugin, follow the
14+ [ plugin installation instructions] ( https://pub.dev/packages/google_sign_in/install ) ,
15+ then follow the platform integration steps below for all platforms you support.
5316
54- Flutter apps must be able to detect what scopes have been granted by their users,
55- and if the grants are still valid.
17+ ### Platform integration
5618
57- Read below about ** Working with scopes, and incremental authorization ** for
58- general information about changes that may be needed on an app, and for more
59- specific web integration details, see the
60- [ ` google_sign_in_web ` package ] ( https://pub.dev/packages/google_sign_in_web ) .
19+ * ** Android ** : Please see [ the ` google_sign_in_android ` README ] ( https://pub.dev/packages/google_sign_in_android#integration ) .
20+ * ** iOS ** : Please see [ the ` google_sign_in_ios ` README ] ( https://pub.dev/packages/google_sign_in_ios#ios-integration ) .
21+ * ** macOS ** : Please see [ the ` google_sign_in_ios ` README ] ( https://pub.dev/packages/google_sign_in_ios#macos-integration ) (which also supports macOS).
22+ * ** Web ** : Please see [ the ` google_sign_in_web ` README ] ( https://pub.dev/packages/google_sign_in_web#integration ) .
6123
6224## Usage
6325
64- ### Import the package
26+ ### Initialization and authentication
6527
66- To use this plugin, follow the
67- [ plugin installation instructions ] ( https://pub.dev/packages/google_sign_in/install ) .
28+ Initialize the ` GoogleSignIn ` instance, and (optionally) start the lightweight
29+ authentication process:
6830
69- ### Use the plugin
70-
71- Initialize ` GoogleSignIn ` with the scopes you want:
72-
73- <? code-excerpt "example/lib/main.dart (Initialize)"?>
31+ <? code-excerpt "example/lib/main.dart (Setup)"?>
7432``` dart
75- const List<String> scopes = <String>[
76- 'email',
77- 'https://www.googleapis.com/auth/contacts.readonly',
78- ];
79-
80- GoogleSignIn _googleSignIn = GoogleSignIn(
81- // Optional clientId
82- // clientId: 'your-client_id.apps.googleusercontent.com',
83- scopes: scopes,
84- );
33+ final GoogleSignIn signIn = GoogleSignIn.instance;
34+ unawaited(signIn
35+ .initialize(clientId: clientId, serverClientId: serverClientId)
36+ .then((_) {
37+ signIn.authenticationEvents
38+ .listen(_handleAuthenticationEvent)
39+ .onError(_handleAuthenticationError);
40+
41+ /// This example always uses the stream-based approach to determining
42+ /// which UI state to show, rather than using the future returned here,
43+ /// if any, to conditionally skip directly to the signed-in state.
44+ signIn.attemptLightweightAuthentication();
45+ }));
8546```
8647
87- [ Full list of available scopes] ( https://developers.google.com/identity/protocols/googlescopes ) .
88-
89- You can now use the ` GoogleSignIn ` class to authenticate in your Dart code, e.g.
48+ If the user isn't signed in by the lightweight method, you can show UI to
49+ start a sign-in flow. This uses ` authenticate ` on platforms that return true
50+ for ` supportsAuthenticate ` , otherwise applications should fall back to a
51+ platform-specific approach. For instance, user-initiated sign in on web must
52+ use a button rendered by the sign in SDK, rather than application-provided
53+ UI:
9054
91- <? code-excerpt "example/lib/main.dart (SignIn )"?>
55+ <? code-excerpt "example/lib/main.dart (ExplicitSignIn )"?>
9256``` dart
93- Future<void> _handleSignIn() async {
94- try {
95- await _googleSignIn.signIn();
96- } catch (error) {
97- print(error);
98- }
99- }
57+ if (GoogleSignIn.instance.supportsAuthenticate())
58+ ElevatedButton(
59+ onPressed: () async {
60+ try {
61+ await GoogleSignIn.instance.authenticate();
62+ } catch (e) {
63+ // ···
64+ }
65+ },
66+ child: const Text('SIGN IN'),
67+ )
68+ else ...<Widget>[
69+ if (kIsWeb)
70+ web.renderButton()
71+ // ···
72+ ]
10073```
10174
102- In the web, you should use the ** Google Sign In button** (and not the ` signIn ` method)
103- to guarantee that your user authentication contains a valid ` idToken ` .
104-
105- For more details, take a look at the
106- [ ` google_sign_in_web ` package] ( https://pub.dev/packages/google_sign_in_web ) .
107-
108- ## Working with scopes, and incremental authorization.
109-
110- If your app supports both mobile and web, read this section!
75+ ## Authorization
11176
11277### Checking if scopes have been granted
11378
114- Users may (or may * not* ) grant all the scopes that an application requests at
115- Sign In. In fact, in the web, no scopes are granted by ` signIn ` , ` silentSignIn `
116- or the ` renderButton ` widget anymore.
117-
118- Applications must be able to:
119-
120- * Detect if the authenticated user has authorized the scopes they need.
121- * Determine if the scopes that were granted a few minutes ago are still valid.
122-
123- There's a new method that enables the checks above, ` canAccessScopes ` :
79+ If the user has previously authorized the scopes required by your application,
80+ you can silently request an access token for those scopes:
12481
125- <? code-excerpt "example/lib/main.dart (CanAccessScopes) "?>
82+ <? code-excerpt "example/lib/main.dart (CheckAuthorization)" plaster="none "?>
12683``` dart
127- // In mobile, being authenticated means being authorized...
128- bool isAuthorized = account != null;
129- // However, on web...
130- if (kIsWeb && account != null) {
131- isAuthorized = await _googleSignIn.canAccessScopes(scopes);
132- }
84+ const List<String> scopes = <String>[
85+ 'https://www.googleapis.com/auth/contacts.readonly',
86+ ];
87+ final GoogleSignInAccount? user = // ...
88+ final GoogleSignInClientAuthorization? authorization =
89+ await user?.authorizationClient.authorizationForScopes(scopes);
13390```
13491
135- _ (Only implemented in the web platform, from version 6.1.0 of this package) _
92+ [ Full list of available scopes ] ( https://developers.google.com/identity/protocols/googlescopes ) .
13693
13794### Requesting more scopes when needed
13895
13996If an app determines that the user hasn't granted the scopes it requires, it
140- should initiate an Authorization request. (Remember that in the web platform,
141- this request ** must be initiated from an user interaction** , like a button press).
97+ should initiate an Authorization request. On platforms where
98+ ` authorizationRequiresUserInteraction() ` returns true,
99+ this request ** must be initiated from a user interaction** like a button press.
142100
143- <? code-excerpt "example/lib/main.dart (RequestScopes)" plaster="none" ?>
101+ <? code-excerpt "example/lib/main.dart (RequestScopes)"?>
144102``` dart
145- Future<void> _handleAuthorizeScopes() async {
146- final bool isAuthorized = await _googleSignIn.requestScopes(scopes);
147- if (isAuthorized) {
148- unawaited(_handleGetContact(_currentUser!));
149- }
103+ final GoogleSignInClientAuthorization authorization =
104+ await user.authorizationClient.authorizeScopes(scopes);
150105```
151106
152- The ` requestScopes ` returns a ` boolean ` value that is ` true ` if the user has
153- granted all the requested scopes or ` false ` otherwise.
154-
155- Once your app determines that the current user ` isAuthorized ` to access the
156- services for which you need ` scopes ` , it can proceed normally.
157-
158107### Authorization expiration
159108
160109In the web, ** the ` accessToken ` is no longer refreshed** . It expires after 3600
161110seconds (one hour), so your app needs to be able to handle failed REST requests,
162111and update its UI to prompt the user for a new Authorization round.
163112
164113This can be done by combining the error responses from your REST requests with
165- the ` canAccessScopes ` and ` requestScopes ` methods described above.
114+ the authorization methods described above.
166115
167116For more details, take a look at the
168117[ ` google_sign_in_web ` package] ( https://pub.dev/packages/google_sign_in_web ) .
169118
170- ### Does an app always need to check ` canAccessScopes ` ?
119+ ### Requesting a server auth code
171120
172- The new web SDK implicitly grant access to the ` email ` , ` profile ` and ` openid `
173- scopes when users complete the sign-in process (either via the One Tap UX or the
174- Google Sign In button).
121+ If your application needs to access user data from a backend server, you can
122+ request a server auth code to send to the server:
175123
176- If an app only needs an ` idToken ` , or only requests permissions to any/all of
177- the three scopes mentioned above
178- ([ OpenID Connect scopes] ( https://developers.google.com/identity/protocols/oauth2/scopes#openid-connect ) ),
179- it won't need to implement any additional scope handling.
124+ <? code-excerpt "example/lib/main.dart (RequestServerAuth)"?>
125+ ``` dart
126+ final GoogleSignInServerAuthorization? serverAuth =
127+ await user.authorizationClient.authorizeServer(scopes);
128+ ```
129+
130+ Server auth codes are not always available on all platforms. For instance, on
131+ some platforms they may only be returned when a user initially signs in, and
132+ not for subsequent authentications via the lightweight process. If you
133+ need a server auth code you should request it as soon as possible after initial
134+ sign-in, and manage server tokens for that user entirely on the server side
135+ unless the signed in user changes.
180136
181- If an app needs any scope other than ` email ` , ` profile ` and ` openid ` , it ** must **
182- implement a more complete scope handling, as described above .
137+ On platforms where ` authorizationRequiresUserInteraction() ` returns true,
138+ this request ** must be initiated from a user interaction ** like a button press .
183139
184140## Example
185141
186- Find the example wiring in the
187- [ Google sign-in example application] ( https://github.com/flutter/packages/blob/main/packages/google_sign_in/google_sign_in/example/lib/main.dart ) .
142+ The
143+ [ Google Sign-In example application] ( https://github.com/flutter/packages/blob/main/packages/google_sign_in/google_sign_in/example/lib/main.dart ) demonstrates one approach to using this
144+ package to sign a user in and authorize access to specific user data.
145+
146+ ## Migration from pre-7.0 versions
147+
148+ If you used version 6.x or earlier of ` google_sign_in ` , see
149+ [ the migration guide] ( https://github.com/flutter/packages/blob/main/packages/google_sign_in/google_sign_in/MIGRATION.md )
150+ for more information about the changes.
0 commit comments