این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با مرجع Google JavaScript API وارد شوید

این صفحه مرجع، API جاوا اسکریپت ورود به سیستم با گوگل را شرح می‌دهد که برای نمایش دکمه ورود به سیستم با گوگل یا اعلان تک‌لمسی در صفحات وب استفاده می‌شود.

روش: google.accounts.id.initialize

متد google.accounts.id.initialize کلاینت Sign In With Google را بر اساس شیء پیکربندی مقداردهی اولیه می‌کند. به مثال کد زیر از این متد توجه کنید:

google.accounts.id.initialize(IdConfiguration)

مثال کد زیر متد google.accounts.id.initialize را با یک تابع onload پیاده‌سازی می‌کند:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

متد google.accounts.id.initialize یک نمونه کلاینت از نوع Sign In With Google ایجاد می‌کند که می‌تواند به طور ضمنی توسط همه ماژول‌های موجود در یک صفحه وب مورد استفاده قرار گیرد.

حتی اگر از چندین ماژول (مانند One Tap، Personalized button، revocation و غیره) در یک صفحه وب استفاده کنید، فقط کافی است یک بار متد google.accounts.id.initialize را فراخوانی کنید.
اگر متد google.accounts.id.initialize را چندین بار فراخوانی کنید، فقط پیکربندی‌های آخرین فراخوانی به خاطر سپرده شده و استفاده می‌شوند.

در واقع هر زمان که متد google.accounts.id.initialize را فراخوانی می‌کنید، پیکربندی‌ها را مجدداً تنظیم می‌کنید و تمام متدهای بعدی در همان صفحه وب بلافاصله از پیکربندی‌های جدید استفاده می‌کنند.

نوع داده: IdConfiguration

جدول زیر فیلدها و توضیحات مربوط به نوع داده IdConfiguration را فهرست می‌کند:

میدان
`client_id`	شناسه کلاینت برنامه شما
`color_scheme`	طرح رنگی اعمال شده برای اعلان One Tap.
`auto_select`	انتخاب خودکار را فعال می‌کند.
`callback`	تابع جاوا اسکریپتی که توکن‌های شناسه را مدیریت می‌کند. حالت تجربه کاربری پاپ‌آپ دکمه `popup` با گوگل و دکمه گوگل از این ویژگی استفاده می‌کنند.
`login_uri`	URL نقطه پایانی ورود شما. حالت UX `redirect` دکمه ورود با گوگل از این ویژگی استفاده می‌کند.
`native_callback`	تابع جاوا اسکریپت که اعتبارنامه‌های رمز عبور را مدیریت می‌کند.
`cancel_on_tap_outside`	اگر کاربر خارج از محدوده‌ی اعلان کلیک کند، اعلان را لغو می‌کند.
`prompt_parent_id`	شناسه DOM مربوط به عنصر کانتینر اعلان One Tap
`nonce`	یک رشته تصادفی برای توکن‌های شناسه
`context`	عنوان و کلمات موجود در اعلان One Tap
`state_cookie_domain`	اگر نیاز به فراخوانی One Tap در دامنه والد و زیردامنه‌های آن دارید، دامنه والد را به این فیلد ارسال کنید تا از یک کوکی مشترک استفاده شود.
`ux_mode`	جریان تجربه کاربری دکمه ورود با گوگل
`allowed_parent_origin`	مبداهایی که مجاز به جاسازی iframe میانی هستند. در صورت وجود این فیلد، One Tap در حالت iframe میانی اجرا می‌شود.
`intermediate_iframe_close_callback`	وقتی کاربران به صورت دستی One Tap را می‌بندند، رفتار پیش‌فرض iframe میانی را لغو می‌کند.
`itp_support`	تجربه کاربری One Tap ارتقا یافته را در مرورگرهای ITP فعال می‌کند.
`login_hint`	با ارائه یک راهنمای کاربری، از انتخاب حساب کاربری صرف نظر کنید.
`hd`	محدود کردن انتخاب حساب کاربری بر اساس دامنه.
`use_fedcm_for_prompt`	به مرورگر اجازه دهید تا درخواست‌های ورود کاربر را کنترل کند و جریان ورود به سیستم را بین وب‌سایت شما و گوگل واسطه‌گری کند.
`use_fedcm_for_button`	این فیلد تعیین می‌کند که آیا باید از رابط کاربری دکمه FedCM در کروم (دسکتاپ M125+ و اندروید M128+) استفاده شود یا خیر. مقدار پیش‌فرض `false` است.
`button_auto_select`	آیا گزینه انتخاب خودکار برای جریان دکمه FedCM فعال شود یا خیر. در صورت فعال بودن، کاربرانی که دوباره با یک جلسه فعال گوگل وارد سیستم می‌شوند، به طور خودکار وارد سیستم می‌شوند و از مرحله انتخاب حساب کاربری عبور می‌کنند. مقدار پیش‌فرض `false` است.

شناسه_مشتری

این فیلد، شناسه کلاینت برنامه شماست که در کنسول Google Cloud یافت و ایجاد می‌شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	بله	`client_id: "CLIENT_ID.apps.googleusercontent.com"`

