مرجع میانای برنامه‌سازی کاربردی HTML «ورود به سیستم با Google»

این صفحه مرجع، میانای برنامه‌سازی کاربردی ویژگی‌های داده HTML «ورود به سیستم با Google» را شرح می‌دهد، که برای نمایش دکمه «ورود به سیستم با Google» یا پیام‌واره One Tap در صفحه‌های وب استفاده می‌شود.

عنصر با شناسه «g_id_onload»

می‌توانید مشخصه‌های داده «ورود به سیستم با Google» را در هر عنصر مرئی یا نامرئی، مثل <div> و <span>، قرار دهید. تنها شرط این است که شناسه عنصر روی g_id_onload تنظیم شده باشد. این شناسه را روی چند عنصر قرار ندهید.

مشخصه‌های داده

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

مشخصه
data-client_id شناسه کارخواه برنامه‌تان
data-color_scheme آرایش رنگ‌های اعمال‌شده بر پیام‌واره One Tap.
data-auto_prompt نمایش تک‌ضرب Google One.
data-auto_select انتخاب خودکار را در Google One Tap فعال می‌کند.
data-login_uri نشانی وب نقطه پایان ورود به سیستم شما
data-callback نام تابع گرداننده شناسه ژتون جاوا اسکریپت
data-native_login_uri نشانی وب نقطه پایان کنترل‌کننده اطلاعات کاربری گذرواژه شما
data-native_callback نام تابع کنترل‌کننده اطلاعات کاربری گذرواژه جاوا اسکریپت
data-native_id_param نام پارامتر برای مقدار credential.id
data-native_password_param نام پارامتر برای مقدار credential.password
data-cancel_on_tap_outside کنترل می‌کند که اگر کاربر خارج از پیام‌واره کلیک کند، پیام‌واره لغو شود یا نه.
data-prompt_parent_id شناسه DOM عنصر محتوی پیام‌واره One Tap
data-skip_prompt_cookie اگر کوکی مشخص‌شده مقدار غیرخالی داشته باشد، از One Tap رد می‌شود.
data-nonce رشته‌ای تصادفی برای نشان‌های شناسه
data-essential_claims ادعاهای اضافی برای گنجاندن در شناسه ژتون برگردانده‌شده توسط Google.
data-context عنوان و کلمات در پیام‌واره «تک‌ضرب»
data-moment_callback نام تابع شنونده اعلان وضعیت واسط کاربر پیام‌واره
data-state_cookie_domain اگر لازم است One Tap را در دامنه اصلی و زیردامنه‌های آن فراخوانی کنید، دامنه اصلی را به این مشخصه ارسال کنید تا از یک کوکی مشترک واحد استفاده شود.
data-ux_mode جریان تجربه کاربری دکمه «ورود به سیستم با Google»
data-allowed_parent_origin مبدأهایی که مجاز به جاسازی iframe واسط هستند. اگر این مشخصه وجود داشته باشد، «ورود با یک ضربه» در حالت میانجی iframe اجرا می‌شود.
data-intermediate_iframe_close_callback وقتی کاربران One Tap را به‌طور دستی می‌بندند، رفتار iframe واسط پیش‌فرض را لغو می‌کند.
data-itp_support تجربه کاربری One Tap ارتقایافته را در مرورگرهای ITP فعال می‌کند.
data-login_hint با ارائه راهنمایی کاربر، از انتخاب حساب رد شوید.
data-hd انتخاب حساب را براساس دامنه محدود کنید.
data-use_fedcm_for_prompt به مرورگر اجازه دهید پیام‌واره‌های ورود به سیستم کاربر را کنترل کند و میانجی جریان ورود به سیستم بین وب‌سایت شما و Google باشد.
data-use_fedcm_for_button این فیلد تعیین می‌کند که آیا باید از تجربه کاربری دکمه FedCM در Chrome استفاده شود یا نه (رایانه M125+‎ و Android M128+‎). پیش‌فرض false است.
data-button_auto_select اینکه گزینه انتخاب خودکار برای جریان دکمه FedCM فعال شود یا نه. اگر فعال باشد، کاربران بازگشتی که جلسه Google فعال دارند به‌طور خودکار به سیستم وارد می‌شوند و درخواست «انتخاب‌گر حساب» را دور می‌زنند. مقدار پیش‌فرض false است.

