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

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

عنصر با شناسه "g_id_onload"

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

ویژگی‌های داده

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

ویژگی
data-client_id شناسه کلاینت برنامه شما
data-color_scheme طرح رنگی اعمال شده برای اعلان One Tap.
data-auto_prompt نمایش ضربه گوگل وان.
data-auto_select انتخاب خودکار را در Google One Tap فعال می‌کند.
data-login_uri آدرس اینترنتی (URL) نقطه پایانی ورود شما
data-callback نام تابع مدیریت توکن شناسه جاوا اسکریپت
data-native_login_uri آدرس اینترنتی (URL) نقطه پایانی کنترل‌کننده اعتبارنامه رمز عبور شما
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 اگر کوکی مشخص شده مقداری غیر خالی داشته باشد، از یک ضربه صرف نظر می‌کند.
data-nonce یک رشته تصادفی برای توکن‌های شناسه
data-context عنوان و کلمات موجود در اعلان One Tap
data-moment_callback نام تابع شنونده اعلان وضعیت رابط کاربری سریع
data-state_cookie_domain اگر نیاز دارید که One Tap را در دامنه والد و زیردامنه‌های آن فراخوانی کنید، دامنه والد را به این ویژگی منتقل کنید تا از یک کوکی مشترک استفاده شود.
data-ux_mode جریان تجربه کاربری دکمه ورود با گوگل
data-allowed_parent_origin مبداهایی که مجاز به جاسازی iframe میانی هستند. اگر این ویژگی وجود داشته باشد، One Tap در حالت 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 به مرورگر اجازه دهید تا درخواست‌های ورود کاربر را کنترل کند و جریان ورود به سیستم را بین وب‌سایت شما و گوگل واسطه‌گری کند.
data-use_fedcm_for_button این فیلد تعیین می‌کند که آیا باید از رابط کاربری دکمه FedCM در کروم (دسکتاپ M125+ و اندروید M128+) استفاده شود یا خیر. مقدار پیش‌فرض false است.
data-button_auto_select آیا گزینه انتخاب خودکار برای جریان دکمه FedCM فعال شود یا خیر. در صورت فعال بودن، کاربرانی که دوباره با یک جلسه فعال گوگل وارد سیستم می‌شوند، به طور خودکار وارد سیستم می‌شوند و از مرحله انتخاب حساب کاربری عبور می‌کنند. مقدار پیش‌فرض false است.

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

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

شناسه-مشتری-داده

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

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

طرح رنگ داده

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

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

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

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

تابع داده خودکار

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

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

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

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

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

داده-login_uri

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

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

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

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

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

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

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

فراخوانی داده

این ویژگی نام تابع جاوا اسکریپتی است که توکن شناسه (ID token) برگردانده شده را مدیریت می‌کند. برای اطلاعات بیشتر به جدول زیر مراجعه کنید:

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

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

  • ویژگی data-login_uri برای حالت UX redirect دکمه ورود با گوگل الزامی است، که ویژگی data-callback را نادیده می‌گیرد.

  • یکی از این دو ویژگی باید برای حالت تجربه کاربری popup دکمه ورود گوگل و حالت وان تپ تنظیم شود. اگر هر دو تنظیم شده باشند، ویژگی data-callback اولویت بالاتری دارد.

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

داده-بومی_login_uri

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

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

فراخوانی برگشتی داده-بومی

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

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

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

پارامتر_id_native_data

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

نوع مورد نیاز مثال
آدرس اینترنتی اختیاری data-native_id_param="user_id"

پارامتر رمز عبور بومی داده

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

نوع مورد نیاز مثال
آدرس اینترنتی اختیاری data-native_password_param="pwd"

لغو داده روی ضربه زدن به بیرون

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

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

شناسه-متغیر_والد_داده

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

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

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

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

داده-نانوس

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

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

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

زمینه داده

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

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

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

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

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

داده-لحظه_فراخوانی

این ویژگی نام تابعِ شنونده‌ی اعلان وضعیت رابط کاربری سریع (prompt UI status listener) است. برای اطلاعات بیشتر، به نوع داده‌ی PromptMomentNotification مراجعه کنید.

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

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

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

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

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

