Google ログイン JavaScript クライアント リファレンス

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このリファレンスでは、ウェブ アプリケーションに 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 onInit 関数の完了時に満たされる Promise、または初期化エラーが発生した場合に拒否される PromiseonInit 関数から返された値があれば解決されます。

エラーコード

idpiframe_initialization_failed
サポートされていない環境などが原因で、必要な iframe を Google から初期化できませんでした。details プロパティは、発生したエラーに関する詳細情報を提供します。

gapi.auth2.ClientConfig

gapi.auth2.init メソッドのさまざまな構成パラメータを表すインターフェース。

パラメータ
client_id string 必須。Google Developers Console で見つけて作成されたアプリのクライアント ID。
cookie_policy string ログイン Cookie を作成するドメイン。URI、single_host_originnone のいずれか。指定しない場合のデフォルトは 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 モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popupredirect です。
redirect_uri string ux_mode='redirect' を使用する場合、このパラメータを使用すると、同意フローの最後で使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、現在の URL からクエリ パラメータとハッシュ フラグメントを削除します。
plugin_name string (省略可)この値を設定した場合、2022 年 7 月 29 日より前に作成された新しいクライアント ID では古い Google Platform ライブラリを使用できます。 新しく作成されたクライアント ID はデフォルトでプラットフォーム ライブラリの使用がブロックされるようになり、代わりに新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。簡単に識別できるように、プロダクト名やプラグイン名など、わかりやすい名前をおすすめします。 例: plugin_name: 'YOUR_STRING_HERE'

認証

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 ユーザーが認証とスコープのリクエストを許可したときに GoogleUser インスタンスで処理される Promise。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(以下のエラーコードをご覧ください)。

エラーコード

GoogleAuth.signIn(options)をご確認ください。

GoogleAuth.signIn(options)

指定されたオプションを使用してユーザーをログインさせます。

引数
options 次のいずれかを行います。
  • ログイン パラメータの Key-Value ペアを含む gapi.auth2.SignInOptions オブジェクト。例:
    {
      scope: 'profile email'
    }
  • gapi.auth2.SigninOptionsBuilder のインスタンス。例:
    options = new gapi.auth2.SigninOptionsBuilder();
    options.setAppPackageName('com.example.app');
    options.setFetchBasicProfile(True);
    options.setPrompt('select_account');
    options.setScope('profile').setScope('email');
戻り値
Promise ユーザーが認証とスコープのリクエストを許可したときに GoogleUser インスタンスで処理される Promise。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(以下のエラーコードをご覧ください)。

エラーコード

popup_closed_by_user
ユーザーは、ログインフローを完了する前にポップアップを閉じました。
access_denied
ユーザーは必要なスコープに対する権限を拒否しました。
immediate_failed
同意フローを促すメッセージが表示されない場合は、ユーザーを自動的に選択することはできません。signInprompt: 'none' オプションとともに使用すると、エラーが発生します。gapi.auth2.init は、以前のセッションで以前にログインしていた場合はユーザーを自動的にログインさせるため、このオプションの使用は必須ではありません。

gapi.auth2.SignInOptions

GoogleAuth.signIn(options) メソッドのさまざまな構成パラメータを表すインターフェース。

パラメータ
prompt string 同意フローに対して特定のモードを強制的に設定します。省略可。
有効な値は次のとおりです。
  • consent
    認証サーバーは、情報をユーザーに返す前にユーザーに同意を求めるプロンプトを表示します。
  • select_account
    承認サーバーがユーザーに Google アカウントの選択を促します。これにより、複数のアカウントを持つユーザーが、現在のセッションを担当する複数のアカウントの中から選択することができます。
  • none(非推奨
    認証サーバーは認証画面とユーザーの同意画面を表示しません。ユーザーがまだ認証されておらず、リクエストされたスコープにまだ同意していない場合は、エラーが返されます。
    以前にログインしている場合、gapi.auth2.init はユーザーをアプリケーションに自動的にログインさせるため、signIn({prompt: 'none'}) の呼び出しは通常失敗します。
scope string gapi.auth2.init パラメータで定義されたスコープの一番上に、リクエストするスコープ(スペース区切りの文字列)。fetch_basic_profile が false に設定されていない場合は省略できます。
ux_mode string ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popupredirect です。
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
同意フローを促すメッセージが表示されない場合は、ユーザーを自動的に選択することはできません。signInprompt: 'none' オプションとともに使用すると、エラーが発生します。gapi.auth2.init は、以前のセッションで以前にログインしていた場合はユーザーを自動的にログインさせるため、このオプションの使用は必須ではありません。

gapi.auth2.OfflineAccessOptions

GoogleAuth.grantOfflineAccess(options) メソッドのさまざまな構成パラメータを表すインターフェース。

パラメータ
prompt string 同意フローに対して特定のモードを強制的に設定します。省略可。
有効な値は次のとおりです。
  • consent
    認証サーバーは、情報をユーザーに返す前にユーザーに同意を求めるプロンプトを表示します。
  • select_account
    承認サーバーがユーザーに Google アカウントの選択を促します。これにより、複数のアカウントを持つユーザーが、現在のセッションを担当する複数のアカウントの中から選択することができます。
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 文字列を取得します。

戻り値
String ユーザーの一意の ID

GoogleUser.isSignedIn()

ユーザーがログインしている場合は true を返します。

戻り値
ブール値 ユーザーがログインしている場合は true

GoogleUser.getHostedDomain()

ユーザーが G Suite アカウントでログインしている場合は、ユーザーの G Suite ドメインを取得します。

戻り値
String ユーザーの G Suite ドメイン

GoogleUser.getGrantedScopes()

ユーザーがスペースで区切った文字列として付与したスコープを取得します。

戻り値
String ユーザーが付与するスコープ

GoogleUser.getBasicProfile()

ユーザーの基本的なプロフィール情報を取得します。

戻り値
gapi.auth2.BasicProfile gapi.auth2.BasicProfile のプロパティは、次のメソッドで取得できます。
  • BasicProfile.getId()
  • BasicProfile.getName() の使用
  • BasicProfile.getGivenName() である
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

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
}
次のオプションを指定できます。
パラメータ
スコープ ユーザーがログインしたときにリクエストするスコープ(デフォルト: profile)。
width ボタンの幅(ピクセル単位)(デフォルト: 120)。
高さ ボタンの高さ(ピクセル単位)(デフォルト: 36)。
長いタイトル 「ログイン」ではなく、「Google でログイン」などの長いラベルを表示します(デフォルト: false)。長いタイトルを使用する場合は、ボタンの幅をデフォルトから大きくする必要があります。
テーマ ボタンの色テーマ: light または dark(デフォルト: light)。
成功 ユーザーが正常にログインしたときに呼び出すコールバック関数。 この関数は 1 つの引数を取る必要があります。1 つは gapi.auth2.GoogleUser のインスタンスです(デフォルト: なし)。
失敗 ログインに失敗したときに呼び出すコールバック関数。この関数は引数を受け取りません(デフォルト: none)。