انواع مشخصه

بخش‌های زیر حاوی جزئیات مربوط به هر نوع مشخصه و یک نمونه است.

data-client_id

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

نوع الزامی مثال
رشته بله data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-color_scheme

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

نوع الزامی مثال
رشته اختیاری. به‌طور پیش‌فرض روی آرایش رنگ‌های پیش‌فرض سیستم کاربر تنظیم می‌شود. data-color_scheme="dark"

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

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

data-auto_prompt

این مشخصه تعیین می‌کند که «ورود با یک ضربه» نمایش داده شود یا نه. مقدار پیش‌فرض true است. وقتی این مقدار false باشد، Google One tap نمایش داده نمی‌شود. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
بولی اختیاری data-auto_prompt="true"

data-auto_select

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

نوع الزامی مثال
بولی اختیاری data-auto_select="true"

data-login_uri

این مشخصه شناسه منبع یکسان نقطه پایانی ورود به سیستم شما است.

این مقدار باید دقیقاً با یکی از URIهای هدایت مجاز برای کارخواه OAuth 2.0 که در Google Auth Platform پیکربندی کرده‌اید مطابقت داشته باشد و باید با قوانین اعتبارسنجی URI هدایت ما مطابقت داشته باشد.

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

وقتی تابع بازخوانی تعریف نشده باشد و کاربر روی دکمه‌های «ورود به سیستم با Google» یا «تک‌ضرب» کلیک کند، یا ورود خودکار به سیستم انجام شود، پاسخ اطلاعات اعتباری کد شناسه در نقطه پایانی ورود به سیستم شما پست می‌شود.

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

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع اختیاری مثال
نشانی وب به‌طور پیش‌فرض روی شناسه منبع یکسان صفحه فعلی یا مقداری که مشخص می‌کنید تنظیم می‌شود.
وقتی data-ux_mode="popup" و data-callback تنظیم شده باشد، نادیده گرفته می‌شود.
data-login_uri="https://www.example.com/login"

data-callback

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

نوع الزامی مثال
رشته اگر data-login_uri تنظیم نشده باشد، الزامی است. data-callback="handleToken"

ممکن است یکی از مشخصه‌های data-login_uri و data-callback استفاده شود. این به پیکربندی‌های مؤلفه و حالت UX زیر بستگی دارد:

  • مشخصه data-login_uri برای حالت تجربه کاربری دکمه «ورود به سیستم با Google» redirect الزامی است، که مشخصه data-callback را نادیده می‌گیرد.

  • یکی از این دو مشخصه باید برای «تک‌ضرب Google» و دکمه «ورود به سیستم با Google» popup حالت UX تنظیم شود. اگر هر دو تنظیم شده باشند، مشخصه data-callback اولویت بالاتری دارد.

توابع جاوا اسکریپت در فضای نام توسط HTML API پشتیبانی نمی‌شوند. درعوض، از تابع جاوا اسکریپت سراسری بدون جای‌نام استفاده کنید. برای مثال، از mylibCallback به‌جای mylib.callback استفاده کنید.

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

data-native_login_uri

این مشخصه نشانی وب نقطه پایانی کنترل‌کننده اطلاعات کاربری گذرواژه شما است. اگر مشخصه data-native_login_uri یا مشخصه data-native_callback را تنظیم کنید، کتابخانه JavaScript درصورت نبودن جلسه Google، به مدیر اطلاعات کاربری داخلی برمی‌گردد. نمی‌توانید هر دو مشخصه data-native_callback و data-native_login_uri را تنظیم کنید. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-login_uri="https://www.example.com/password_login"

data-native_callback

این مشخصه نام تابع جاوا اسکریپت است که اعتبارنامه گذرواژه برگردانده‌شده از مدیر اعتبارنامه داخلی مرورگر را مدیریت می‌کند. اگر مشخصه data-native_login_uri یا مشخصه data-native_callback را تنظیم کنید، کتابخانه JavaScript درصورت نبودن جلسه Google، به مدیر اطلاعات کاربری داخلی برمی‌گردد. نمی‌توانید هر دو data-native_callback و data-native_login_uri را تنظیم کنید. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-native_callback="handlePasswordCredential"

