From 12b3d59d18d748c898d41654f1becd5480dded73 Mon Sep 17 00:00:00 2001 From: Michael McGuiness Date: Wed, 13 Dec 2023 11:07:53 -0800 Subject: [PATCH] [google_sign_in] Adopt code excerpts in README (#5521) Improves README example and updates it to use code excerpts. Part of [flutter/flutter#102679](https://github.com/flutter/flutter/issues/102679) --- .../google_sign_in/CHANGELOG.md | 4 +++ .../google_sign_in/google_sign_in/README.md | 33 +++++++++++-------- .../google_sign_in/example/lib/main.dart | 12 ++++++- .../google_sign_in/pubspec.yaml | 2 +- script/configs/temp_exclude_excerpt.yaml | 1 - 5 files changed, 35 insertions(+), 17 deletions(-) diff --git a/packages/google_sign_in/google_sign_in/CHANGELOG.md b/packages/google_sign_in/google_sign_in/CHANGELOG.md index e9c5ac2ef9..a010d955f9 100644 --- a/packages/google_sign_in/google_sign_in/CHANGELOG.md +++ b/packages/google_sign_in/google_sign_in/CHANGELOG.md @@ -1,3 +1,7 @@ +## 6.2.1 + +* Improves README example and updates it to use code excerpts. + ## 6.2.0 * Adds support for macOS. diff --git a/packages/google_sign_in/google_sign_in/README.md b/packages/google_sign_in/google_sign_in/README.md index ed58237dbb..1b94f5d069 100644 --- a/packages/google_sign_in/google_sign_in/README.md +++ b/packages/google_sign_in/google_sign_in/README.md @@ -68,20 +68,19 @@ To use this plugin, follow the ### Use the plugin -Add the following import to your Dart code: - -```dart -import 'package:google_sign_in/google_sign_in.dart'; -``` - Initialize `GoogleSignIn` with the scopes you want: + ```dart +const List scopes = [ + 'email', + 'https://www.googleapis.com/auth/contacts.readonly', +]; + GoogleSignIn _googleSignIn = GoogleSignIn( - scopes: [ - 'email', - 'https://www.googleapis.com/auth/contacts.readonly', - ], + // Optional clientId + // clientId: 'your-client_id.apps.googleusercontent.com', + scopes: scopes, ); ``` @@ -89,6 +88,7 @@ GoogleSignIn _googleSignIn = GoogleSignIn( You can now use the `GoogleSignIn` class to authenticate in your Dart code, e.g. + ```dart Future _handleSignIn() async { try { @@ -122,8 +122,14 @@ Applications must be able to: There's a new method that enables the checks above, `canAccessScopes`: + ```dart -final bool isAuthorized = await _googleSignIn.canAccessScopes(scopes); +// In mobile, being authenticated means being authorized... +bool isAuthorized = account != null; +// However, on web... +if (kIsWeb && account != null) { + isAuthorized = await _googleSignIn.canAccessScopes(scopes); +} ``` _(Only implemented in the web platform, from version 6.1.0 of this package)_ @@ -134,14 +140,13 @@ If an app determines that the user hasn't granted the scopes it requires, it should initiate an Authorization request. (Remember that in the web platform, this request **must be initiated from an user interaction**, like a button press). + ```dart Future _handleAuthorizeScopes() async { final bool isAuthorized = await _googleSignIn.requestScopes(scopes); if (isAuthorized) { - // Do things that only authorized users can do! - _handleGetContact(_currentUser!); + unawaited(_handleGetContact(_currentUser!)); } -} ``` The `requestScopes` returns a `boolean` value that is `true` if the user has diff --git a/packages/google_sign_in/google_sign_in/example/lib/main.dart b/packages/google_sign_in/google_sign_in/example/lib/main.dart index a103353c79..576ec36fef 100644 --- a/packages/google_sign_in/google_sign_in/example/lib/main.dart +++ b/packages/google_sign_in/google_sign_in/example/lib/main.dart @@ -15,6 +15,7 @@ import 'package:http/http.dart' as http; import 'src/sign_in_button.dart'; /// The scopes required by this application. +// #docregion Initialize const List scopes = [ 'email', 'https://www.googleapis.com/auth/contacts.readonly', @@ -25,6 +26,7 @@ GoogleSignIn _googleSignIn = GoogleSignIn( // clientId: 'your-client_id.apps.googleusercontent.com', scopes: scopes, ); +// #enddocregion Initialize void main() { runApp( @@ -55,12 +57,14 @@ class _SignInDemoState extends State { _googleSignIn.onCurrentUserChanged .listen((GoogleSignInAccount? account) async { +// #docregion CanAccessScopes // In mobile, being authenticated means being authorized... bool isAuthorized = account != null; - // However, in the web... + // However, on web... if (kIsWeb && account != null) { isAuthorized = await _googleSignIn.canAccessScopes(scopes); } +// #enddocregion CanAccessScopes setState(() { _currentUser = account; @@ -136,6 +140,7 @@ class _SignInDemoState extends State { // // On the web, the on-click handler of the Sign In button is owned by the JS // SDK, so this method can be considered mobile only. + // #docregion SignIn Future _handleSignIn() async { try { await _googleSignIn.signIn(); @@ -143,6 +148,7 @@ class _SignInDemoState extends State { print(error); } } + // #enddocregion SignIn // Prompts the user to authorize `scopes`. // @@ -150,14 +156,18 @@ class _SignInDemoState extends State { // and Authorization at the same time (like the web). // // On the web, this must be called from an user interaction (button click). + // #docregion RequestScopes Future _handleAuthorizeScopes() async { final bool isAuthorized = await _googleSignIn.requestScopes(scopes); + // #enddocregion RequestScopes setState(() { _isAuthorized = isAuthorized; }); + // #docregion RequestScopes if (isAuthorized) { unawaited(_handleGetContact(_currentUser!)); } + // #enddocregion RequestScopes } Future _handleSignOut() => _googleSignIn.disconnect(); diff --git a/packages/google_sign_in/google_sign_in/pubspec.yaml b/packages/google_sign_in/google_sign_in/pubspec.yaml index 77470e3c0e..08fd7e39fe 100644 --- a/packages/google_sign_in/google_sign_in/pubspec.yaml +++ b/packages/google_sign_in/google_sign_in/pubspec.yaml @@ -3,7 +3,7 @@ description: Flutter plugin for Google Sign-In, a secure authentication system for signing in with a Google account. repository: https://github.com/flutter/packages/tree/main/packages/google_sign_in/google_sign_in issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+google_sign_in%22 -version: 6.2.0 +version: 6.2.1 environment: sdk: ">=3.2.0 <4.0.0" diff --git a/script/configs/temp_exclude_excerpt.yaml b/script/configs/temp_exclude_excerpt.yaml index 7bb162be1e..7d56d427ed 100644 --- a/script/configs/temp_exclude_excerpt.yaml +++ b/script/configs/temp_exclude_excerpt.yaml @@ -8,7 +8,6 @@ - espresso - extension_google_sign_in_as_googleapis_auth - go_router_builder -- google_sign_in/google_sign_in - image_picker_for_web - in_app_purchase/in_app_purchase - ios_platform_images