مرجع سرویس گیرنده جاوا اسکریپت Google Sign-In

این مرجع روش‌ها و ویژگی‌های کلاینت جاوا اسکریپت را که برای پیاده‌سازی Google Sign-In در برنامه‌های کاربردی وب خود استفاده خواهید کرد، توضیح می‌دهد.

اگر در استفاده از کتابخانه با مشکلی مواجه شدید، آن را به مخزن GitHub ما گزارش دهید. .

Auth Setup

برای ایجاد شی gapi ، کتابخانه پلتفرم Google APIs را بارگیری کنید:

<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 خود و هر گزینه دیگری که می خواهید مشخص کنید پیکربندی می کنید. سپس، اگر کاربر قبلاً وارد سیستم شده باشد، شی GoogleAuth وضعیت ورود به سیستم کاربر را از جلسه قبل بازیابی می‌کند.

استدلال ها
params یک شی حاوی جفت های کلید-مقدار از داده های پیکربندی مشتری. برای خصوصیات مختلف قابل تنظیم به gapi.auth2.ClientConfig مراجعه کنید. به عنوان مثال:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
برمی گرداند
gapi.auth2.GoogleAuth شی gapi.auth2.GoogleAuth . از متد then() برای دریافت یک Promise استفاده کنید که با اتمام مقداردهی اولیه شی gapi.auth2.GoogleAuth حل می شود.

GoogleAuth.then ( onInit ، onError )

هنگامی که شی GoogleAuth به طور کامل مقداردهی اولیه شود، تابع onInit را فراخوانی می کند. اگر هنگام تنظیم اولیه خطایی ایجاد شود (این ممکن است در مرورگرهای قدیمی پشتیبانی نشده اتفاق بیفتد)، به جای آن تابع onError فراخوانی می شود.

استدلال ها
onInit تابع هنگامی که به طور کامل مقداردهی اولیه شد با شی GoogleAuth فراخوانی می شود.
onError اگر GoogleAuth در مقداردهی اولیه ناموفق بود، تابع با یک شی حاوی یک ویژگی error فراخوانی شد.
برمی گرداند
قول بده Promise ای که با تکمیل تابع onInit محقق می شود، یا در صورت بروز خطای اولیه رد می شود. در صورت وجود، با مقدار برگشتی از تابع onInit حل می شود.

کدهای خطا

idpiframe_initialization_failed
به عنوان مثال، به دلیل یک محیط پشتیبانی نشده، یک iframe مورد نیاز از Google تنظیم اولیه نشد. ویژگی details اطلاعات بیشتری در مورد خطای مطرح شده ارائه می دهد.

gapi.auth2.ClientConfig

رابطی که پارامترهای پیکربندی مختلف را برای روش gapi.auth2.init نشان می دهد.

پارامترها
client_id string مورد نیاز. شناسه سرویس گیرنده برنامه که در Google API Console پیدا و ایجاد شده است.
cookie_policy string دامنه‌هایی که کوکی‌های ورود به سیستم برای آن‌ها ایجاد می‌شود. URI، single_host_origin ، یا none . در صورت نامشخص بودن به صورت پیش‌فرض به single_host_origin می‌رسد.
scope string محدوده های درخواستی، به عنوان رشته ای با فاصله محدود. اگر fetch_basic_profile روی false تنظیم نشده باشد، اختیاری است.
fetch_basic_profile boolean اطلاعات اولیه نمایه کاربران را هنگام ورود به سیستم واکشی کنید. "نمایه"، "ایمیل" و "openid" را به محدوده های درخواستی اضافه می کند. اگر مشخص نباشد درست است.
hosted_domain string دامنه G Suite که کاربران باید به آن تعلق داشته باشند تا به سیستم وارد شوند. این دامنه در معرض تغییر توسط مشتریان است، بنابراین حتماً ویژگی دامنه میزبانی کاربر بازگشتی را تأیید کنید. از GoogleUser.getHostedDomain() روی مشتری استفاده کنید و ادعای hd در شناسه شناسه روی سرور برای تأیید دامنه همان چیزی است که انتظار داشتید.
use_fedcm boolean اختیاری، پیش‌فرض روی True است. استفاده از APIهای FedCM مرورگر را هنگام ورود به سیستم فعال یا غیرفعال کنید.
ux_mode string حالت UX برای استفاده برای جریان ورود به سیستم. به طور پیش فرض، جریان رضایت را در یک پنجره باز می کند. مقادیر معتبر popup و redirect هستند.
redirect_uri string اگر از ux_mode='redirect' استفاده می‌کنید، این پارامتر به شما امکان می‌دهد redirect_uri پیش‌فرض را که در پایان جریان رضایت استفاده می‌شود، لغو کنید. redirect_uri پیش‌فرض URL فعلی بدون پارامترهای پرس و جو و قطعه هش است.
enable_granular_consent boolean اختیاری. آیا برای فعال کردن مجوزهای granular . اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شوند. برای شناسه‌های مشتری OAuth ایجاد شده در طول یا بعد از سال 2019 هیچ تأثیری وجود ندارد، زیرا مجوزهای دقیق‌تر همیشه برای آنها فعال است.
plugin_name string اختیاری. اگر این مقدار تنظیم شود، شناسه‌های مشتری جدید ایجاد شده قبل از ۲۹ ژوئیه ۲۰۲۲ می‌توانند از کتابخانه قدیمی Google Platform استفاده کنند. به‌طور پیش‌فرض، شناسه‌های مشتری جدید ایجاد شده اکنون برای استفاده از کتابخانه پلتفرم مسدود شده‌اند و در عوض باید از کتابخانه سرویس‌های هویت Google جدیدتر استفاده کنند. شما می توانید هر مقداری را انتخاب کنید، یک نام توصیفی مانند نام محصول یا افزونه برای شناسایی توصیه می شود. مثال: plugin_name: 'YOUR_STRING_HERE'

