このリファレンスでは、ウェブ アプリケーションに Google ログインを実装するために使用する JavaScript クライアントのメソッドと属性について説明します。
ライブラリの使用中に問題が発生した場合は、GitHub リポジトリに報告してください。
認証の設定
Google API プラットフォーム ライブラリを読み込んで gapi
オブジェクトを作成します。
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
プラットフォーム ライブラリが読み込まれたら、auth2
ライブラリを読み込みます。
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
GoogleAuth
オブジェクトを初期化します。gapi.auth2.GoogleAuth
のメソッドを呼び出す前に、このメソッドを呼び出す必要があります。
GoogleAuth
オブジェクトを初期化するときに、OAuth 2.0 クライアント ID と追加オプションを指定してオブジェクトを構成します。ユーザーがすでにログインしている場合、GoogleAuth
オブジェクトはユーザーのログイン状態を前回のセッションから復元します。
引数 | |
---|---|
params |
クライアント構成データの Key-Value ペアを含むオブジェクト。構成可能な別のプロパティについては、gapi.auth2.ClientConfig をご覧ください。次に例を示します。
{ client_id: 'CLIENT_ID.apps.googleusercontent.com' } |
戻り値 | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth オブジェクト。then() メソッドを使用して、gapi.auth2.GoogleAuth オブジェクトの初期化が完了したときに解決される Promise を取得します。 |
GoogleAuth.then(onInit、onError)
GoogleAuth
オブジェクトが完全に初期化されたときに、onInit 関数を呼び出します。初期化中にエラーが発生した場合(サポートされていない古いブラウザで発生している可能性があります)、代わりに onError 関数が呼び出されます。
引数 | |
---|---|
onInit |
完全に初期化されたときに GoogleAuth オブジェクトで呼び出される関数。
|
onError |
GoogleAuth の初期化に失敗した場合に、error プロパティを含むオブジェクトで呼び出される関数。
|
戻り値 | |
---|---|
Promise | Promise 。onInit 関数が完了すると実行され、初期化エラーが発生した場合は拒否されます。これは、onInit 関数から返された値(存在する場合)で解決されます。 |
エラーコード
idpiframe_initialization_failed
-
サポートされていない環境などが原因で、Google から必要な iframe を初期化できませんでした。
details
プロパティは、発生したエラーに関する詳細情報を提供します。
gapi.auth2.ClientConfig
gapi.auth2.init
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
client_id |
string |
必須。Google Developers Console で取得、作成されたアプリのクライアント ID。 |
cookie_policy |
string |
ログイン Cookie を作成するドメイン。URI、single_host_origin 、none のいずれか。指定しない場合のデフォルトは single_host_origin です。 |
scope |
string |
リクエストするスコープ。スペース区切りの文字列で指定します。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
fetch_basic_profile |
boolean |
ユーザーがログインしたときにユーザーの基本的なプロフィール情報を取得します。リクエストされたスコープに「profile」、「email」、「openid」を追加します。指定しない場合は true。 |
hosted_domain |
string |
ユーザーがログインするために所属する G Suite ドメイン。これはクライアントによって変更される可能性があるため、返されたユーザーのホストされているドメイン プロパティを必ず確認してください。クライアントで GoogleUser.getHostedDomain() を使用し、サーバーの ID トークンの hd クレームを使用して、ドメインが想定どおりであることを確認します。 |
ux_mode |
string |
ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popup と redirect です。 |
redirect_uri |
string |
ux_mode='redirect' を使用している場合、このパラメータを使用すると、同意フローの最後で使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、クエリ パラメータとハッシュ フラグメントが削除された現在の URL です。 |
enable_granular_consent |
boolean |
省略可。きめ細かい権限を有効にするかどうか。false に設定すると、2019 年より前に作成された OAuth クライアント ID に対して、より詳細な Google アカウントの権限が無効になります。2019 年中またはそれ以降に作成された OAuth クライアント ID には、よりきめ細かい権限が常に有効になるため、影響はありません。 |
plugin_name |
string |
省略可。この値が設定されている場合、2022 年 7 月 29 日より前に作成された新しいクライアント ID では古い Google プラットフォーム ライブラリを使用できます。デフォルトでは、新しく作成されたクライアント ID はプラットフォーム ライブラリを使用できないため、代わりに新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。識別しやすいように、プロダクト名やプラグイン名など、わかりやすい名前を使用することをおすすめします。例: plugin_name: 'YOUR_STRING_HERE' |
エネルギー効率比率(EER)
GoogleAuth
は、ユーザーが Google アカウントでログインするメソッド、ユーザーの現在のログイン ステータスを取得するメソッド、ユーザーの Google プロフィールからの特定のデータを取得するメソッド、追加のスコープのリクエスト、現在のアカウントからのログアウトを可能にするメソッドを提供するシングルトン クラスです。
gapi.auth2.getAuthInstance()
GoogleAuth
オブジェクトを返します。このメソッドを呼び出す前に、GoogleAuth
オブジェクトを gapi.auth2.init()
で初期化する必要があります。
戻り値 | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth オブジェクト。このオブジェクトを使用して、gapi.auth2.GoogleAuth のメソッドを呼び出します。
|
GoogleAuth.isSignedIn.get()
現在のユーザーがログインしているかどうかを返します。
戻り値 | |
---|---|
ブール値 |
true (ユーザーがログインしている場合)、または false (ユーザーがログアウトしている場合、または GoogleAuth オブジェクトが初期化されていない場合)。 |
GoogleAuth.isSignedIn.listen(listener)
現在のユーザーのログイン状態の変化をリッスンします。
引数 | |
---|---|
listener |
ブール値を受け取る関数。listen() は、ユーザーがログインしたときに true をこの関数に渡し、ユーザーがログアウトしたときに false を渡します。
|
GoogleAuth.signIn()
gapi.auth2.init()
に指定されたオプションでユーザーのログインを行います。
戻り値 | |
---|---|
Promise | Promise 。ユーザーが認証に成功し、リクエストされたスコープを付与すると、GoogleUser インスタンスでフルフィルメントされます。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(エラーコードについては後述)。 |
エラーコード
GoogleAuth.signIn(options)
をご確認ください。
GoogleAuth.signIn(options)
指定されたオプションを使用してユーザーをログインさせます。
引数 | |
---|---|
options |
以下のいずれか:
|
戻り値 | |
---|---|
Promise | Promise 。ユーザーが認証に成功し、リクエストされたスコープを付与すると、GoogleUser インスタンスでフルフィルメントされます。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(エラーコードについては後述)。 |
エラーコード
popup_closed_by_user
- ユーザーがログインフローを完了する前にポップアップを閉じました。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローでプロンプトが表示されなければ、ユーザーを自動的に選択することはできませんでした。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生します。gapi.auth2.init
で以前のセッションにログインしていたユーザーは自動的にログインするため、このオプションの使用は必須ではありません。
gapi.auth2.SignInOptions
GoogleAuth.signIn(options)
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
prompt |
string |
同意フローで特定のモードを強制的に適用します。省略可。 有効な値は次のとおりです。
|
scope |
string |
gapi.auth2.init パラメータで定義されたスコープに加えて、リクエストするスコープ(スペース区切りの文字列)。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
ux_mode |
string |
ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popup と redirect です。 |
redirect_uri |
string |
ux_mode='redirect' を使用している場合、このパラメータを使用すると、同意フローの最後で使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、クエリ パラメータとハッシュ フラグメントが削除された現在の URL です。 |
GoogleAuth.signOut()
現在のアカウントをアプリケーションからログアウトします。
戻り値 | |
---|---|
Promise | ユーザーがログアウトしたときに実行される Promise 。 |
GoogleAuth.disconnect()
ユーザーが許可したすべてのスコープを取り消します。
GoogleAuth.grantOfflineAccess(options)
指定されたスコープにオフラインでアクセスする権限をユーザーから取得します。
引数 | |
---|---|
options |
パラメータの Key-Value ペアを含む gapi.auth2.OfflineAccessOptions オブジェクト。次に例を示します。 { scope: 'profile email' } |
戻り値 | |
---|---|
Promise | リクエストされたスコープをユーザーが付与し、認証コードを含むオブジェクトを Promise のフルフィルメント ハンドラに渡すときに実行される Promise 。次に例を示します。 auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; }); |
エラーコード
popup_closed_by_user
- ユーザーが同意フローを完了する前にポップアップを閉じました。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローでプロンプトが表示されなければ、ユーザーを自動的に選択することはできませんでした。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生します。gapi.auth2.init
で以前のセッションにログインしていたユーザーは自動的にログインするため、このオプションの使用は必須ではありません。
gapi.auth2.OfflineAccessOptions
GoogleAuth.grantOfflineAccess(options)
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
prompt |
string |
同意フローで特定のモードを強制的に適用します。省略可。 有効な値は次のとおりです。
|
scope |
string |
gapi.auth2.init パラメータで定義されたスコープに加えて、リクエストするスコープ(スペース区切りの文字列)。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
指定されたコンテナのクリック ハンドラにログインフローをアタッチします。
引数 | |
---|---|
container | クリック ハンドラをアタッチする div 要素の ID または参照。 |
options | パラメータの Key-Value ペアを含むオブジェクト。GoogleAuth.signIn() をご覧ください。 |
onsuccess | ログインの完了後に呼び出す関数。 |
onfailure | ログインに失敗した場合に呼び出す関数。 |
ユーザー数
GoogleUser
オブジェクトは 1 つのユーザー アカウントを表します。GoogleUser
オブジェクトは通常、GoogleAuth.currentUser.get() を呼び出して取得します。
GoogleAuth.currentUser.get()
現在のユーザーを表す GoogleUser
オブジェクトを返します。新しく初期化された GoogleAuth
インスタンスでは、現在のユーザーは設定されていないことに注意してください。currentUser.listen()
メソッドまたは GoogleAuth.then()
を使用して、初期化済みの GoogleAuth
インスタンスを取得します。
戻り値 | |
---|---|
GoogleUser |
現在のユーザー |
GoogleAuth.currentUser.listen(listener)
currentUser の変更をリッスンします。
引数 | |
---|---|
listener |
GoogleUser パラメータを受け取る関数。listen は、currentUser を変更するすべての変更でこの関数を GoogleUser インスタンスに渡します。 |
GoogleUser.getId()
ユーザーの一意の ID 文字列を取得します。
戻り値 | |
---|---|
文字列 | ユーザーの一意の ID |
GoogleUser.isSignedIn()
ユーザーがログインしている場合は true を返します。
戻り値 | |
---|---|
ブール値 | ユーザーがログインしている場合は true |
GoogleUser.getHostedDomain()
ユーザーが G Suite アカウントでログインしている場合は、ユーザーの G Suite ドメインを取得します。
戻り値 | |
---|---|
文字列 | ユーザーの G Suite ドメイン |
GoogleUser.getGrantedScopes()
ユーザーがスペース区切りの文字列として付与したスコープを取得します。
戻り値 | |
---|---|
文字列 | ユーザーが付与したスコープ |
GoogleUser.getBasicProfile()
ユーザーの基本的なプロフィール情報を取得します。
戻り値 | |
---|---|
gapi.auth2.BasicProfile |
gapi.auth2.BasicProfile のプロパティは、次のメソッドで取得できます。
|
GoogleUser.getAuthResponse(includeAuthorizationData)
ユーザーの認証セッションからレスポンス オブジェクトを取得します。
引数 | |
---|---|
includeAuthorizationData | 省略可: 常にアクセス トークンとスコープを返すかどうかを指定するブール値。デフォルトでは、fetch_basic_profile が true(デフォルト値)で、追加のスコープがリクエストされていない場合、アクセス トークンとリクエストされたスコープは返されません。 |
戻り値 | |
---|---|
gapi.auth2.AuthResponse |
gapi.auth2.AuthResponse オブジェクト。
|
GoogleUser.reloadAuthResponse()
アクセス トークンを強制的に更新し、新しい AuthResponse の Promise を返します。
戻り値 | |
---|---|
Promise |
OAuth トークンの再読み込み完了時に再読み込みされた gapi.auth2.AuthResponse で処理される Promise 。 |
gapi.auth2.AuthResponse
GoogleUser.getAuthResponse(includeAuthorizationData)
メソッドまたは GoogleUser.reloadAuthResponse()
メソッドを呼び出したときに返されるレスポンス。
プロパティ | ||
---|---|---|
access_token |
string |
付与されたアクセス トークン。 |
id_token |
string |
付与された ID トークン。 |
scope |
string |
アクセス トークンで付与されるスコープ。 |
expires_in |
number |
アクセス トークンの有効期限が切れるまでの秒数。 |
first_issued_at |
number |
ユーザーがリクエストされたスコープを最初に付与した時点のタイムスタンプ。 |
expires_at |
number |
アクセス トークンが期限切れになるタイムスタンプ。 |
GoogleUser.hasGrantedScopes(scopes)
ユーザーが指定されたスコープを許可した場合、true を返します。
引数 | |
---|---|
scopes | スペースで区切られたスコープの文字列。 |
戻り値 | |
---|---|
ブール値 | スコープが付与されている場合は true |
GoogleUser.grant(options)
ユーザーに追加のスコープをリクエストします。
パラメータとエラーコードのリストについては、GoogleAuth.signIn()
をご覧ください。
GoogleUser.grantOfflineAccess(options)
指定されたスコープにオフラインでアクセスする権限をユーザーから取得します。
引数 | |
---|---|
options |
パラメータの Key-Value ペアを含む gapi.auth2.OfflineAccessOptions オブジェクト。次に例を示します。 { scope: 'profile email' } |
GoogleUser.disconnect()
ユーザーがアプリケーションに付与したすべてのスコープを取り消します。
UI 要素
gapi.signin2.render(id, options)
options オブジェクトで指定された設定を使用して、指定された ID の要素にログインボタンをレンダリングします。
引数 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | ログインボタンを表示する要素の ID。 | ||||||||||||||||
options |
ボタンのレンダリングに使用する設定を含むオブジェクト。例: { scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }次のオプションを指定できます。
|
上級者向け
gapi.auth2.authorization(params, callback)
1 回限りの OAuth 2.0 認証を実行します。これにより、使用するパラメータに応じて、Google ログインフローのポップアップが開くか、ユーザーの操作なしでリクエストされたレスポンスが自動的に読み込まれます。
この方法が役立つユースケースには、次のようなものがあります。
- アプリケーションは、Google API エンドポイントを 1 回リクエストするだけで済みます。たとえば、ユーザーが初めてログインしたときにお気に入りの YouTube 動画を読み込む場合などです。
- アプリケーションには独自のセッション管理インフラストラクチャがあり、バックエンドでユーザーを識別するために ID トークンを 1 回だけ必要とします。
- 同じページ内で複数のクライアント ID が使用されています。
引数 | |
---|---|
params |
設定データの Key-Value ペアを含むオブジェクト。構成可能な別のプロパティについては、gapi.auth2.AuthorizeConfig をご覧ください。次に例を示します。
{ client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' } |
callback |
リクエストの完了(成功または失敗)後に gapi.auth2.AuthorizeResponse オブジェクトで呼び出される関数。 |
例
gapi.auth2.authorize({
client_id: 'CLIENT_ID.apps.googleusercontent.com',
scope: 'email profile openid',
response_type: 'id_token permission'
}, function(response) {
if (response.error) {
// An error happened!
return;
}
// The user authorized the application for the scopes requested.
var accessToken = response.access_token;
var idToken = response.id_token;
// You can also now use gapi.client to perform authenticated requests.
});
エラーコード
idpiframe_initialization_failed
-
サポートされていない環境などが原因で、Google から必要な iframe を初期化できませんでした。
details
プロパティは、発生したエラーに関する詳細情報を提供します。 popup_closed_by_user
- ユーザーがログインフローを完了する前にポップアップを閉じました。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローでプロンプトが表示されなければ、ユーザーを自動的に選択することはできませんでした。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生します。
gapi.auth2.AuthorizeConfig
gapi.auth2.authorize
メソッドのさまざまな構成パラメータを表すインターフェース。
プロパティ | ||
---|---|---|
client_id |
string |
必須。Google Developers Console で取得、作成されたアプリのクライアント ID。 |
scope |
string |
必須。リクエストするスコープ。スペース区切りの文字列で指定します。 |
response_type |
string |
スペースで区切られたレスポンス タイプのリスト。デフォルトは 'permission' です。可能な値は次のとおりです。
|
prompt |
string |
同意フローで特定のモードを強制的に適用します。可能な値は次のとおりです。
|
cookie_policy |
string |
ログイン Cookie を作成するドメイン。URI、single_host_origin 、none のいずれか。指定しない場合のデフォルトは single_host_origin です。 |
hosted_domain |
string |
ユーザーがログインするために所属する G Suite ドメイン。これはクライアントによって変更される可能性があるため、返されたユーザーのホストされているドメイン プロパティを必ず確認してください。 |
login_hint |
string |
ログインフローで事前に選択するユーザーのメールアドレスまたはユーザー ID。これは、prompt: "none" を使用しない限り、ユーザーが変更する可能性があります。
|
include_granted_scopes |
boolean |
ユーザーが以前にアプリに許可したすべてのスコープを含むアクセス トークンをリクエストするか、現在の呼び出しでリクエストされたスコープのみをリクエストするかを指定します。デフォルトは true です。 |
enable_granular_consent |
boolean |
省略可。きめ細かい権限を有効にするかどうか。false に設定すると、2019 年より前に作成された OAuth クライアント ID に対して、より詳細な Google アカウントの権限が無効になります。2019 年中またはそれ以降に作成された OAuth クライアント ID には、よりきめ細かい権限が常に有効になるため、影響はありません。 |
plugin_name |
string |
省略可。設定すると、2022 年 7 月 29 日より前に作成されたクライアント ID で Google プラットフォーム ライブラリを使用できます。デフォルトでは、新しく作成されたクライアント ID はプラットフォーム ライブラリを使用できません。代わりに、新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。識別しやすいように、プロダクト名やプラグイン名など、わかりやすい名前を使用することをおすすめします。例: plugin_name: 'YOUR_STRING_HERE' |
gapi.auth2.AuthorizeResponse
gapi.auth2.authorize
メソッドのコールバックに返されたレスポンス。
プロパティ | ||
---|---|---|
access_token |
string |
付与されたアクセス トークン。response_type で permission または token が指定されている場合にのみ存在します。
|
id_token |
string |
付与された ID トークン。response_type で id_token が指定されている場合のみ存在します。
|
code |
string |
付与された認可コード。response_type で code が指定されている場合のみ存在します。
|
scope |
string |
アクセス トークンで付与されるスコープ。response_type で permission または token が指定されている場合にのみ存在します。
|
expires_in |
number |
アクセス トークンの有効期限が切れるまでの秒数。response_type で permission または token が指定されている場合のみ存在します。
|
first_issued_at |
number |
ユーザーがリクエストされたスコープを最初に付与した時点のタイムスタンプ。response_type で permission または token が指定されている場合にのみ存在します。
|
expires_at |
number |
アクセス トークンが期限切れになるタイムスタンプ。response_type で permission または token が指定されている場合のみ存在します。
|
error |
string |
リクエストが失敗した場合、エラーコードが記録されます。 |
error_subtype |
string |
リクエストが失敗した場合、返されるエラーコードの追加情報が含まれる場合があります。 |