حالت داده-ux_mode

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

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

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

حالت تجربه کاربری
popup جریان تجربه کاربری ورود به سیستم را در یک پنجره بازشو اجرا می‌کند.
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 میانی با شکست مواجه شده و متوقف می‌شود.

پیشوندهای 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" نامعتبر تلقی می‌شود.

داده-میانجی_iframe_close_callback

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

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

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

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

پشتیبانی-itp_data

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

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

راهنمایی-ورود-داده

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

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

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

دیتا-اچ‌دی

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

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

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

استفاده از داده برای اعلان

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

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

دکمه-استفاده-از-داده_fedcm_for_button

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

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

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

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

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

عنصر با کلاس "g_id_signin"

اگر g_id_signin به ویژگی class یک عنصر اضافه کنید، آن عنصر به عنوان یک دکمه ورود با گوگل رندر می‌شود.

شما می‌توانید چندین دکمه‌ی ورود با گوگل را در یک صفحه نمایش دهید. هر دکمه می‌تواند تنظیمات بصری مخصوص به خود را داشته باشد. این تنظیمات توسط ویژگی‌های داده‌ی زیر تعریف می‌شوند.

ویژگی‌های داده‌های بصری

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

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

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

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

نوع داده

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

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

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

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

قالب داده

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

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

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

تم
outline
یک دکمه استاندارد با پس‌زمینه سفیدیک دکمه آیکون با پس زمینه سفیدیک دکمه شخصی‌سازی‌شده با پس‌زمینه سفید
قالب دکمه استاندارد.
filled_blue
یک دکمه استاندارد با پس‌زمینه آبییک دکمه آیکون با پس زمینه آبییک دکمه شخصی‌سازی‌شده با پس‌زمینه آبی
تم دکمه‌های آبی رنگ.
filled_black
یک دکمه استاندارد با پس‌زمینه مشکییک دکمه آیکون با پس زمینه سیاهیک دکمه شخصی‌سازی‌شده با پس‌زمینه مشکی
تم دکمه‌های مشکی.

اندازه داده

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

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

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

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

متن داده

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

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

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

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

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

شکل داده

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

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

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

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

ترازبندی-logo_data

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

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

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

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

عرض داده

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

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

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

داده-محلی

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

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

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

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

شنونده-کلیک-داده

شما می‌توانید با استفاده از ویژگی 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>

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

حالت داده

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

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

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

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

نقاط پایانی سمت سرور شما باید درخواست‌های HTTP 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>

درخواست HTTP POST شامل اطلاعات زیر است:

قالب نام توضیحات
کوکی g_csrf_token یک رشته تصادفی که با هر درخواست به نقطه پایانی ورود مشخص شده توسط data-login_uri تغییر می‌کند، باید با مقدار موجود در پارامتر درخواست g_csrf_token مطابقت داشته باشد.
پارامتر درخواست g_csrf_token یک رشته تصادفی که با هر درخواست به نقطه پایانی ورود مشخص شده توسط data-login_uri تغییر می‌کند، باید با مقدار کوکی g_csrf_token مطابقت داشته باشد.
پارامتر درخواست credential توکن JWT ID کدگذاری شده‌ای که گوگل صادر می‌کند.
پارامتر درخواست select_by نحوه ورود کاربر.
پارامتر درخواست state این پارامتر فقط زمانی تعریف می‌شود که کاربر روی دکمه‌ی «ورود با گوگل» کلیک کند تا وارد سیستم شود و ویژگی 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 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": "Eliza",
  "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"
}

مشتریان باید ادعاهای JWT ناشناخته را نادیده بگیرند.

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

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

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

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

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

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

g_csrf_token

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

انتخاب_توسط

جدول زیر مقادیر ممکن برای فیلد 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 کاربری که رضایت نداده بود، دکمه ورود با گوگل را فشار داد و دکمه «ادامه» را برای دادن رضایت و اشتراک‌گذاری اطلاعات کاربری فشار داد.

ایالت

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

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

نقطه پایانی کنترل‌کننده اعتبارنامه رمز عبور

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

درخواست HTTP POST شامل اطلاعات زیر است:

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