احراز هویت

GoogleAuth یک کلاس singleton است که روش هایی را ارائه می دهد که به کاربر اجازه می دهد با یک حساب Google وارد سیستم شود، وضعیت ورود به سیستم فعلی کاربر را دریافت کند، داده های خاصی را از نمایه Google کاربر دریافت کند، دامنه های اضافی درخواست کند و از حساب فعلی خارج شود.

gapi.auth2.getAuthInstance()

شی GoogleAuth را برمی‌گرداند. قبل از فراخوانی این متد باید شی GoogleAuth با gapi.auth2.init() مقداردهی اولیه کنید.

برمی گرداند
gapi.auth2.GoogleAuth شی gapi.auth2.GoogleAuth . از این شی برای فراخوانی متدهای gapi.auth2.GoogleAuth استفاده کنید.

GoogleAuth.isSignedIn.get()

نشان می دهد که آیا کاربر فعلی وارد سیستم شده است یا خیر.

برمی گرداند
بولی true اگر کاربر وارد سیستم شده باشد، یا اگر کاربر از سیستم خارج شده باشد یا شی GoogleAuth اولیه نشده باشد، false .

GoogleAuth.isSignedIn.listen(شنونده)

به تغییرات در وضعیت ورود به سیستم کاربر فعلی گوش دهید.

استدلال ها
listener تابعی که یک مقدار بولی می گیرد. listen() هنگام ورود کاربر به این تابع true و هنگامی که کاربر از سیستم خارج می شود false می دهد.

GoogleAuth.signIn()

کاربر را با گزینه های مشخص شده در gapi.auth2.init() وارد می کند.

برمی گرداند
قول بده Promise که با نمونه GoogleUser زمانی که کاربر با موفقیت احراز هویت می‌کند و دامنه‌های درخواستی را اعطا می‌کند، اجرا می‌شود، یا در صورت وقوع خطا، با یک شی حاوی ویژگی error رد می‌شود. برای کدهای خطا به بخش بعدی مراجعه کنید.

کدهای خطا

به GoogleAuth.signIn(options) مراجعه کنید.

GoogleAuth.signIn ( options )

با استفاده از گزینه های مشخص شده کاربر را وارد می کند.

استدلال ها
options یا:
  • یک شی 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 زمانی که کاربر با موفقیت احراز هویت و اعطای محدوده‌های درخواستی را انجام می‌دهد، انجام می‌شود، یا در صورت وقوع خطا، با یک شی حاوی ویژگی error رد می‌شود (برای کدهای خطا به زیر مراجعه کنید).

کدهای خطا

popup_closed_by_user
کاربر قبل از پایان ورود به سیستم، پنجره بازشو را بست.
access_denied
کاربر اجازه دسترسی به محدوده های مورد نیاز را رد کرد.
immediate_failed
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: '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 برای استفاده برای جریان ورود به سیستم. به طور پیش فرض، جریان رضایت را در یک پنجره باز می کند. مقادیر معتبر popup و redirect هستند.
redirect_uri string اگر از ux_mode='redirect' استفاده می‌کنید، این پارامتر به شما امکان می‌دهد redirect_uri پیش‌فرض را که در پایان جریان رضایت استفاده می‌شود، لغو کنید. redirect_uri پیش‌فرض URL فعلی بدون پارامترهای پرس و جو و قطعه هش است.

GoogleAuth.signOut()

حساب جاری را از برنامه خارج می کند.

برمی گرداند
قول بده Promise که با خروج کاربر محقق می شود.

GoogleAuth.disconnect()

همه حوزه هایی را که کاربر اعطا کرده است باطل می کند.

GoogleAuth.grantOfflineAccess ( options )

برای دسترسی آفلاین به محدوده های مشخص شده از کاربر اجازه دریافت کنید.

استدلال ها
options یک شی gapi.auth2.OfflineAccessOptions حاوی جفت پارامترهای کلید-مقدار. به عنوان مثال:
{
  scope: 'profile email'
}
برمی گرداند
قول بده Promise که زمانی محقق می‌شود که کاربر محدوده‌های درخواستی را اعطا می‌کند و یک شی حاوی کد مجوز را به کنترل‌کننده تحقق Promise ارسال می‌کند. به عنوان مثال:
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

کدهای خطا

popup_closed_by_user
کاربر قبل از اتمام جریان رضایت، پنجره بازشو را بست.
access_denied
کاربر اجازه دسترسی به محدوده های مورد نیاز را رد کرد.
immediate_failed
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: '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 که کنترل کننده کلیک را به آن متصل کنید.
options یک شی حاوی جفت پارامترهای کلید-مقدار. به GoogleAuth.signIn() مراجعه کنید.
onsuccess عملکرد فراخوانی پس از تکمیل ورود به سیستم.
onfailure تابعی برای فراخوانی در صورت عدم موفقیت در ورود به سیستم.

کاربران

یک شی GoogleUser نشان دهنده یک حساب کاربری است. اشیاء GoogleUser معمولاً با فراخوانی ()GoogleAuth.currentUser.get به دست می‌آیند.

GoogleAuth.currentUser.get()