طرح_رنگ

این فیلد، طرح رنگی اعمال شده به اعلان One Tap است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری. به طور پیش‌فرض از طرح رنگ پیش‌فرض سیستم کاربر استفاده می‌کند.	`color_scheme: "dark"`

جدول زیر طرح‌های رنگی موجود و توضیحات آنها را فهرست می‌کند.

طرح رنگ
`default`	طرح رنگی پیش‌فرض سیستم کاربر را اعمال کنید، بسته به ترجیح کاربر، طرح رنگی می‌تواند روشن یا تیره باشد.
`light`	یک طرح رنگی روشن اعمال کنید.
`dark`	یک طرح رنگی تیره اعمال کنید.

انتخاب خودکار

این فیلد تعیین می‌کند که آیا وقتی فقط یک جلسه گوگل وجود دارد که قبلاً برنامه شما را تأیید کرده است، یک شناسه توکن به طور خودکار و بدون هیچ گونه تعامل با کاربر بازگردانده شود یا خیر. مقدار پیش‌فرض false است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
بولی	اختیاری	`auto_select: true`

تماس برگشتی

این فیلد یک تابع جاوا اسکریپت است که توکن شناسه (ID token) برگردانده شده از اعلان One Tap یا پنجره پاپ‌آپ را مدیریت می‌کند. این ویژگی در صورت استفاده از حالت تجربه کاربری popup Google One Tap یا دکمه ورود با گوگل (Sign In With Google) الزامی است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
تابع	برای حالت One Tap و حالت UX `popup` مورد نیاز است	`callback: handleResponse`

login_uri

این ویژگی، URI نقطه پایانی ورود شما است.

این مقدار باید دقیقاً با یکی از URI های ریدایرکت مجاز برای کلاینت OAuth 2.0 که در کنسول Google Cloud پیکربندی کرده‌اید ، مطابقت داشته باشد و باید با قوانین اعتبارسنجی Redirect URI ما مطابقت داشته باشد.

اگر صفحه فعلی، صفحه ورود شما باشد، ممکن است این ویژگی حذف شود، که در این صورت اعتبارنامه به طور پیش‌فرض در این صفحه ارسال می‌شود.

پاسخ اعتبارنامه توکن شناسه هنگامی که کاربر روی دکمه ورود با گوگل کلیک می‌کند و حالت UX تغییر مسیر استفاده می‌شود، به نقطه پایانی ورود شما ارسال می‌شود.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	اختیاری	مثال
آدرس اینترنتی	پیش‌فرض، آدرس اینترنتی (URI) صفحه فعلی یا مقداری است که شما مشخص می‌کنید. فقط زمانی استفاده می‌شود که `ux_mode: "redirect"` تنظیم شده باشد.	`login_uri: "https://www.example.com/login"`

نقطه پایانی ورود شما باید درخواست‌های POST حاوی پارامتر credential با مقدار توکن شناسه در بدنه را مدیریت کند.

native_callback

این فیلد نام تابع جاوا اسکریپتی است که اعتبارنامه رمز عبور برگردانده شده از مدیریت اعتبارنامه داخلی مرورگر را مدیریت می‌کند. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
تابع	اختیاری	`native_callback: handleResponse`

لغو_در_ضربه_خارج

این فیلد تعیین می‌کند که آیا در صورت کلیک کاربر خارج از محدوده‌ی اعلان، درخواست One Tap لغو شود یا خیر. مقدار پیش‌فرض true است. اگر مقدار را false تنظیم کنید، می‌توانید آن را غیرفعال کنید. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
بولی	اختیاری	`cancel_on_tap_outside: false`

prompt_parent_id

این ویژگی، شناسه DOM عنصر کانتینر را تنظیم می‌کند. اگر تنظیم نشده باشد، اعلان One Tap در گوشه بالا سمت راست پنجره نمایش داده می‌شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`prompt_parent_id: 'parent_id'`

نانس

این فیلد یک رشته تصادفی است که توسط توکن ID برای جلوگیری از حملات بازپخش استفاده می‌شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`nonce: "biaqbm70g23"`

طول Nonce به حداکثر اندازه JWT پشتیبانی شده توسط محیط شما و محدودیت‌های اندازه HTTP مرورگر و سرور محدود می‌شود.

زمینه

این فیلد متن عنوان و پیام‌های نمایش داده شده در اعلان One Tap را تغییر می‌دهد، برای مرورگرهای ITP تاثیری ندارد. پیش‌فرض روی signin است.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`context: "use"`

جدول زیر تمام زمینه‌های موجود و توضیحات آنها را فهرست می‌کند:

زمینه
`signin`	«ورود به»
`signup`	«ثبت نام برای»
`use`	«استفاده»

state_cookie_domain

اگر نیاز دارید که One Tap را در دامنه والد و زیردامنه‌های آن نمایش دهید، دامنه والد را به این فیلد ارسال کنید تا از یک کوکی با وضعیت مشترک استفاده شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`state_cookie_domain: "example.com"`

حالت_تجربه_کاربری