上級

gapi.auth2.authorized(params, callback)

OAuth 2.0 認証を 1 回だけ実行します。使用されるパラメータに応じて、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
サポートされていない環境などが原因で、必要な iframe を Google から初期化できませんでした。details プロパティは、発生したエラーに関する詳細情報を提供します。
popup_closed_by_user
ユーザーは、ログインフローを完了する前にポップアップを閉じました。
access_denied
ユーザーは必要なスコープに対する権限を拒否しました。
immediate_failed
同意フローを促すメッセージが表示されない場合は、ユーザーを自動的に選択することはできません。signInprompt: 'none' オプションとともに使用すると、エラーが発生します。

gapi.auth2.AuthorizeConfig

gapi.auth2.authorize メソッドのさまざまな構成パラメータを表すインターフェース。

プロパティ
client_id string 必須。Google Developers Console で見つけて作成されたアプリのクライアント ID。
scope string 必須。リクエストするスコープ(スペース区切りの文字列)。
response_type string スペース区切りレスポンス タイプのリスト。デフォルトは 'permission' です。使用できる値は次のとおりです。
  • id_token: ID トークンを取得する
  • permission(または token): アクセス トークンを取得します。
  • code、認証コードを取得する
prompt string 同意フローに対して特定のモードを強制的に設定します。使用できる値は次のとおりです。
  • consent
    認証サーバーは、情報をユーザーに返す前にユーザーに同意を求めるプロンプトを表示します。
  • select_account
    承認サーバーがユーザーに Google アカウントの選択を促します。これにより、複数のアカウントを持つユーザーが、現在のセッションを担当する複数のアカウントの中から選択することができます。
  • none
    認証サーバーに認証画面とユーザーの同意画面は表示されません。ユーザーがまだ認証されておらず、リクエストされたスコープにまだ同意していない場合は、エラーが返されます。
    code がレスポンス タイプとしてリクエストされた場合、返されるコードは access_token とのみ交換できます。refresh_token とは交換できません。
cookie_policy string ログイン Cookie を作成するドメイン。URI、single_host_originnone のいずれか。指定しない場合のデフォルトは single_host_origin です。
hosted_domain string ログインが必要なユーザーが属する G Suite ドメイン。これはクライアントによって変更される可能性があるため、返されたユーザーのホストされたドメイン プロパティを必ず確認してください。
login_hint string ログインフローで事前に選択するユーザーのメールアドレス(ユーザー ID)。prompt: "none" を使用しない限り、これはユーザーが変更する可能性が高くなります。
include_granted_scopes boolean ユーザーが以前にアプリに付与したすべてのスコープを含むアクセス トークンをリクエストするか、現在の呼び出しでリクエストされたスコープのみをリクエストするか。デフォルトは true です。
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_typepermission または token が指定されている場合のみ存在します。
id_token string 付与される ID トークン。response_typeid_token が指定されている場合のみ存在します。
code string 付与された認証コード。response_typecode が指定されている場合のみ存在します。
scope string アクセス トークンで付与されるスコープ。response_typepermission または token が指定されている場合のみ存在します。
expires_in number アクセス トークンが期限切れになるまでの秒数。response_typepermission または token を指定した場合のみ存在します。
first_issued_at number リクエストされたスコープをユーザーが最初に付与した時点のタイムスタンプ。response_typepermission または token を指定した場合のみ存在します。
expires_at number アクセス トークンの有効期限を示すタイムスタンプ。response_typepermission または token を指定した場合のみ存在します。
error string リクエストが失敗した場合、エラーコードが含まれます。
error_subtype string リクエストが失敗した場合、返されたエラーコードへの追加情報も返されることがあります。