یک شی GoogleUser را برمی‌گرداند که نشان‌دهنده کاربر فعلی است. توجه داشته باشید که در یک نمونه GoogleAuth که به تازگی راه اندازی شده است، کاربر فعلی تنظیم نشده است. از متد currentUser.listen() یا GoogleAuth.then() برای دریافت نمونه اولیه GoogleAuth استفاده کنید.

برمی گرداند
GoogleUser کاربر فعلی

GoogleAuth.currentUser.listen ( listener )

به تغییرات در currentUser گوش دهید.

استدلال ها
listener تابعی که پارامتر GoogleUser را می گیرد. listen این تابع را به عنوان نمونه GoogleUser در هر تغییری که currentUser تغییر می دهد، ارسال می کند.

GoogleUser.getId()

رشته شناسه منحصر به فرد کاربر را دریافت کنید.

برمی گرداند
رشته شناسه منحصر به فرد کاربر

GoogleUser.isSignedIn()

اگر کاربر وارد سیستم شده باشد، 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 (شاملAuthorizationData)

شی پاسخ را از جلسه تأیید کاربر دریافت کنید.

استدلال ها
includeAuthorizationData اختیاری: یک بولی که مشخص می‌کند آیا همیشه یک نشانه دسترسی و دامنه‌ها برگردانده شود یا خیر. به‌طور پیش‌فرض، زمانی که fetch_basic_profile true باشد (مقدار پیش‌فرض) نشانه دسترسی و دامنه‌های درخواستی بازگردانده نمی‌شوند و هیچ محدوده اضافی درخواست نمی‌شود.
برمی گرداند
gapi.auth2.AuthResponse یک شی gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse()

به روزرسانی نشانه دسترسی را مجبور می کند و سپس یک Promise برای AuthResponse جدید برمی گرداند.

برمی گرداند
Promise Promise ای که با بارگذاری مجدد gapi.auth2.AuthResponse هنگام بارگیری مجدد توکن OAuth انجام می شود.

gapi.auth2.AuthResponse

هنگام فراخوانی روش‌های GoogleUser.getAuthResponse( includeAuthorizationData ) یا GoogleUser.reloadAuthResponse() پاسخ داده می‌شود.

خواص
access_token string توکن دسترسی داده شد.
id_token string شناسه توکن اعطا شد.
scope string دامنه های اعطا شده در رمز دسترسی.
expires_in number تعداد ثانیه تا پایان یافتن رمز دسترسی.
first_issued_at number مهر زمانی که کاربر برای اولین بار دامنه های درخواستی را اعطا کرد.
expires_at number مهر زمانی که در آن رمز دسترسی منقضی می شود.

GoogleUser.hasGrantedScopes ( scopes )

در صورتی که کاربر محدوده های مشخص شده را اعطا کرده باشد، true برمی گرداند.

استدلال ها
scopes رشته ای از محدوده های محدود شده با فضا.
برمی گرداند
بولی درست است اگر دامنه اعطا شود

GoogleUser.grant ( options )

دامنه های اضافی را از کاربر درخواست کنید.

برای لیست پارامترها و کد خطا به GoogleAuth.signIn() مراجعه کنید.

GoogleUser.grantOfflineAccess ( options )

برای دسترسی آفلاین به محدوده های مشخص شده از کاربر اجازه دریافت کنید.

استدلال ها
options یک شی gapi.auth2.OfflineAccessOptions حاوی جفت پارامترهای کلید-مقدار. به عنوان مثال:
{
  scope: 'profile email'
}

GoogleUser.disconnect()

همه حوزه هایی را که کاربر برای برنامه اعطا کرده است لغو می کند.

عناصر رابط کاربری

gapi.signin2.render( id ، options )

با استفاده از تنظیمات مشخص شده توسط شی options ، یک دکمه ورود به سیستم را در عنصر با شناسه داده شده ارائه می دهد.

استدلال ها
id شناسه عنصری که در آن دکمه ورود به سیستم ارائه می شود.
options یک شی حاوی تنظیماتی برای استفاده برای رندر کردن دکمه. به عنوان مثال:
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
می توانید گزینه های زیر را مشخص کنید:
پارامترها
دامنه دامنه درخواست هنگام ورود کاربر (پیش‌فرض: profile ).
عرض عرض دکمه بر حسب پیکسل (پیش‌فرض: 120 ).
ارتفاع ارتفاع دکمه بر حسب پیکسل (پیش‌فرض: 36 ).
عنوان طولانی برچسب‌های طولانی مانند «ورود با Google» به جای «ورود به سیستم» (پیش‌فرض: false ) را نمایش دهید. هنگامی که از عناوین طولانی استفاده می کنید، باید عرض دکمه را از پیش فرض آن افزایش دهید.
موضوع تم رنگی دکمه: light یا dark (پیش‌فرض: light ).
بر موفقیت تابع فراخوانی برای تماس زمانی که کاربر با موفقیت وارد سیستم می شود. این تابع باید یک آرگومان داشته باشد: نمونه ای از gapi.auth2.GoogleUser (پیش فرض: هیچ).
شکست عملکرد پاسخ به تماس برای تماس زمانی که ورود ناموفق است. این تابع هیچ آرگومان نمی گیرد (پیش فرض: هیچ).

پیشرفته

gapi.auth2.authorize ( params ، callback )

مجوز یک بار OAuth 2.0 را انجام می دهد. بسته به پارامترهای مورد استفاده، این یک پنجره بازشو به جریان ورود به سیستم Google باز می‌کند یا سعی می‌کند پاسخ درخواستی را بی‌صدا و بدون تعامل کاربر بارگیری کند.