از این فیلد برای تنظیم جریان UX مورد استفاده توسط دکمه ورود با گوگل استفاده کنید. مقدار پیش‌فرض popup است. این ویژگی هیچ تاثیری بر UX OneTap ندارد. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`ux_mode: "redirect"`

جدول زیر حالت‌های UX موجود و توضیحات آنها را فهرست می‌کند.

حالت تجربه کاربری
`popup`	جریان تجربه کاربری ورود به سیستم را در یک پنجره بازشو اجرا می‌کند.
`redirect`	جریان تجربه کاربری ورود به سیستم را با تغییر مسیر کامل صفحه انجام می‌دهد.

allowed_parent_origin

مبداهایی که مجاز به جاسازی iframe میانی هستند. در صورت وجود این فیلد، One Tap در حالت iframe میانی اجرا می‌شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته یا آرایه رشته‌ای	اختیاری	`allowed_parent_origin: "https://example.com"`

جدول زیر انواع مقادیر پشتیبانی شده و توضیحات آنها را فهرست می‌کند.

انواع مقادیر
`string`	یک URI دامنه واحد.	`"https://example.com"`
`string array`	آرایه‌ای از URIهای دامنه.	`["https://news.example.com", "https://local.example.com"]`

پیشوندهای Wildcard نیز پشتیبانی می‌شوند. برای مثال، "https://*.example.com" با example.com و زیر دامنه‌های آن در تمام سطوح (مثلاً news.example.com ، login.news.example.com ) مطابقت دارد. نکاتی که هنگام استفاده از Wildcardها باید در نظر داشته باشید:

رشته‌های الگو نمی‌توانند فقط از یک wildcard و یک دامنه سطح بالا تشکیل شوند. برای مثال https:// .com و https:// .co.uk نامعتبر هستند زیرا "https:// .example.com" با example.com و تمام زیر دامنه‌های آن مطابقت دارد. برای نمایش دو دامنه مختلف از یک لیست جدا شده با کاما استفاده کنید. برای مثال، "https://example1.com,https:// .example2.com" با دامنه‌های example1.com ، example2.com و زیر دامنه‌های example2.com مطابقت دارد.
دامنه‌های Wildcard باید با یک طرح امن https:// شروع شوند، بنابراین "*.example.com" نامعتبر تلقی می‌شود.

اگر مقدار فیلد allowed_parent_origin نامعتبر باشد، مقداردهی اولیه One Tap از حالت iframe میانی با شکست مواجه شده و متوقف می‌شود.

intermediate_iframe_close_callback

وقتی کاربران با ضربه زدن روی دکمه 'X' در رابط کاربری One Tap، به صورت دستی One Tap را می‌بندند، رفتار پیش‌فرض iframe میانی را لغو می‌کند. رفتار پیش‌فرض این است که iframe میانی را فوراً از DOM حذف کند.

فیلد intermediate_iframe_close_callback فقط در حالت intermediate iframe اعمال می‌شود. و فقط روی intermediate iframe تأثیر می‌گذارد، نه روی One Tap iframe. رابط کاربری One Tap قبل از فراخوانی callback حذف می‌شود.

نوع	مورد نیاز	مثال
تابع	اختیاری	`intermediate_iframe_close_callback: logBeforeClose`

پشتیبانی itp

این فیلد تعیین می‌کند که آیا One Tap UX ارتقا یافته باید در مرورگرهایی که از Intelligent Tracking Prevention (ITP) پشتیبانی می‌کنند، فعال شود یا خیر. مقدار پیش‌فرض false است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
بولی	اختیاری	`itp_support: true`

login_hint

اگر برنامه شما از قبل بداند که کدام کاربر باید وارد سیستم شود، می‌تواند یک راهنمای ورود به سیستم به گوگل ارائه دهد. در صورت موفقیت، انتخاب حساب کاربری نادیده گرفته می‌شود. مقادیر پذیرفته شده عبارتند از: یک آدرس ایمیل یا یک مقدار زیر فیلد شناسه.

برای اطلاعات بیشتر، به فیلد login_hint در مستندات OpenID Connect مراجعه کنید.

نوع	مورد نیاز	مثال
رشته، یک آدرس ایمیل یا مقداری از یک فیلد `sub` توکن شناسه.	اختیاری	`login_hint: 'elisa.beckett@gmail.com'`

اچ دی

وقتی کاربری چندین حساب کاربری دارد و فقط باید با حساب Workspace خود وارد سیستم شود، از این برای ارائه یک اشاره‌گر نام دامنه به گوگل استفاده کنید. در صورت موفقیت، حساب‌های کاربری نمایش داده شده هنگام انتخاب حساب به دامنه ارائه شده محدود می‌شوند. مقدار wildcard: * فقط حساب‌های Workspace را به کاربر ارائه می‌دهد و حساب‌های کاربری (user@gmail.com) را هنگام انتخاب حساب کاربری حذف می‌کند.

برای اطلاعات بیشتر، به فیلد hd در مستندات OpenID Connect مراجعه کنید.

نوع	مورد نیاز	مثال
رشته. یک نام دامنه کاملاً واجد شرایط یا *.	اختیاری	`hd: '*'`