توابع جاوا اسکریپت در فضای نام توسط HTML API پشتیبانی نمی‌شوند. درعوض، از تابع جاوا اسکریپت سراسری بدون جای‌نام استفاده کنید. برای مثال، از mylibCallback به‌جای mylib.callback استفاده کنید.

data-native_id_param

وقتی اطلاعات اعتباری گذرواژه را به نقطه پایانی گرداننده اطلاعات اعتباری گذرواژه ارسال می‌کنید، می‌توانید نام پارامتر را برای فیلد credential.id مشخص کنید. نام پیش‌فرض email است. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
نشانی وب اختیاری data-native_id_param="user_id"

data-native_password_param

وقتی اعتبارنامه گذرواژه را به نقطه پایانی کنترل‌کننده اعتبارنامه گذرواژه ارسال می‌کنید، می‌توانید نام پارامتر را برای مقدار credential.password مشخص کنید. نام پیش‌فرض password است. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
نشانی وب اختیاری data-native_password_param="pwd"

data-cancel_on_tap_outside

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

نوع الزامی مثال
بولی اختیاری data-cancel_on_tap_outside="false"

data-prompt_parent_id

این مشخصه شناسه DOM عنصر محتوی را تنظیم می‌کند. اگر تنظیم نشده باشد، پیام‌واره «یک‌ضربه‌ای» در گوشه بالا سمت راست پنجره نمایش داده می‌شود. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-prompt_parent_id="parent_id"

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

نوع الزامی مثال
رشته اختیاری data-skip_prompt_cookie="SID"

data-nonce

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

نوع الزامی مثال
رشته اختیاری data-nonce="biaqbm70g23"

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

data-essential_claims

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

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-essential_claims="auth_time, amr"

بافت داده‌ها

این فیلد نوشتار عنوان و پیام‌های نشان‌داده‌شده در پیام‌واره «یک‌ضربه‌ای» را تغییر می‌دهد، تأثیری بر مرورگرهای ITP ندارد. پیش‌فرض‌ها به signin.

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-context="use"

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

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

data-moment_callback

این مشخصه نام تابع شنونده اعلان وضعیت واسط کاربر پیام‌واره است. برای اطلاعات بیشتر، به نوع داده PromptMomentNotification مراجعه کنید.

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-moment_callback="logMomentNotification"

توابع جاوا اسکریپت در فضای نام توسط HTML API پشتیبانی نمی‌شوند. درعوض، از تابع جاوا اسکریپت سراسری بدون جای‌نام استفاده کنید. برای مثال، از mylibCallback به‌جای mylib.callback استفاده کنید.

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

نوع الزامی مثال
رشته اختیاری data-state_cookie_domain="example.com"

data-ux_mode

این مشخصه جریان UX مورداستفاده دکمه «ورود به سیستم با Google» را تنظیم می‌کند. مقدار پیش‌فرض popup است. این مشخصه تأثیری بر One Tap UX ندارد. برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-ux_mode="redirect"

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

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

data-allowed_parent_origin

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

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

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

انواع مقدار
string یک URI دامنه. "https://example.com"
string array فهرستی از URIهای دامنه جداشده با کاما. "https://news.example.com,https://local.example.com"

اگر مقدار مشخصه data-allowed_parent_origin نامعتبر باشد، مقداردهی اولیه One Tap در حالت iframe واسط ناموفق خواهد بود و متوقف می‌شود.

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

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

data-intermediate_iframe_close_callback

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

فیلد data-intermediate_iframe_close_callback فقط در حالت iframe واسط اعمال می‌شود. و فقط بر iframe واسطه تأثیر می‌گذارد، نه iframe «ورود با یک ضربه». رابط کاربری «ورود با یک ضربه» قبل‌از فراخوانی فراخوان برگشتی برداشته می‌شود.

نوع الزامی مثال
عملکرد اختیاری data-intermediate_iframe_close_callback="logBeforeClose"

توابع جاوا اسکریپت در فضای نام توسط HTML API پشتیبانی نمی‌شوند. درعوض، از تابع جاوا اسکریپت سراسری بدون جای‌نام استفاده کنید. برای مثال، از mylibCallback به‌جای mylib.callback استفاده کنید.

data-itp_support

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

نوع الزامی مثال
بولی اختیاری data-itp_support="false"

data-login_hint

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

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