برخی از موارد استفاده که این روش مفید است عبارتند از:

  • برنامه شما فقط یک بار باید یک نقطه پایانی Google API را درخواست کند، برای مثال برای بارگیری ویدیوهای YouTube مورد علاقه کاربر در اولین باری که وارد سیستم می‌شود.
  • برنامه شما زیرساخت مدیریت جلسه خود را دارد و فقط یک بار به شناسه Token نیاز دارد تا کاربر در باطن شما را شناسایی کند.
  • چندین شناسه مشتری در همان صفحه استفاده می شود.
استدلال ها
params یک شی حاوی جفت های کلید-مقدار از داده های پیکربندی. برای خصوصیات مختلف قابل تنظیم به 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
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: 'none' خطایی ایجاد شد.

gapi.auth2.AuthorizeConfig

رابطی که پارامترهای پیکربندی مختلف را برای متد gapi.auth2.authorize نشان می دهد.

خواص
client_id string مورد نیاز . شناسه سرویس گیرنده برنامه که در Google API Console پیدا و ایجاد شده است.
scope string مورد نیاز . محدوده های درخواستی، به عنوان رشته ای با فاصله محدود.
response_type string فهرستی از نوع پاسخ با فاصله محدود. پیش‌فرض 'permission' است. مقادیر ممکن عبارتند از:
  • id_token ، برای بازیابی یک شناسه توکن
  • permission (یا token )، برای بازیابی یک نشانه دسترسی
  • code ، برای بازیابی کد مجوز
prompt string حالت خاصی را برای جریان رضایت اجباری می کند. مقادیر ممکن عبارتند از:
  • consent
    سرور مجوز قبل از بازگرداندن اطلاعات به برنامه، از کاربر درخواست می‌کند که رضایت دهد.
  • select_account
    سرور مجوز از کاربر می خواهد که یک حساب Google را انتخاب کند. این به کاربری که چندین حساب دارد اجازه می‌دهد تا از میان چندین حسابی که ممکن است جلسات فعلی برای آنها داشته باشد، انتخاب کند.
  • none
    سرور مجوز هیچ صفحه تأیید اعتبار یا رضایت کاربر را نمایش نمی دهد. اگر کاربر قبلاً احراز هویت نشده باشد و قبلاً به محدوده های درخواستی رضایت نداده باشد، خطا را برمی گرداند.
    اگر code به‌عنوان نوع پاسخ درخواست شود، کد بازگردانده شده فقط با یک access_token قابل مبادله خواهد بود، نه یک refresh_token .
cookie_policy string دامنه‌هایی که کوکی‌های ورود به سیستم برای آن‌ها ایجاد می‌شود. URI، single_host_origin ، یا none . در صورت نامشخص بودن به صورت پیش‌فرض به single_host_origin می‌رسد.
hosted_domain string دامنه G Suite که کاربران باید به آن تعلق داشته باشند تا به سیستم وارد شوند. این دامنه در معرض تغییر توسط مشتریان است، بنابراین حتماً ویژگی دامنه میزبانی کاربر بازگشتی را تأیید کنید.
login_hint string ایمیل یا شناسه کاربری یک کاربر برای انتخاب از قبل در جریان ورود به سیستم. این مورد مستعد تغییر توسط کاربر است، مگر اینکه prompt: "none" استفاده شود.
include_granted_scopes boolean آیا باید یک رمز دسترسی درخواست کرد که شامل تمام دامنه‌هایی باشد که قبلاً توسط کاربر به برنامه اعطا شده است یا فقط دامنه‌های درخواست شده در تماس فعلی. پیش فرض ها به true
enable_granular_consent boolean اختیاری. آیا برای فعال کردن مجوزهای granular . اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شوند. برای شناسه‌های مشتری OAuth ایجاد شده در طول یا بعد از سال 2019 هیچ تأثیری وجود ندارد، زیرا مجوزهای دقیق‌تر همیشه برای آنها فعال است.
plugin_name string اختیاری. در صورت تنظیم، شناسه‌های مشتری ایجاد شده قبل از ۲۹ ژوئیه ۲۰۲۲ می‌توانند از کتابخانه Google Platform استفاده کنند. به‌طور پیش‌فرض، شناسه‌های مشتری جدید ایجاد شده برای استفاده از کتابخانه پلتفرم مسدود شده‌اند و در عوض باید از کتابخانه سرویس‌های هویت Google جدیدتر استفاده کنند. شما می توانید هر مقداری را انتخاب کنید، یک نام توصیفی مانند نام محصول یا افزونه برای شناسایی آسان توصیه می شود. مثال: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

پاسخ به فراخوانی متد gapi.auth2.authorize بازگشت.

خواص
access_token string توکن دسترسی داده شد. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
id_token string شناسه توکن اعطا شد. فقط در صورتی وجود دارد که id_token در response_type مشخص شده باشد.
code string کد مجوز اعطا شد. فقط در صورتی ارائه می شود که code در response_type مشخص شده باشد.
scope string دامنه های اعطا شده در رمز دسترسی. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
expires_in number تعداد ثانیه تا پایان یافتن رمز دسترسی. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
first_issued_at number مهر زمانی که کاربر برای اولین بار دامنه های درخواستی را اعطا کرد. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
expires_at number مهر زمانی که در آن رمز دسترسی منقضی می شود. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
error string وقتی درخواست ناموفق بود، این شامل کد خطا است.
error_subtype string هنگامی که درخواست با شکست مواجه شد، این می تواند حاوی اطلاعات اضافی به کد خطا نیز باشد.
،