use_fedcm_for_prompt

به مرورگر اجازه دهید تا درخواست‌های ورود به سیستم کاربر را کنترل کند و جریان ورود به سیستم را بین وب‌سایت شما و گوگل میانجیگری کند. مقدار پیش‌فرض false است. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.

نوع	مورد نیاز	مثال
بولی	اختیاری	`use_fedcm_for_prompt: true`

دکمه‌ی use_fedcm_for_button

این فیلد تعیین می‌کند که آیا باید از رابط کاربری دکمه FedCM در کروم (دسکتاپ M125+ و اندروید M128+) استفاده شود یا خیر. مقدار پیش‌فرض false است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
بولی	اختیاری	`use_fedcm_for_button: true`

دکمه_انتخاب_خودکار

این فیلد تعیین می‌کند که آیا گزینه انتخاب خودکار برای جریان دکمه FedCM فعال شود یا خیر. در صورت فعال بودن، کاربرانی که دوباره با یک جلسه فعال گوگل وارد سیستم می‌شوند، به طور خودکار وارد سیستم می‌شوند و از اعلان انتخاب حساب عبور می‌کنند. مقدار پیش‌فرض false است. شما باید ورود خودکار به دکمه را به طور صریح در طول راه‌اندازی انتخاب فعال کنید. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
بولی	اختیاری	`button_auto_select: true`

روش: google.accounts.id.prompt

متد google.accounts.id.prompt پس از فراخوانی متد initialize() ، اعلان One Tap یا مدیریت اعتبارنامه داخلی مرورگر را نمایش می‌دهد. به نمونه کد زیر از این متد توجه کنید:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

معمولاً متد prompt() هنگام بارگذاری صفحه فراخوانی می‌شود. با توجه به وضعیت جلسه و تنظیمات کاربر در سمت گوگل، ممکن است رابط کاربری One Tap prompt نمایش داده نشود. برای اطلاع از وضعیت رابط کاربری در لحظات مختلف، تابعی را برای دریافت اعلان‌های وضعیت رابط کاربری ارسال کنید.

اعلان‌ها در لحظات زیر ارسال می‌شوند:

لحظه نمایش: این اتفاق پس از فراخوانی متد prompt() رخ می‌دهد. اعلان شامل یک مقدار بولی است که نشان می‌دهد رابط کاربری نمایش داده می‌شود یا خیر.
لحظه از دست رفته: این اتفاق زمانی می‌افتد که اعلان One Tap با لغو خودکار، لغو دستی یا زمانی که گوگل نتواند اعتبارنامه را صادر کند، بسته می‌شود، مانند زمانی که جلسه انتخاب شده از گوگل خارج شده است.
در این موارد، توصیه می‌کنیم در صورت وجود، به سراغ ارائه‌دهندگان هویت بعدی بروید.
لحظه لغو: این اتفاق زمانی رخ می‌دهد که گوگل با موفقیت یک اعتبارنامه را بازیابی کند یا کاربر بخواهد جریان بازیابی اعتبارنامه را متوقف کند. برای مثال، وقتی کاربر شروع به وارد کردن نام کاربری و رمز عبور خود در کادر ورود به سیستم می‌کند، می‌توانید متد google.accounts.id.cancel() برای بستن اعلان One Tap و ایجاد یک لحظه لغو فراخوانی کنید.
هشدار: وقتی در لحظه‌ی رد شدن هستید، هیچ یک از ارائه‌دهندگان هویت بعدی را امتحان نکنید.

مثال کد زیر لحظه‌ی از قلم افتاده را پیاده‌سازی می‌کند:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

نوع داده: اعلان لحظه‌ای سریع

جدول زیر متدها و توضیحات مربوط به نوع داده PromptMomentNotification را فهرست می‌کند:

روش
`isDisplayMoment()`	اگر اعلان One Tap نمایش داده شود، `true` برمی‌گرداند. توجه: وقتی FedCM فعال باشد، این اعلان پشتیبانی نمی‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`isDisplayed()`	اگر نوع لحظه `PromptMoment.DISPLAY` باشد و اعلان One Tap نمایش داده شود، `true` برمی‌گرداند. توجه: وقتی FedCM فعال باشد، این اعلان پشتیبانی نمی‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`isNotDisplayed()`	اگر نوع لحظه `PromptMoment.DISPLAY` باشد و اعلان One Tap نمایش داده نشود، `true` برمی‌گرداند. توجه: وقتی FedCM فعال باشد، این اعلان پشتیبانی نمی‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`getNotDisplayedReason()`	دلیل دقیق عدم نمایش رابط کاربری. مقادیر ممکن به شرح زیر است: `browser_not_supported` `invalid_client` `missing_client_id` `opt_out_or_no_session` `secure_http_required` `suppressed_by_user` `unregistered_origin` `unknown_reason` توجه: وقتی FedCM فعال باشد، این روش پشتیبانی نمی‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`isSkippedMoment()`	اگر نوع لحظه `PromptMoment.SKIPPED` باشد، `true` برمی‌گرداند. نکته: وقتی FedCM فعال باشد، این روش تا حدی پشتیبانی می‌شود. به طور خاص، از دلیل نادیده گرفته شده `user_cancel` پشتیبانی نمی‌کند. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`getSkippedReason()`	دلیل دقیق لحظه از دست رفته. مقادیر ممکن زیر هستند: `auto_cancel` `user_cancel` `tap_outside` `issuing_failed` نکته: وقتی FedCM فعال باشد، این روش تا حدی پشتیبانی می‌شود. به طور خاص، از دلیل نادیده گرفته شده `user_cancel` پشتیبانی نمی‌کند. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`isDismissedMoment()`	اگر نوع لحظه `PromptMoment.DISMISSED` باشد، `true` برمی‌گرداند. توجه: وقتی FedCM فعال باشد، این روش کاملاً پشتیبانی می‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`getDismissedReason()`	دلیل دقیق اخراج. مقادیر ممکن زیر عبارتند از: `credential_returned` `cancel_called` `flow_restarted` توجه: وقتی FedCM فعال باشد، این روش کاملاً پشتیبانی می‌شود. برای اطلاعات بیشتر به صفحه مهاجرت به FedCM مراجعه کنید.
`getMomentType()`	یک رشته برای نوع moment برمی‌گرداند. مقادیر زیر ممکن هستند: `display` `skipped` `dismissed`