نوع الزامی مثال
رشته. می‌تواند نشانی ایمیل یا مقدار فیلد sub از شناسه ژتون باشد. اختیاری data-login_hint="elisa.beckett@gmail.com"

data-hd

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

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

نوع الزامی مثال
رشته. نام دامنه کاملاً واجدشرایط یا *. اختیاری data-hd="*"

data-use_fedcm_for_prompt

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

نوع الزامی مثال
بولی منسوخ data-use_fedcm_for_prompt="true"

data-use_fedcm_for_button

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

نوع الزامی مثال
بولی اختیاری data-use_fedcm_for_button="true"

data-button_auto_select

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

نوع الزامی مثال
بولی اختیاری data-button_auto_select="true"

عنصر با کلاس «g_id_signin»

اگر g_id_signin را به مشخصه class عنصر اضافه کنید، عنصر به‌صورت دکمه «ورود به سیستم با Google» ارائه می‌شود.

می‌توانید چندین دکمه «ورود به سیستم با Google» را در یک صفحه ارائه دهید. هر دکمه می‌تواند تنظیمات دیداری خودش را داشته باشد. تنظیمات با مشخصه‌های داده زیر تعریف می‌شود.

مشخصه‌های داده‌های بصری

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

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

انواع مشخصه

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

نوع داده

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

نوع الزامی مثال
رشته بله data-type="icon"

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

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

data-theme

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

نوع الزامی مثال
رشته اختیاری data-theme="filled_blue"

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

زمینه نمونه‌ها مشخصات
outline
standard-button-white icon-button-white personalized-button-white
زمینه دکمه استاندارد.
Fill: #FFFFFF
Stroke: #747775 | 1px | inside
Font: #1F1F1F | Roboto Medium | 14/20
Personalized: #1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue
زمینه دکمه با رنگ آبی.
Fill: #0B57D0
Stroke: #OB57D0 | 1px | inside
Font: #FFFFFF | Google Sans Medium | 14/20
Personalized: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black
زمینه دکمه با رنگ مشکی و نشان‌واره متضاد.
Fill: #202124
Stroke: #OB57D0 | 1px | inside
Font: #FFFFFF | Google Sans Medium | 14/20
Personalized: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark
زمینه دکمه با رنگ مشکی.
Fill: #131314
Stroke: #8E918F | 1px | inside
Font: #FFFFFF | Google Sans Medium | 14/20
Personalized: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13

اندازه داده‌ها

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

نوع الزامی مثال
رشته اختیاری data-size="small"

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

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

نوشتار-داده

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

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-text="signup_with"

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

نوشتار
signin_with
دکمه‌ای استاندارد با برچسب «ورود به سیستم با Google» دکمه نماد بدون نوشتار قابل‌مشاهده
نوشتار دکمه «ورود به سیستم با Google» است.
signup_with
دکمه‌ای استاندارد با برچسب «ثبت‌نام با Google» دکمه نماد بدون نوشتار قابل‌مشاهده
نوشتار دکمه «ثبت‌نام با Google» است.
continue_with
دکمه‌ای استاندارد با برچسب «ادامه دادن با Google» دکمه نماد بدون نوشتار قابل‌مشاهده
نوشتار دکمه «ادامه با Google» است.
signin
دکمه‌ای استاندارد با برچسب «ورود به سیستم» دکمه نماد بدون نوشتار قابل‌مشاهده
نوشتار دکمه «ورود به سیستم» است.

data-shape

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

نوع الزامی مثال
رشته اختیاری data-shape="rectangular"

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

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

data-logo_alignment

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

نوع الزامی مثال
رشته اختیاری data-logo_alignment="center"

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

logo_alignment
left
دکمه استاندارد با نشان‌واره G در سمت چپ
نشان‌واره Google را چپ‌چین می‌کند.
center
دکمه استاندارد با نشان‌واره G در مرکز
نشان‌واره Google را در مرکز تراز می‌کند.

data-width

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

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-width=400

data-locale

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

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

برای اطلاعات بیشتر، جدول زیر را ببینید:

نوع الزامی مثال
رشته اختیاری data-locale="zh_CN"

data-click_listener

می‌توانید تابع جاوا اسکریپت را تعریف کنید تا وقتی روی دکمه «ورود به سیستم با Google» کلیک می‌شود، بااستفاده از مشخصه data-click_listener فراخوانی شود.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

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

