Add migration notes to the README.

Author: ditman

packages/google_sign_in/google_sign_in_web/CHANGELOG.md

@@ -2,16 +2,7 @@
 
 * **Breaking Change:** Migrates JS-interop to `package:google_identity_services_web`
   * Uses the new Google Identity Authentication and Authorization JS SDKs. [Docs](https://developers.google.com/identity).
-  * TODO: Move the below to a migration instructions doc in the README.
-  * Authentication and Authorization are now two separate concerns.
-  * `signInSilently` now displays the One Tap UX for web. The SDK no longer has
-    direct access to previously-seen users.
-  * The new SDK only provides an `idToken` when the user does `signInSilently`.
-  * The plugin attempts to mimic the old behavior (of retrieving Profile information
-    on `signIn`) but in that case, the `idToken` is not returned.
-  * The plugin no longer is able to renew Authorization sessions on the web.
-    Once the session expires, API requests will begin to fail with unauthorized,
-    and user Authorization is required again.
+    * Added "Migrating to v0.11" section to the `README.md`.
 * Updates minimum Flutter version to 3.0.
 
 ## 0.10.2+1

packages/google_sign_in/google_sign_in_web/README.md

@@ -2,6 +2,87 @@
 
 The web implementation of [google_sign_in](https://pub.dev/packages/google_sign_in)
 
+## Migrating to v0.11 (Google Identity Services)
+
+The `google_sign_in_web` plugin is backed by the new Google Identity Services
+JS SDK since version 0.11.0.
+
+The new SDK is used both for [Authentication](https://developers.google.com/identity/gsi/web/guides/overview)
+and [Authorization](https://developers.google.com/identity/oauth2/web/guides/overview) flows.
+
+The new SDK, however, doesn't behave exactly like the one being deprecated.
+Some concepts have experienced pretty drastic changes, and that's why this
+required a major version update.
+
+### Key differences between the SDK
+
+* For the SDK, Authentication and Authorization are now two separate concerns.
+  * Authentication (information about the current user) flows will not
+    authorize `scopes` anymore.
+  * Authorization (permissions for the app to access certain user information)
+    flows will not return authentication information.
+* The SDK no longer has direct access to previously-seen users upon initialization.
+  * `signInSilently` now displays the One Tap UX for web.
+* The new SDK only provides an `idToken` (JWT-encoded info) when the user
+  successfully completes `signInSilently`.
+* `signIn` uses the Oauth "Implicit Flow" to Authorize the requested `scopes`.
+  * If the user hasn't `signInSilently`, they'll have to sign in as a first step
+    of the Authorization popup flow.
+  * If `signInSilently` was unsuccessful, the plugin will add extra `scopes` to
+    `signIn` and retrieve basic Profile information from the People API via a
+    REST call immediately after a successful authorization. In this case, the
+    `idToken` field of the `GoogleSignInUserData` will always be null.
+* The SDK no longer handles sign-in state and user sessions, it only provides
+  Authentication credentials for the moment the user did authenticate.
+* The SDK no longer is able to renew Authorization sessions on the web.
+  Once the token expires, API requests will begin to fail with unauthorized,
+  and user Authorization is required again.
+
+See more differences in the following migration guides:
+
+* Authentication > [Migrating from Google Sign-In](https://developers.google.com/identity/gsi/web/guides/migration)
+* Authorization > [Migrate to Google Identity Services](https://developers.google.com/identity/oauth2/web/guides/migration-to-gis)
+
+### New use cases to take into account in your app
+
+#### User Sessions
+
+Since the new SDK does *not* manage user sessions anymore, apps that relied on
+this feature might break.
+
+If long-lived sessions are required, consider using some User authentication
+system that supports Google Sign In as a federated Authentication provider,
+like [Firebase Auth](https://firebase.google.com/docs/auth/flutter/federated-auth#google),
+or similar (expand this list as other providers become generally available for
+Flutter web).
+
+#### Expired / Invalid Authorization Tokens
+
+Since the new SDK does *not* auto-renew authorization tokens anymore, it's now
+the responsibility of your app to do so.
+
+Apps now need to monitor the status code of their REST API requests for response
+codes different to `200`. For example:
+
+* `401`: Missing or invalid access token.
+* `403`: Expired access token.
+
+In either case, your app needs to prompt the end user to `signIn` again, to
+interactively renew the token. The GIS SDK limits authorization token duration
+to one hour (3600 seconds).
+
+#### Null `idToken`
+
+The `GoogleSignInUserData` returned after `signIn` may contain a `null` `idToken`
+field. This is not an indication of the session being invalid, it's just that
+the user canceled (or wasn't presented with) the OneTap UX from `signInSilently`.
+
+In cases where the OneTap UX does not authenticate the user, the `signIn` method
+will attempt to "fill in the gap" by requesting basic profile information of the
+currently signed-in user.
+
+In that case, the `GoogleSignInUserData` will contain a `null` `idToken`.
+
 ## Usage
 
 ### Import the package
@@ -12,7 +93,7 @@ normally. This package will be automatically included in your app when you do.
 
 ### Web integration
 
-First, go through the instructions [here](https://developers.google.com/identity/sign-in/web/sign-in#before_you_begin) to create your Google Sign-In OAuth client ID.
+First, go through the instructions [here](https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid) to create your Google Sign-In OAuth client ID.
 
 On your `web/index.html` file, add the following `meta` tag, somewhere in the
 `head` of the document:
@@ -29,7 +110,10 @@ You can do this by:
 2. Clicking "Edit" in the OAuth 2.0 Web application client that you created above.
 3. Adding the URIs you want to the **Authorized JavaScript origins**.
 
-For local development, may add a `localhost` entry, for example: `http://localhost:7357`
+For local development, you must add two `localhost` entries:
+
+* `http://localhost` and
+* `http://localhost:7357` (or any port that is free in your machine)
 
 #### Starting flutter in http://localhost:7357
 
@@ -45,48 +129,19 @@ flutter run -d chrome --web-hostname localhost --web-port 7357
 
 Read the rest of the instructions if you need to add extra APIs (like Google People API).
 
-
 ### Using the plugin
-Add the following import to your Dart code:
 
-```dart
-import 'package:google_sign_in/google_sign_in.dart';
-```
+See the [**Usage** instructions of `package:google_sign_in`](https://pub.dev/packages/google_sign_in#usage)
 
-Initialize GoogleSignIn with the scopes you want:
-
-```dart
-GoogleSignIn _googleSignIn = GoogleSignIn(
-  scopes: [
-    'email',
-    'https://www.googleapis.com/auth/contacts.readonly',
-  ],
-);
-```
-
-[Full list of available scopes](https://developers.google.com/identity/protocols/googlescopes).
-
-Note that the `serverClientId` parameter of the `GoogleSignIn` constructor is not supported on Web.
-
-You can now use the `GoogleSignIn` class to authenticate in your Dart code, e.g.
-
-```dart
-Future<void> _handleSignIn() async {
-  try {
-    await _googleSignIn.signIn();
-  } catch (error) {
-    print(error);
-  }
-}
-```
+Note that the **`serverClientId` parameter of the `GoogleSignIn` constructor is not supported on Web.**
 
 ## Example
 
 Find the example wiring in the [Google sign-in example application](https://github.com/flutter/plugins/blob/main/packages/google_sign_in/google_sign_in/example/lib/main.dart).
 
 ## API details
 
-See the [google_sign_in.dart](https://github.com/flutter/plugins/blob/main/packages/google_sign_in/google_sign_in/lib/google_sign_in.dart) for more API details.
+See [google_sign_in.dart](https://github.com/flutter/plugins/blob/main/packages/google_sign_in/google_sign_in/lib/google_sign_in.dart) for more API details.
 
 ## Contributions and Testing