نوع داده: پاسخ اعتبارنامه

وقتی تابع callback شما فراخوانی می‌شود، یک شیء CredentialResponse به عنوان پارامتر ارسال می‌شود. جدول زیر فیلدهایی را که در شیء پاسخ credential وجود دارند، فهرست می‌کند:

میدان
`credential`	توکن JWT ID کدگذاری شده‌ای که گوگل صادر می‌کند.
`select_by`	نحوه ورود کاربر.
`state`	این فیلد فقط زمانی تعریف می‌شود که کاربر برای ورود به سیستم روی دکمه‌ی «ورود با گوگل» کلیک کند و ویژگی `state` دکمه مشخص شده باشد.

اعتبارنامه

این فیلد، توکن شناسه به صورت یک رشته JSON Web Token (JWT) کدگذاری شده با پایه 64 است.

وقتی JWT رمزگشایی می‌شود ، مانند مثال زیر به نظر می‌رسد:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

این sub یک شناسه منحصر به فرد جهانی برای حساب گوگل است. فقط sub به عنوان شناسه برای کاربر استفاده کنید زیرا در بین همه حساب‌های گوگل منحصر به فرد است و هرگز دوباره استفاده نمی‌شود.

با استفاده از فیلدهای email ، email_verified و hd می‌توانید تعیین کنید که آیا گوگل میزبان و معتبر برای یک آدرس ایمیل است یا خیر. در مواردی که گوگل معتبر باشد، تأیید می‌شود که کاربر مالک قانونی حساب است.

مواردی که گوگل معتبر است:

اگر email پسوند @gmail.com دارد، این یک حساب جیمیل است.
email_verified روی true تنظیم شده و hd هم تنظیم شده است، این یک حساب Google Workspace است.

کاربران می‌توانند بدون استفاده از Gmail یا Google Workspace برای حساب‌های Google ثبت نام کنند. وقتی email حاوی پسوند @gmail.com نباشد و hd هم وجود نداشته باشد، گوگل معتبر نیست و روش‌های رمز عبور یا سایر روش‌های چالش‌برانگیز برای تأیید کاربر توصیه می‌شود. email_verfied همچنین می‌تواند درست باشد زیرا گوگل در ابتدا کاربر را هنگام ایجاد حساب Google تأیید کرده است، با این حال ممکن است مالکیت حساب ایمیل شخص ثالث از آن زمان تغییر کرده باشد.

فیلد exp زمان انقضای لازم برای تأیید توکن در سمت سرور را نشان می‌دهد. این زمان برای توکن شناسه دریافت شده از ورود با گوگل یک ساعت است. شما باید قبل از زمان انقضا ، توکن را تأیید کنید . exp برای مدیریت جلسه استفاده نکنید . منقضی شدن توکن شناسه به معنای خروج کاربر نیست . برنامه شما مسئول مدیریت جلسه کاربران شماست.

انتخاب_توسط

جدول زیر مقادیر ممکن برای فیلد select_by را فهرست می‌کند. نوع دکمه مورد استفاده به همراه جلسه و وضعیت رضایت برای تنظیم مقدار استفاده می‌شوند.

کاربر یا دکمه One Tap یا Sign In With Google را فشار می‌داد یا از فرآیند ورود خودکار بدون لمس استفاده می‌کرد.
یک جلسه موجود پیدا شد، یا کاربر یک حساب Google را برای ایجاد یک جلسه جدید انتخاب و وارد سیستم شد.
قبل از به اشتراک گذاشتن اعتبارنامه‌های توکن شناسایی با برنامه شما، کاربر می‌تواند یکی از موارد زیر را انجام دهد:
- دکمه تأیید را فشار داده تا رضایت خود را برای اشتراک‌گذاری اعتبارنامه‌ها اعلام کند، یا
- قبلاً رضایت داده بود و از «انتخاب حساب» برای انتخاب یک حساب Google استفاده کرده بود.