این مرجع روش‌ها و ویژگی‌های کلاینت جاوا اسکریپت را که برای پیاده‌سازی Google Sign-In در برنامه‌های کاربردی وب خود استفاده خواهید کرد، توضیح می‌دهد.

اگر در استفاده از کتابخانه با مشکلی مواجه شدید، آن را به مخزن GitHub ما گزارش دهید. .

Auth Setup

برای ایجاد شی gapi ، کتابخانه پلتفرم Google APIs را بارگیری کنید:

<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 خود و هر گزینه دیگری که می خواهید مشخص کنید پیکربندی می کنید. سپس، اگر کاربر قبلاً وارد سیستم شده باشد، شی GoogleAuth وضعیت ورود به سیستم کاربر را از جلسه قبل بازیابی می‌کند.

استدلال ها
params یک شی حاوی جفت های کلید-مقدار از داده های پیکربندی مشتری. برای خصوصیات مختلف قابل تنظیم به gapi.auth2.ClientConfig مراجعه کنید. به عنوان مثال:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
برمی گرداند
gapi.auth2.GoogleAuth شی gapi.auth2.GoogleAuth . از متد then() برای دریافت یک Promise استفاده کنید که با اتمام مقداردهی اولیه شی gapi.auth2.GoogleAuth حل می شود.

GoogleAuth.then ( onInit ، onError )

هنگامی که شی GoogleAuth به طور کامل مقداردهی اولیه شود، تابع onInit را فراخوانی می کند. اگر هنگام تنظیم اولیه خطایی ایجاد شود (این ممکن است در مرورگرهای قدیمی پشتیبانی نشده اتفاق بیفتد)، به جای آن تابع onError فراخوانی می شود.

استدلال ها
onInit تابع هنگامی که به طور کامل مقداردهی اولیه شد با شی GoogleAuth فراخوانی می شود.
onError اگر GoogleAuth در مقداردهی اولیه ناموفق بود، تابع با یک شی حاوی یک ویژگی error فراخوانی شد.
برمی گرداند
قول بده Promise ای که با تکمیل تابع onInit محقق می شود، یا در صورت بروز خطای اولیه رد می شود. در صورت وجود، با مقدار برگشتی از تابع onInit حل می شود.

کدهای خطا

idpiframe_initialization_failed
به عنوان مثال، به دلیل یک محیط پشتیبانی نشده، یک iframe مورد نیاز از Google تنظیم اولیه نشد. ویژگی details اطلاعات بیشتری در مورد خطای مطرح شده ارائه می دهد.

gapi.auth2.ClientConfig

رابطی که پارامترهای پیکربندی مختلف را برای روش gapi.auth2.init نشان می دهد.

پارامترها
client_id string مورد نیاز. شناسه سرویس گیرنده برنامه که در Google API Console پیدا و ایجاد شده است.
cookie_policy string دامنه‌هایی که کوکی‌های ورود به سیستم برای آن‌ها ایجاد می‌شود. URI، single_host_origin ، یا none . در صورت نامشخص بودن به صورت پیش‌فرض به single_host_origin می‌رسد.
scope string محدوده های درخواستی، به عنوان رشته ای با فاصله محدود. اگر fetch_basic_profile روی false تنظیم نشده باشد، اختیاری است.
fetch_basic_profile boolean اطلاعات اولیه نمایه کاربران را هنگام ورود به سیستم واکشی کنید. "نمایه"، "ایمیل" و "openid" را به محدوده های درخواستی اضافه می کند. اگر مشخص نباشد درست است.
hosted_domain string دامنه G Suite که کاربران باید به آن تعلق داشته باشند تا به سیستم وارد شوند. این دامنه در معرض تغییر توسط مشتریان است، بنابراین حتماً ویژگی دامنه میزبانی کاربر بازگشتی را تأیید کنید. از GoogleUser.getHostedDomain() روی مشتری استفاده کنید و ادعای hd در شناسه شناسه روی سرور برای تأیید دامنه همان چیزی است که انتظار داشتید.
use_fedcm boolean اختیاری، پیش‌فرض روی True است. استفاده از APIهای FedCM مرورگر را هنگام ورود به سیستم فعال یا غیرفعال کنید.
ux_mode string حالت UX برای استفاده برای جریان ورود به سیستم. به طور پیش فرض، جریان رضایت را در یک پنجره باز می کند. مقادیر معتبر popup و redirect هستند.
redirect_uri string اگر از ux_mode='redirect' استفاده می‌کنید، این پارامتر به شما امکان می‌دهد redirect_uri پیش‌فرض را که در پایان جریان رضایت استفاده می‌شود، لغو کنید. redirect_uri پیش‌فرض URL فعلی بدون پارامترهای پرس و جو و قطعه هش است.
enable_granular_consent boolean اختیاری. آیا برای فعال کردن مجوزهای granular . اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شوند. برای شناسه‌های مشتری OAuth ایجاد شده در طول یا بعد از سال 2019 هیچ تأثیری وجود ندارد، زیرا مجوزهای دقیق‌تر همیشه برای آنها فعال است.
plugin_name string اختیاری. اگر این مقدار تنظیم شود، شناسه‌های مشتری جدید ایجاد شده قبل از ۲۹ ژوئیه ۲۰۲۲ می‌توانند از کتابخانه قدیمی Google Platform استفاده کنند. به‌طور پیش‌فرض، شناسه‌های مشتری جدید ایجاد شده اکنون برای استفاده از کتابخانه پلتفرم مسدود شده‌اند و در عوض باید از کتابخانه سرویس‌های هویت Google جدیدتر استفاده کنند. شما می توانید هر مقداری را انتخاب کنید، یک نام توصیفی مانند نام محصول یا افزونه برای شناسایی توصیه می شود. مثال: plugin_name: 'YOUR_STRING_HERE'

