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

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

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

エラーコード

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_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(containeroptionsonsuccessonfailure

指定されたコンテナのクリック ハンドラにログインフローを接続します。

引数
container クリック ハンドラを接続する div 要素の ID または参照。
options パラメータの Key-Value ペアを含むオブジェクト。GoogleAuth.signIn() をご覧ください。
onsuccess ログインの完了後に呼び出す関数。
onfailure ログインが失敗した場合に呼び出す関数。

ユーザー

GoogleUser オブジェクトは 1 つのユーザー アカウントを表します。 GoogleUser オブジェクトは通常、GoogleAuth.currentUser.get() を呼び出して取得します。

GoogleAuth.currentUser.get()

現在のユーザーを表す GoogleUser オブジェクトを返します。新しく初期化された GoogleAuth インスタンスでは、現在のユーザーが設定されていないことに注意してください。初期化された GoogleAuth インスタンスを取得するには、currentUser.listen() メソッドまたは GoogleAuth.then() を使用します。

戻り値
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(idoptions

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)。
成功 ユーザーがログインに成功したときに呼び出すコールバック関数。 この関数は、gapi.auth2.GoogleUser のインスタンスを 1 つ指定する必要があります(デフォルト: なし)。
故障 ログインが失敗した場合に呼び出すコールバック関数。この関数は引数を取らない(デフォルト: なし)。

高度

gapi.auth2.authorization(paramscallback

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

この方法が役立つユースケースには、次のようなものがあります。

  • ユーザーが Google API エンドポイントを最初にリクエストする必要があるのは、たとえばユーザーがログインしたときにお気に入りの 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' です。値は次のいずれかです。
  • id_token、ID トークンを取得する
  • permission(または token): アクセス トークンを取得する
  • code: 認証コードを取得します。
prompt string 同意フローに特定のモードを強制します。値は次のいずれかです。
  • consent
    認証サーバーは、アプリケーションに情報を返す前に同意を求めます。
  • select_account
    Google アカウントを選択します。これにより、複数のアカウントを持つユーザーが、現在のセッションを持つ複数のアカウントの中から選択できるようになります。
  • none
    認証サーバーには認証画面とユーザーの同意画面は表示されません。ユーザーがまだ認証されておらず、リクエストされたスコープにまだ同意していない場合は、エラーが返されます。
    レスポンス タイプとして code がリクエストされた場合、返されるコードは refresh_token ではなく access_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 リクエストが失敗した場合は、返されるエラーコードに関する追加情報も含まれる可能性があります。