مقدار این فیلد روی یکی از این نوع‌ها تنظیم شده است،

ارزش	توضیحات
`auto`	ورود خودکار کاربری که قبلاً با اشتراک‌گذاری اعتبارنامه‌ها موافقت کرده است. این قابلیت فقط برای مرورگرهایی که از FedCM پشتیبانی نمی‌کنند، فعال است.
`user`	کاربری که قبلاً رضایت خود را اعلام کرده و دارای یک جلسه کاربری است، با فشردن دکمه «ادامه به عنوان» و فشردن یک ضربه، اطلاعات کاربری خود را به اشتراک گذاشته است. این قابلیت فقط برای مرورگرهایی که از FedCM پشتیبانی نمی‌کنند، فعال است.
`fedcm`	کاربر برای اشتراک‌گذاری اعتبارنامه‌ها با استفاده از FedCM، دکمه‌ی «ادامه به عنوان» را با یک ضربه فشار داده است. این مورد فقط در مرورگرهای پشتیبانی‌شده توسط FedCM اعمال می‌شود.
`fedcm_auto`	ورود خودکار کاربری که قبلاً با استفاده از FedCM One Tap رضایت خود را برای اشتراک‌گذاری اعتبارنامه‌ها اعلام کرده است. این قابلیت فقط برای مرورگرهای پشتیبانی‌شده توسط FedCM اعمال می‌شود.
`user_1tap`	کاربری که جلسه فعالی داشته، دکمه «ادامه به عنوان» را با یک ضربه فشار داده تا رضایت خود را اعلام کرده و اعتبارنامه‌ها را به اشتراک بگذارد. فقط در Chrome نسخه ۷۵ و بالاتر اعمال می‌شود.
`user_2tap`	کاربری که جلسه کاربری ندارد، دکمه «ادامه به عنوان» را با یک ضربه فشار داده تا یک حساب کاربری انتخاب کند و سپس دکمه تأیید را در یک پنجره بازشو فشار داده تا رضایت خود را اعلام کرده و اعتبارنامه‌ها را به اشتراک بگذارد. این مورد برای مرورگرهای غیر مبتنی بر کرومیوم اعمال می‌شود.
`itp`	کاربری که قبلاً رضایت خود را اعلام کرده بود، دکمه‌ی One Tap را در مرورگرهای ITP فشار داد.
`itp_confirm`	کاربری که رضایت نداده بود، دکمه One Tap را در مرورگرهای ITP فشار داد و دکمه «ادامه» را برای دادن رضایت و اشتراک‌گذاری اعتبارنامه‌ها فشار داد.
`btn`	کاربری که قبلاً رضایت خود را اعلام کرده بود، دکمه ورود با گوگل را فشار داد و یک حساب گوگل را از قسمت «انتخاب حساب» برای اشتراک‌گذاری اعتبارنامه انتخاب کرد.
`btn_confirm`	کاربری که رضایت نداده بود، دکمه ورود با گوگل را فشار داد و دکمه «ادامه» را برای دادن رضایت و اشتراک‌گذاری اطلاعات کاربری فشار داد.

ایالت

این فیلد فقط زمانی تعریف می‌شود که کاربر روی دکمه‌ی «ورود با گوگل» کلیک کند تا وارد سیستم شود و ویژگی state » دکمه‌ی کلیک‌شده مشخص شده باشد. مقدار این فیلد همان مقداری است که در ویژگی state » دکمه تعیین کرده‌اید.

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

روش: google.accounts.id.renderButton

متد google.accounts.id.renderButton یک دکمه‌ی ورود با گوگل (Sign In With Google) را در صفحات وب شما رندر می‌کند.

به نمونه کد زیر از این روش توجه کنید:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

نوع داده: GsiButtonConfiguration

جدول زیر فیلدها و توضیحات نوع داده GsiButtonConfiguration را فهرست می‌کند:

ویژگی
`type`	نوع دکمه: آیکون یا دکمه استاندارد.
`theme`	تم دکمه. برای مثال، filled_blue یا filled_black.
`size`	اندازه دکمه. مثلاً کوچک یا بزرگ.
`text`	متن دکمه. برای مثال، «ورود با گوگل» یا «ثبت نام با گوگل».
`shape`	شکل دکمه. مثلاً مستطیلی یا دایره‌ای.
`logo_alignment`	تراز لوگوی گوگل: چپ یا وسط
`width`	عرض دکمه، بر حسب پیکسل.
`locale`	اگر تنظیم شود، زبان دکمه رندر می‌شود.
`click_listener`	اگر تنظیم شود، این تابع زمانی فراخوانی می‌شود که روی دکمه‌ی ورود با گوگل کلیک شود.
`state`	در صورت تنظیم، این رشته به همراه توکن شناسه برمی‌گردد.

انواع ویژگی‌ها

بخش‌های بعدی شامل جزئیاتی در مورد نوع هر ویژگی و یک مثال است.

نوع

نوع دکمه. مقدار پیش‌فرض standard است.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	بله	`type: "icon"`