وضعیت داده‌ها

اختیاری، چون چند دکمه «ورود به سیستم با Google» را می‌توان در یک صفحه ارائه کرد، می‌توانید برای هر دکمه یک رشته منحصربه‌فرد اختصاص دهید. همان رشته همراه با کد شناسه برگردانده می‌شود تا بتوانید تشخیص دهید کاربر روی کدام دکمه برای ورود به سیستم کلیک کرده است.

برای اطلاعات بیشتر، جدول زیر را ببینید:

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

ادغام سمت سرور

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

نقطه پایان کنترل‌کننده کد شناسه

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

نمونه درخواست به نقطه پایانی ورود به سیستم شما:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

درخواست اچ‌تی‌تی‌پی POST حاوی اطلاعات زیر است:

قالب نام شرح
کوکی g_csrf_token رشته‌ای تصادفی که با هر درخواست به نقطه پایانی ورود به سیستم مشخص‌شده توسط data-login_uri تغییر می‌کند، باید با مقدار موجود در پارامتر درخواست g_csrf_token مطابقت داشته باشد.
پارامتر درخواست g_csrf_token رشته‌ای تصادفی که با هر درخواست به نقطه پایانی ورود به سیستم مشخص‌شده توسط data-login_uri تغییر می‌کند، باید با مقدار کوکی g_csrf_token مطابقت داشته باشد.
پارامتر درخواست credential نشان شناسه JWT کدگذاری‌شده که Google صادر می‌کند.
پارامتر درخواست state این پارامتر فقط زمانی تعریف می‌شود که کاربر برای ورود به سیستم روی دکمه «ورود به سیستم با Google» کلیک کند و مشخصه state دکمه مشخص شده باشد.

مدرک شناسایی (جمع: مدارک شناسایی)

وقتی رمزگشایی شود، شناسه به‌صورت نمونه زیر خواهد بود:

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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

کارخواه‌ها باید ادعاهای JWT ناشناخته را نادیده بگیرند.

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

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

مواردی که Google مرجع است:

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

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

فیلد exp زمان انقضا را برای شما نشان می‌دهد تا توکن را در سمت سرور خود درستی‌سنجی کنید. این مدت برای کد شناسه به‌دست‌آمده از «ورود به سیستم با Google» یک ساعت است. باید پیش‌از زمان انقضا، ژتون را درستی‌سنجی کنید. از exp برای مدیریت جلسه استفاده نکنید. منقضی شدن شناسه توکن به این معنی نیست که کاربر از سیستم خارج شده است. برنامه شما مسئول مدیریت جلسه کاربران شما است.

g_csrf_token

کد حالت ضدجعل. این یک کد جعل درخواست بین‌سایتی (CSRF) است که توسط کتابخانه gsi/client ایجاد شده است. یک مقدار تصادفی هم به‌عنوان کوکی و هم به‌عنوان پارامتر درخواست در بدنه بار داده POST گنجانده شده است. اگر این دو مقدار هنگام پردازش درخواست در سرور شما مطابقت نداشته باشند، درخواست باید نامعتبر درنظر گرفته شود.

ایالت

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

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

نقطه پایانی کنترل‌کننده اطلاعات کاربری گذرواژه

نقطه پایانی کنترل‌کننده اعتبارنامه گذرواژه، اعتبارنامه‌های گذرواژه‌ای را که مدیر اعتبارنامه داخلی بازیابی می‌کند پردازش می‌کند.

درخواست اچ‌تی‌تی‌پی POST حاوی اطلاعات زیر است:

قالب نام شرح
کوکی g_csrf_token رشته‌ای تصادفی که با هر درخواست به نقطه پایانی ورود به سیستم مشخص‌شده توسط data-native_login_uri تغییر می‌کند، باید با مقدار موجود در پارامتر درخواست g_csrf_token مطابقت داشته باشد.
پارامتر درخواست g_csrf_token رشته‌ای تصادفی که با هر درخواست به نقطه پایانی ورود به سیستم مشخص‌شده توسط data-native_login_uri تغییر می‌کند، باید با مقدار کوکی g_csrf_token مطابقت داشته باشد.
پارامتر درخواست email این شناسه توکنی است که Google صادر می‌کند.
پارامتر درخواست password نحوه انتخاب اعتبارنامه.