احراز هویت

GoogleAuth یک کلاس singleton است که روش هایی را ارائه می دهد که به کاربر اجازه می دهد با یک حساب Google وارد سیستم شود، وضعیت ورود به سیستم فعلی کاربر را دریافت کند، داده های خاصی را از نمایه Google کاربر دریافت کند، دامنه های اضافی درخواست کند و از حساب فعلی خارج شود.

gapi.auth2.getAuthInstance()

شی GoogleAuth را برمی‌گرداند. قبل از فراخوانی این متد باید شی GoogleAuth با gapi.auth2.init() مقداردهی اولیه کنید.

برمی گرداند
gapi.auth2.GoogleAuth شی gapi.auth2.GoogleAuth . از این شی برای فراخوانی متدهای gapi.auth2.GoogleAuth استفاده کنید.

GoogleAuth.isSignedIn.get()

نشان می دهد که آیا کاربر فعلی وارد سیستم شده است یا خیر.

برمی گرداند
بولی true اگر کاربر وارد سیستم شده باشد، یا اگر کاربر از سیستم خارج شده باشد یا شی GoogleAuth اولیه نشده باشد، false .

GoogleAuth.isSignedIn.listen(شنونده)

به تغییرات در وضعیت ورود به سیستم کاربر فعلی گوش دهید.

استدلال ها
listener تابعی که یک مقدار بولی می گیرد. listen() هنگام ورود کاربر به این تابع true و هنگامی که کاربر از سیستم خارج می شود false می دهد.

GoogleAuth.signIn()

کاربر را با گزینه های مشخص شده در gapi.auth2.init() وارد می کند.

برمی گرداند
قول بده Promise که با نمونه GoogleUser زمانی که کاربر با موفقیت احراز هویت می‌کند و دامنه‌های درخواستی را اعطا می‌کند، اجرا می‌شود، یا در صورت وقوع خطا، با یک شی حاوی ویژگی error رد می‌شود. برای کدهای خطا به بخش بعدی مراجعه کنید.

کدهای خطا

به GoogleAuth.signIn(options) مراجعه کنید.

GoogleAuth.signIn ( options )

با استفاده از گزینه های مشخص شده کاربر را وارد می کند.

استدلال ها
options یا:
  • یک شی 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 زمانی که کاربر با موفقیت احراز هویت و اعطای محدوده‌های درخواستی را انجام می‌دهد، انجام می‌شود، یا در صورت وقوع خطا، با یک شی حاوی ویژگی error رد می‌شود (برای کدهای خطا به زیر مراجعه کنید).

کدهای خطا

popup_closed_by_user
کاربر قبل از پایان ورود به سیستم، پنجره بازشو را بست.
access_denied
کاربر اجازه دسترسی به محدوده های مورد نیاز را رد کرد.
immediate_failed
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: '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 برای استفاده برای جریان ورود به سیستم. به طور پیش فرض، جریان رضایت را در یک پنجره باز می کند. مقادیر معتبر popup و redirect هستند.
redirect_uri string اگر از ux_mode='redirect' استفاده می‌کنید، این پارامتر به شما امکان می‌دهد redirect_uri پیش‌فرض را که در پایان جریان رضایت استفاده می‌شود، لغو کنید. redirect_uri پیش‌فرض URL فعلی بدون پارامترهای پرس و جو و قطعه هش است.

GoogleAuth.signOut()

حساب جاری را از برنامه خارج می کند.

برمی گرداند
قول بده Promise که با خروج کاربر محقق می شود.

GoogleAuth.disconnect()

همه حوزه هایی را که کاربر اعطا کرده است باطل می کند.

GoogleAuth.grantOfflineAccess ( options )

برای دسترسی آفلاین به محدوده های مشخص شده از کاربر اجازه دریافت کنید.

استدلال ها
options یک شی gapi.auth2.OfflineAccessOptions حاوی جفت پارامترهای کلید-مقدار. به عنوان مثال:
{
  scope: 'profile email'
}
برمی گرداند
قول بده Promise که زمانی محقق می‌شود که کاربر محدوده‌های درخواستی را اعطا می‌کند و یک شی حاوی کد مجوز را به کنترل‌کننده تحقق Promise ارسال می‌کند. به عنوان مثال:
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

کدهای خطا

popup_closed_by_user
کاربر قبل از اتمام جریان رضایت، پنجره بازشو را بست.
access_denied
کاربر اجازه دسترسی به محدوده های مورد نیاز را رد کرد.
immediate_failed
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: '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 که کنترل کننده کلیک را به آن متصل کنید.
options یک شی حاوی جفت پارامترهای کلید-مقدار. به GoogleAuth.signIn() مراجعه کنید.
onsuccess عملکرد فراخوانی پس از تکمیل ورود به سیستم.
onfailure تابعی برای فراخوانی در صورت عدم موفقیت در ورود به سیستم.

کاربران

یک شی GoogleUser نشان دهنده یک حساب کاربری است. اشیاء GoogleUser معمولاً با فراخوانی ()GoogleAuth.currentUser.get به دست می‌آیند.

GoogleAuth.currentUser.get()

یک شی GoogleUser را برمی‌گرداند که نشان‌دهنده کاربر فعلی است. توجه داشته باشید که در یک نمونه GoogleAuth که به تازگی راه اندازی شده است، کاربر فعلی تنظیم نشده است. از متد currentUser.listen() یا GoogleAuth.then() برای دریافت نمونه اولیه GoogleAuth استفاده کنید.