جدول زیر انواع دکمه‌های موجود و توضیحات آنها را فهرست می‌کند:

نوع
`standard`	دکمه‌ای با متن یا اطلاعات شخصی‌سازی‌شده.
`icon`	یک دکمه آیکونی بدون متن.

تم

تم دکمه. مقدار پیش‌فرض outline است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`theme: "filled_blue"`

جدول زیر فهرستی از تم‌های موجود و توضیحات آنها را نشان می‌دهد:

تم
`outline`	یک قالب دکمه استاندارد.
`filled_blue`	یک تم دکمه‌ای آبی‌رنگ.
`filled_black`	یک تم دکمه‌ای با رنگ مشکی.

اندازه

اندازه دکمه. مقدار پیش‌فرض large است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`size: "small"`

جدول زیر اندازه‌های دکمه‌های موجود و توضیحات آنها را نشان می‌دهد:

اندازه
`large`	یک دکمه بزرگ.
`medium`	یک دکمه با اندازه متوسط.
`small`	یک دکمه کوچک.

متن

متن دکمه. مقدار پیش‌فرض signin_with است. هیچ تفاوت بصری برای متن دکمه‌های آیکون که ویژگی‌های text متفاوتی دارند وجود ندارد. تنها استثنا زمانی است که متن برای دسترسی به صفحه نمایش خوانده می‌شود.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`text: "signup_with"`

جدول زیر تمام متن‌های دکمه‌های موجود و توضیحات آنها را فهرست می‌کند:

متن
`signin_with`	متن دکمه «ورود با گوگل» است.
`signup_with`	متن دکمه «ثبت نام با گوگل» است.
`continue_with`	متن دکمه «ادامه با گوگل» است.
`signin`	متن دکمه «ورود» است.

شکل

شکل دکمه. مقدار پیش‌فرض rectangular است. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`shape: "rectangular"`

جدول زیر شکل‌های دکمه‌های موجود و توضیحات آنها را فهرست می‌کند:

شکل
`rectangular`	دکمه مستطیل شکل. اگر برای نوع دکمه `icon` استفاده شود، مانند `square` است.
`pill`	دکمه قرصی شکل. اگر برای نوع دکمه `icon` استفاده شود، مانند `circle` است.
`circle`	دکمه دایره‌ای شکل. اگر برای نوع دکمه `standard` استفاده شود، همان `pill` است.
`square`	دکمه مربع شکل. اگر برای نوع دکمه `standard` استفاده شود، همان `rectangular` است.

ترازبندی_لوگو

ترازبندی لوگوی گوگل. مقدار پیش‌فرض left است. این ویژگی فقط برای نوع standard دکمه اعمال می‌شود. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`logo_alignment: "center"`

جدول زیر ترازبندی‌های موجود و توضیحات آنها را فهرست می‌کند:

ترازبندی_لوگو
`left`	لوگوی گوگل را در سمت چپ تراز می‌کند.
`center`	لوگوی گوگل را در مرکز تراز می‌کند.

عرض

حداقل عرض دکمه، بر حسب پیکسل. حداکثر عرض ۴۰۰ پیکسل است.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`width: "400"`

محلی

اختیاری. متن دکمه را با استفاده از زبان مشخص شده نمایش دهید، در غیر این صورت به طور پیش‌فرض تنظیمات حساب گوگل یا مرورگر کاربر را نمایش دهید. پارامتر hl و کد زبان را هنگام بارگیری کتابخانه به دستورالعمل src اضافه کنید، برای مثال: gsi/client?hl=<iso-639-code> .

اگر تنظیم نشده باشد، زبان پیش‌فرض مرورگر یا تنظیمات کاربر جلسه گوگل استفاده می‌شود. بنابراین، کاربران مختلف ممکن است نسخه‌های متفاوتی از دکمه‌های محلی‌شده و احتمالاً با اندازه‌های مختلف را ببینند.

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`locale: "zh_CN"`

کلیک_شنونده

شما می‌توانید با استفاده از ویژگی click_listener یک تابع جاوا اسکریپت تعریف کنید که هنگام کلیک روی دکمه ورود با گوگل فراخوانی شود.

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }

در این مثال، پیام «ورود با دکمه گوگل کلیک شد...» هنگام کلیک بر روی دکمه «ورود با گوگل» در کنسول ثبت می‌شود.

ایالت

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

برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

نوع	مورد نیاز	مثال
رشته	اختیاری	`data-state: "button 1"`

نوع داده: اعتبارنامه

وقتی تابع native_callback شما فراخوانی می‌شود، یک شیء Credential به عنوان پارامتر ارسال می‌شود. جدول زیر فیلدهای موجود در این شیء را فهرست می‌کند:

میدان
`id`	کاربر را شناسایی می‌کند.
`password`	رمز عبور

روش: google.accounts.id.disableAutoSelect

وقتی کاربر از وب‌سایت شما خارج می‌شود، باید متد google.accounts.id.disableAutoSelect را برای ثبت وضعیت در کوکی‌ها فراخوانی کنید. این کار از ایجاد حلقه‌ی تکرار در تجربه‌ی کاربری (UX dead loop) جلوگیری می‌کند. قطعه کد زیر از این متد را مشاهده کنید:

google.accounts.id.disableAutoSelect()

مثال کد زیر متد google.accounts.id.disableAutoSelect را با تابع onSignout() پیاده‌سازی می‌کند:

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

روش: google.accounts.id.storeCredential

این متد یک پوشش برای متد store() از API مدیریت اعتبارنامه داخلی مرورگر است. بنابراین، فقط می‌تواند برای ذخیره اعتبارنامه رمز عبور استفاده شود. به نمونه کد زیر از این متد توجه کنید:

google.accounts.id.storeCredential(Credential, callback)

مثال کد زیر متد google.accounts.id.storeCredential را با تابع onSignIn() پیاده‌سازی می‌کند:

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

روش: google.accounts.id.cancel

اگر اعلان را از DOM طرف وابسته حذف کنید، می‌توانید جریان One Tap را لغو کنید. اگر اعتبارنامه‌ای از قبل انتخاب شده باشد، عملیات لغو نادیده گرفته می‌شود. به نمونه کد زیر از این روش مراجعه کنید:

google.accounts.id.cancel()

مثال کد زیر متد google.accounts.id.cancel() را با تابع onNextButtonClicked() پیاده‌سازی می‌کند:

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

فراخوانی مجدد بارگذاری کتابخانه: onGoogleLibraryLoad

شما می‌توانید یک فراخوانی onGoogleLibraryLoad ثبت کنید. این فراخوانی پس از بارگذاری کتابخانه جاوا اسکریپت Sign In With Google اطلاع‌رسانی می‌شود:

window.onGoogleLibraryLoad = () => {
    ...
};

این تابع فراخوانی فقط یک میانبر برای تابع فراخوانی window.onload است و هیچ تفاوتی در رفتار آنها وجود ندارد.

مثال کد زیر، فراخوانی onGoogleLibraryLoad را پیاده‌سازی می‌کند:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

روش: google.accounts.id.revoke

متد google.accounts.id.revoke مجوز OAuth مورد استفاده برای اشتراک‌گذاری توکن شناسه برای کاربر مشخص شده را لغو می‌کند. قطعه کد زیر از این متد را ببینید: javascript google.accounts.id.revoke(login_hint, callback)

پارامتر	نوع	توضیحات
`login_hint`	رشته	آدرس ایمیل یا شناسه منحصر به فرد حساب گوگل کاربر. شناسه، `sub` محتوای اعتبارنامه (credential payload) است.
`callback`	تابع	کنترل‌کننده‌ی اختیاری RevocationResponse .

نمونه کد زیر نحوه استفاده از متد revoke با یک ID را نشان می‌دهد.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

نوع داده: RevocationResponse

وقتی تابع callback شما فراخوانی می‌شود، یک شیء RevocationResponse به عنوان پارامتر ارسال می‌شود. جدول زیر فیلدهایی را که در شیء پاسخ ابطال وجود دارند، فهرست می‌کند:

میدان
`successful`	این فیلد مقدار برگشتی از فراخوانی متد است.
`error`	این فیلد به صورت اختیاری شامل یک پیام پاسخ خطای دقیق است.

موفق

این فیلد یک مقدار بولی است که در صورت موفقیت‌آمیز بودن فراخوانی متد لغو، مقدار آن true و در صورت شکست، مقدار آن false می‌شود.

خطا

این فیلد یک مقدار رشته‌ای است و در صورت عدم موفقیت فراخوانی متد لغو، حاوی یک پیام خطای دقیق است که در صورت موفقیت تعریف نشده است.

با مرجع Google JavaScript API وارد شوید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

روش: google.accounts.id.initialize

نوع داده: IdConfiguration

شناسه_مشتری

طرح_رنگ

انتخاب خودکار

تماس برگشتی

login_uri

native_callback

لغو_در_ضربه_خارج

prompt_parent_id

نانس

زمینه

state_cookie_domain

حالت_تجربه_کاربری

allowed_parent_origin

intermediate_iframe_close_callback

پشتیبانی itp

login_hint

اچ دی

use_fedcm_for_prompt

دکمه‌ی use_fedcm_for_button

دکمه_انتخاب_خودکار

روش: google.accounts.id.prompt

نوع داده: اعلان لحظه‌ای سریع

نوع داده: پاسخ اعتبارنامه

اعتبارنامه

انتخاب_توسط

ایالت

روش: google.accounts.id.renderButton

نوع داده: GsiButtonConfiguration

انواع ویژگی‌ها

نوع

تم

اندازه

متن

شکل

ترازبندی_لوگو

عرض

محلی

کلیک_شنونده

ایالت

نوع داده: اعتبارنامه

روش: google.accounts.id.disableAutoSelect

روش: google.accounts.id.storeCredential

روش: google.accounts.id.cancel

فراخوانی مجدد بارگذاری کتابخانه: onGoogleLibraryLoad

روش: google.accounts.id.revoke

نوع داده: RevocationResponse

موفق

خطا

با مرجع Google JavaScript API وارد شوید