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

このリファレンスでは、ウェブ アプリケーションに Google ログインを実装するために使用する JavaScript クライアントのメソッドと属性について説明します。

このライブラリの使用時に問題が発生した場合は、GitHub リポジトリに報告してください。

Auth の設定

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(onInitonError

GoogleAuth オブジェクトが完全に初期化されたときに onInit 関数を呼び出します。初期化中にエラーが発生した場合(サポートされていない古いブラウザで起こる可能性があります)、代わりに onError 関数が呼び出されます。

引数
onInit 完全に初期化されたときに GoogleAuth オブジェクトで呼び出される関数。
onError GoogleAuth の初期化に失敗した場合に、error プロパティを含むオブジェクトで呼び出される関数。
戻り値
Promise onInit 関数が完了すると実行され、初期化エラーが発生した場合は拒否される PromiseonInit 関数から返された値があればそれで解決されます。

エラーコード

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

gapi.auth2.ClientConfig

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

パラメータ
client_id string 必須: アプリのクライアント ID。Google Developers Console で見つけて作成されます。
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 プラットフォーム ライブラリを使用できます。 デフォルトでは、新しく作成されたクライアント ID でプラットフォーム ライブラリを使用できないため、代わりに新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。識別しやすいように、プロダクト名やプラグイン名などのわかりやすい名前をおすすめします。例: plugin_name: 'YOUR_STRING_HERE'

認証

GoogleAuth は、ユーザーが Google アカウントでログインするメソッド、ユーザーの現在のログイン ステータスを取得するメソッド、ユーザーの Google プロフィールからの特定のデータを取得するメソッド、追加のスコープのリクエスト、現在のアカウントからのログアウトを行うためのメソッドを提供するシングルトン クラスです。

gapi.auth2.getAuthInstance()

GoogleAuth オブジェクトを返します。このメソッドを呼び出す前に、gapi.auth2.init()GoogleAuth オブジェクトを初期化する必要があります。

戻り値
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
同意フローを表示しない限り、ユーザーが自動的に選択されませんでした。prompt: 'none' オプションを指定して signIn を使用するとエラーが発生します。このオプションを使用する必要はありません。以前のセッションで以前にログインしていた場合、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
同意フローを表示しない限り、ユーザーが自動的に選択されませんでした。prompt: 'none' オプションを指定して signIn を使用するとエラーが発生します。このオプションを使用する必要はありません。以前のセッションで以前にログインしていた場合、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 文字列を取得します。

戻り値
文字列 ユーザーの一意の ID

GoogleUser.isSignedIn()

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

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

GoogleUser.getHostedDomain()

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

戻り値
文字列 ユーザーの G Suite ドメイン

GoogleUser.getGrantedScopes()

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

戻り値
文字列 ユーザーが付与したスコープ

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)。
height ピクセル単位のボタンの高さ(デフォルト: 36)。
長いタイトル 「ログイン」ではなく「Google でログイン」などの長いラベルを表示します(デフォルト: false)。長いタイトルを使用する場合は、ボタンの幅をデフォルトから大きくする必要があります。
テーマ ボタンのカラーテーマ: light または dark(デフォルト: light)。
onsuccess ユーザーが正常にログインしたときに呼び出されるコールバック関数。 この関数は 1 つの引数、gapi.auth2.GoogleUser のインスタンスを取る必要があります(デフォルト: なし)。
障害発生時 ログインが失敗したときに呼び出すコールバック関数。この関数は引数を取りません(デフォルト: なし)。

上級

gapi.auth2.authorization(params, callback)

1 回限りの OAuth 2.0 認証を実行します。これにより、使用するパラメータに応じて、Google ログインフローのポップアップが開くか、ユーザーの操作なしで、リクエストされたレスポンスを通知せずに読み込みを試みます。

この方法が役立つユースケースは次のとおりです。

  • たとえば、ユーザーが初めてログインしたときにお気に入りの YouTube 動画を読み込む場合など、アプリケーションは Google API エンドポイントを 1 回だけリクエストする必要があります。
  • アプリケーションには独自のセッション管理インフラストラクチャがあり、バックエンドでユーザーを識別するために 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 必須。アプリのクライアント ID。Google Developers Console で見つけて作成されます。
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 リクエストが失敗した場合、返されるエラーコードの追加情報が含まれる可能性があります。