برمی گرداند
GoogleUser کاربر فعلی

GoogleAuth.currentUser.listen ( listener )

به تغییرات در currentUser گوش دهید.

استدلال ها
listener تابعی که پارامتر GoogleUser را می گیرد. listen این تابع را به عنوان نمونه GoogleUser در هر تغییری که currentUser تغییر می دهد، ارسال می کند.

GoogleUser.getId()

رشته شناسه منحصر به فرد کاربر را دریافت کنید.

برمی گرداند
رشته شناسه منحصر به فرد کاربر

GoogleUser.isSignedIn()

اگر کاربر وارد سیستم شده باشد، 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 (شاملAuthorizationData)

شی پاسخ را از جلسه تأیید کاربر دریافت کنید.

استدلال ها
includeAuthorizationData اختیاری: یک بولی که مشخص می‌کند آیا همیشه یک نشانه دسترسی و دامنه‌ها برگردانده شود یا خیر. به‌طور پیش‌فرض، زمانی که fetch_basic_profile true باشد (مقدار پیش‌فرض) نشانه دسترسی و دامنه‌های درخواستی بازگردانده نمی‌شوند و هیچ محدوده اضافی درخواست نمی‌شود.
برمی گرداند
gapi.auth2.AuthResponse یک شی gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse()

به روزرسانی نشانه دسترسی را مجبور می کند و سپس یک Promise برای AuthResponse جدید برمی گرداند.

برمی گرداند
Promise Promise ای که با بارگذاری مجدد gapi.auth2.AuthResponse هنگام بارگیری مجدد توکن OAuth انجام می شود.

gapi.auth2.AuthResponse

هنگام فراخوانی روش‌های GoogleUser.getAuthResponse( includeAuthorizationData ) یا GoogleUser.reloadAuthResponse() پاسخ داده می‌شود.

خواص
access_token string توکن دسترسی داده شد.
id_token string شناسه توکن اعطا شد.
scope string دامنه های اعطا شده در رمز دسترسی.
expires_in number تعداد ثانیه تا پایان یافتن رمز دسترسی.
first_issued_at number مهر زمانی که کاربر برای اولین بار دامنه های درخواستی را اعطا کرد.
expires_at number مهر زمانی که در آن رمز دسترسی منقضی می شود.

GoogleUser.hasGrantedScopes ( scopes )

در صورتی که کاربر محدوده های مشخص شده را اعطا کرده باشد، true برمی گرداند.

استدلال ها
scopes رشته ای از محدوده های محدود شده با فضا.
برمی گرداند
بولی درست است اگر دامنه اعطا شود

GoogleUser.grant ( options )

دامنه های اضافی را از کاربر درخواست کنید.

برای لیست پارامترها و کد خطا به GoogleAuth.signIn() مراجعه کنید.

GoogleUser.grantOfflineAccess ( options )

برای دسترسی آفلاین به محدوده های مشخص شده از کاربر اجازه دریافت کنید.

استدلال ها
options یک شی gapi.auth2.OfflineAccessOptions حاوی جفت پارامترهای کلید-مقدار. به عنوان مثال:
{
  scope: 'profile email'
}

GoogleUser.disconnect()

همه حوزه هایی را که کاربر برای برنامه اعطا کرده است لغو می کند.

عناصر رابط کاربری

gapi.signin2.render( id ، options )

با استفاده از تنظیمات مشخص شده توسط شی options ، یک دکمه ورود به سیستم را در عنصر با شناسه داده شده ارائه می دهد.

استدلال ها
id شناسه عنصری که در آن دکمه ورود به سیستم ارائه می شود.
options یک شی حاوی تنظیماتی برای استفاده برای رندر کردن دکمه. به عنوان مثال:
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
می توانید گزینه های زیر را مشخص کنید:
پارامترها
دامنه دامنه درخواست هنگام ورود کاربر (پیش‌فرض: profile ).
عرض عرض دکمه بر حسب پیکسل (پیش‌فرض: 120 ).
ارتفاع ارتفاع دکمه بر حسب پیکسل (پیش‌فرض: 36 ).
عنوان طولانی برچسب‌های طولانی مانند «ورود با Google» به جای «ورود به سیستم» (پیش‌فرض: false ) را نمایش دهید. هنگامی که از عناوین طولانی استفاده می کنید، باید عرض دکمه را از پیش فرض آن افزایش دهید.
موضوع تم رنگی دکمه: light یا dark (پیش‌فرض: light ).
بر موفقیت تابع فراخوانی برای تماس زمانی که کاربر با موفقیت وارد سیستم می شود. این تابع باید یک آرگومان داشته باشد: نمونه ای از gapi.auth2.GoogleUser (پیش فرض: هیچ).
شکست عملکرد پاسخ به تماس برای تماس زمانی که ورود ناموفق است. این تابع هیچ آرگومان نمی گیرد (پیش فرض: هیچ).

پیشرفته

gapi.auth2.authorize ( params ، callback )

مجوز یک بار OAuth 2.0 را انجام می دهد. بسته به پارامترهای مورد استفاده، این یک پنجره بازشو به جریان ورود به سیستم Google باز می‌کند یا سعی می‌کند پاسخ درخواستی را بی‌صدا و بدون تعامل کاربر بارگیری کند.

