Skip to content

Commit

Permalink
Updating the documentation to make it more clear how the `google-sign…
Browse files Browse the repository at this point in the history 
…in` works.

Also provides guidance on how to use the `google-signin-aware` with custom signin UIs.

Closes #143
  • Loading branch information
@Zoramite
Zoramite committed May 23, 2016
1 parent 106f9cf commit 7c2ee96
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 89 deletions.
88 changes: 46 additions & 42 deletions google-signin-aware.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -486,48 +486,52 @@

AuthEngine.init();

/**
`google-signin-aware` is used to enable authentication in custom elements by
interacting with a google-signin element that needs to be present somewhere
on the page.
The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API).
The `google-signin-aware-success` event is triggered when a user successfully
authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
authentication will also trigger the `google-signin-offline-success`event.
The `google-signin-aware-signed-out` event is triggered when a user explicitly
signs out via the google-signin element.
You can bind to `isAuthorized` property to monitor authorization state.
##### Example
<google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>
##### Example with offline
<template id="awareness" is="dom-bind">
<google-signin-aware
scopes="https://www.googleapis.com/auth/drive"
offline
on-google-signin-aware-success="handleSignin"
on-google-signin-offline-success="handleOffline"></google-signin-aware>
<\/template>
<script>
var aware = document.querySelector('#awareness');
aware.handleSignin = function(response) {
var user = gapi.auth2.getAuthInstance().currentUser.get();
console.log('User name: ' + user.getBasicProfile().getName());
};
aware.handleOffline = function(response) {
console.log('Offline code received: ' + response.detail.code);
// Here you would POST response.detail.code to your webserver, which can
// exchange the authorization code for an access token. More info at:
// https://developers.google.com/identity/protocols/OAuth2WebServer
};
<\/script>
*/
/**
`<google-signin-aware>` is used to enable authentication in custom elements.
The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API).
The `google-signin-aware-success` event is triggered when a user successfully
authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
authentication will also trigger the `google-signin-offline-success`event.
The `google-signin-aware-signed-out` event is triggered when a user explicitly
signs out via the google-signin element.
You can bind to `isAuthorized` property to monitor authorization state.
The `<google-signin>` element provides the standard Google signin button UI and should be placed
within the application to allow the user to trigger the authentication. When opting to use a
custom signin UI, trigger the authentication by calling the `signin()` method of the
`<google-signin-aware>` component.
#### Example
<google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>
#### Example with offline
<template id="awareness" is="dom-bind">
<google-signin-aware
scopes="https://www.googleapis.com/auth/drive"
offline
on-google-signin-aware-success="handleSignin"
on-google-signin-offline-success="handleOffline"></google-signin-aware>
<\/template>
<script>
var aware = document.querySelector('#awareness');
aware.handleSignin = function(response) {
var user = gapi.auth2.getAuthInstance().currentUser.get();
console.log('User name: ' + user.getBasicProfile().getName());
};
aware.handleOffline = function(response) {
console.log('Offline code received: ' + response.detail.code);
// Here you would POST response.detail.code to your webserver, which can
// exchange the authorization code for an access token. More info at:
// https://developers.google.com/identity/protocols/OAuth2WebServer
};
<\/script>
*/
Polymer({

is: 'google-signin-aware',
Expand Down
94 changes: 47 additions & 47 deletions google-signin.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,73 +118,73 @@
WIDE: 'wide'
};

/**
&lt;google-signin&gt; is used to authenticate with Google, allowing you to interact
with other Google APIs such as Drive and Google+.
<img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>
If you do not need to show the button, use companion `<google-signin-aware>` element to declare scopes, check authentication state.
/**
`<google-signin>` is used to authenticate with Google, allowing you to interact
with other Google APIs such as Drive and Google+.
#### Examples
<img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>
<google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
#### Examples
<google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
#### Notes
#### Notes
The attribute `clientId` is provided in your Google Developers Console
(https://console.developers.google.com).
If you do not want to display the signin button, use the `<google-signin-aware>` element to
declare scopes and listen for authentication events. If there is no `<google-signin>` element on
the page the `<google-signin-aware>.signIn()` will need to be manually triggered.
The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API). Many APIs also
need to be enabled in the Google Developers Console before you can use them.
The attribute `clientId` is provided in your Google Developers Console
(https://console.developers.google.com).
The `requestVisibleActions` attribute is necessary if you want to write app
activities (https://developers.google.com/+/web/app-activities/) on behalf of
the user. Please note that this attribute is only valid in combination with the
plus.login scope (https://www.googleapis.com/auth/plus.login).
The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API). Many APIs also
need to be enabled in the Google Developers Console before you can use them.
The `offline` attribute allows you to get an auth code which your server can
redeem for an offline access token
(https://developers.google.com/identity/sign-in/web/server-side-flow).
You can also set `offline-always-prompt` instead of `offline` to ensure that your app
will re-prompt the user for offline access and generate a working `refresh_token`
even if they have already granted offline access to your app in the past.
The `requestVisibleActions` attribute is necessary if you want to write app
activities (https://developers.google.com/+/web/app-activities/) on behalf of
the user. Please note that this attribute is only valid in combination with the
plus.login scope (https://www.googleapis.com/auth/plus.login).
Use label properties to customize prompts.
The `offline` attribute allows you to get an auth code which your server can
redeem for an offline access token
(https://developers.google.com/identity/sign-in/web/server-side-flow).
You can also set `offline-always-prompt` instead of `offline` to ensure that your app
will re-prompt the user for offline access and generate a working `refresh_token`
even if they have already granted offline access to your app in the past.
The button can be styled in using the `height`, `width`, and `theme` attributes.
These attributes help you follow the Google+ Sign-In button branding guidelines
(https://developers.google.com/+/branding-guidelines).
Use label properties to customize prompts.
The `google-signin-success` event is triggered when a user successfully authenticates
and `google-signed-out` is triggered when user signs out.
You can also use `isAuthorized` attribute to observe user's authentication state.
The button can be styled in using the `height`, `width`, and `theme` attributes.
These attributes help you follow the Google+ Sign-In button branding guidelines
(https://developers.google.com/+/branding-guidelines).
Additional events, such as `google-signout-attempted` are
triggered when the user attempts to sign-out and successfully signs out.
The `google-signin-success` event is triggered when a user successfully authenticates
and `google-signed-out` is triggered when user signs out.
You can also use `isAuthorized` attribute to observe user's authentication state.
When requesting offline access, the `google-signin-offline-success` event is
triggered when the user successfully consents with offline support.
Additional events, such as `google-signout-attempted` are
triggered when the user attempts to sign-out and successfully signs out.
The `google-signin-necessary` event is fired when scopes requested via
google-signin-aware elements require additional user permissions.
When requesting offline access, the `google-signin-offline-success` event is
triggered when the user successfully consents with offline support.
#### Testing
The `google-signin-necessary` event is fired when scopes requested via
google-signin-aware elements require additional user permissions.
By default, the demo accompanying this element is setup to work on localhost with
port 8080. That said, you *should* update the `clientId` to your own one for
any apps you're building. See the Google Developers Console
(https://console.developers.google.com) for more info.
#### Testing
@demo
*/
By default, the demo accompanying this element is setup to work on localhost with
port 8080. That said, you *should* update the `clientId` to your own one for
any apps you're building. See the Google Developers Console
(https://console.developers.google.com) for more info.
@demo
*/
Polymer({

is: 'google-signin',
Expand Down

0 comments on commit 7c2ee96

Please sign in to comment.