برخی از موارد استفاده که این روش مفید است عبارتند از:

  • برنامه شما فقط یک بار باید یک نقطه پایانی Google API را درخواست کند، برای مثال برای بارگیری ویدیوهای YouTube مورد علاقه کاربر در اولین باری که وارد سیستم می‌شود.
  • برنامه شما زیرساخت مدیریت جلسه خود را دارد و فقط یک بار به شناسه Token نیاز دارد تا کاربر در باطن شما را شناسایی کند.
  • چندین شناسه مشتری در همان صفحه استفاده می شود.
استدلال ها
params یک شی حاوی جفت های کلید-مقدار از داده های پیکربندی. برای خصوصیات مختلف قابل تنظیم به 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
هیچ کاربری نمی تواند به طور خودکار بدون درخواست جریان رضایت انتخاب شود. هنگام استفاده از signIn با گزینه prompt: 'none' خطایی ایجاد شد.

gapi.auth2.AuthorizeConfig

رابطی که پارامترهای پیکربندی مختلف را برای متد gapi.auth2.authorize نشان می دهد.

خواص
client_id string مورد نیاز . شناسه سرویس گیرنده برنامه که در Google API Console پیدا و ایجاد شده است.
scope string مورد نیاز . محدوده های درخواستی، به عنوان رشته ای با فاصله محدود.
response_type string فهرستی از نوع پاسخ با فاصله محدود. پیش‌فرض 'permission' است. مقادیر ممکن عبارتند از:
  • id_token ، برای بازیابی یک شناسه توکن
  • permission (یا token )، برای بازیابی یک نشانه دسترسی
  • code ، برای بازیابی کد مجوز
prompt string حالت خاصی را برای جریان رضایت اجباری می کند. مقادیر ممکن عبارتند از:
  • consent
    سرور مجوز قبل از بازگرداندن اطلاعات به برنامه، از کاربر درخواست می‌کند که رضایت دهد.
  • select_account
    سرور مجوز از کاربر می خواهد که یک حساب Google را انتخاب کند. این به کاربری که چندین حساب دارد اجازه می‌دهد تا از میان چندین حسابی که ممکن است جلسات فعلی برای آنها داشته باشد، انتخاب کند.
  • none
    سرور مجوز هیچ صفحه تأیید اعتبار یا رضایت کاربر را نمایش نمی دهد. اگر کاربر قبلاً احراز هویت نشده باشد و قبلاً به محدوده های درخواستی رضایت نداده باشد، خطا را برمی گرداند.
    اگر code به‌عنوان نوع پاسخ درخواست شود، کد بازگردانده شده فقط با یک access_token قابل مبادله خواهد بود، نه یک refresh_token .
cookie_policy string دامنه‌هایی که کوکی‌های ورود به سیستم برای آن‌ها ایجاد می‌شود. URI، single_host_origin ، یا none . در صورت نامشخص بودن به صورت پیش‌فرض به single_host_origin می‌رسد.
hosted_domain string دامنه G Suite که کاربران باید به آن تعلق داشته باشند تا به سیستم وارد شوند. این دامنه در معرض تغییر توسط مشتریان است، بنابراین حتماً ویژگی دامنه میزبانی کاربر بازگشتی را تأیید کنید.
login_hint string ایمیل یا شناسه کاربری یک کاربر برای انتخاب از قبل در جریان ورود به سیستم. این مورد مستعد تغییر توسط کاربر است، مگر اینکه prompt: "none" استفاده شود.
include_granted_scopes boolean آیا باید یک رمز دسترسی درخواست کرد که شامل تمام دامنه‌هایی باشد که قبلاً توسط کاربر به برنامه اعطا شده است یا فقط دامنه‌های درخواست شده در تماس فعلی. پیش فرض ها به true
enable_granular_consent boolean اختیاری. آیا برای فعال کردن مجوزهای granular . اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شوند. برای شناسه‌های مشتری OAuth ایجاد شده در طول یا بعد از سال 2019 هیچ تأثیری وجود ندارد، زیرا مجوزهای دقیق‌تر همیشه برای آنها فعال است.
plugin_name string اختیاری. در صورت تنظیم، شناسه‌های مشتری ایجاد شده قبل از ۲۹ ژوئیه ۲۰۲۲ می‌توانند از کتابخانه Google Platform استفاده کنند. به‌طور پیش‌فرض، شناسه‌های مشتری جدید ایجاد شده برای استفاده از کتابخانه پلتفرم مسدود شده‌اند و در عوض باید از کتابخانه سرویس‌های هویت Google جدیدتر استفاده کنند. شما می توانید هر مقداری را انتخاب کنید، یک نام توصیفی مانند نام محصول یا افزونه برای شناسایی آسان توصیه می شود. مثال: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

پاسخ به فراخوانی متد gapi.auth2.authorize بازگشت.

خواص
access_token string توکن دسترسی داده شد. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
id_token string شناسه توکن اعطا شد. فقط در صورتی وجود دارد که id_token در response_type مشخص شده باشد.
code string کد مجوز اعطا شد. فقط در صورتی ارائه می شود که code در response_type مشخص شده باشد.
scope string دامنه های اعطا شده در رمز دسترسی. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
expires_in number تعداد ثانیه تا پایان یافتن رمز دسترسی. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
first_issued_at number مهر زمانی که کاربر برای اولین بار دامنه های درخواستی را اعطا کرد. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
expires_at number مهر زمانی که در آن رمز دسترسی منقضی می شود. فقط در صورتی وجود دارد که permission یا token در response_type مشخص شده باشد.
error string وقتی درخواست ناموفق بود، این شامل کد خطا است.
error_subtype string هنگامی که درخواست با شکست مواجه شد، این می تواند حاوی اطلاعات اضافی به کد خطا نیز باشد.