Tài liệu tham khảo API về tính năng Đăng nhập bằng Google HTML API

Trang tham chiếu này mô tả API thuộc tính dữ liệu HTML Đăng nhập bằng Google. Bạn có thể dùng API này để hiển thị lời nhắc Một lần nhấn hoặc nút Đăng nhập bằng Google trên các trang web của mình.

Phần tử có giá trị nhận dạng "g_id_onload"

Bạn có thể đặt các thuộc tính dữ liệu Đăng nhập bằng Google trong mọi phần tử hiển thị hoặc không hiển thị, chẳng hạn như <div><span>. Yêu cầu duy nhất là bạn phải đặt mã nhận dạng phần tử thành g_id_onload. Đừng đặt mã nhận dạng này trên nhiều phần tử.

Thuộc tính dữ liệu

Bảng sau đây liệt kê các thuộc tính dữ liệu cùng với nội dung mô tả:

Thuộc tính
data-client_id Mã ứng dụng khách của ứng dụng
data-auto_prompt Hiển thị thao tác nhấn vào Google One.
data-auto_select Cho phép tự động chọn trên Google One Tap.
data-login_uri URL của điểm cuối đăng nhập
data-callback Tên hàm trình xử lý mã thông báo nhận dạng JavaScript
data-native_login_uri URL của điểm cuối trình xử lý thông tin đăng nhập bằng mật khẩu
data-native_callback Tên hàm trình xử lý thông tin đăng nhập mật khẩu JavaScript
data-native_id_param Tên tham số cho giá trị credential.id
data-native_password_param Tên tham số cho giá trị credential.password
data-cancel_on_tap_outside Kiểm soát việc có huỷ lời nhắc hay không nếu người dùng nhấp vào bên ngoài lời nhắc.
data-prompt_parent_id Mã nhận dạng DOM của phần tử vùng chứa lời nhắc One Tap
data-skip_prompt_cookie Bỏ qua tính năng Đăng nhập bằng một lần nhấn nếu cookie được chỉ định có giá trị không trống.
data-nonce Một chuỗi ngẫu nhiên cho mã nhận dạng
data-context Tiêu đề và các từ trong lời nhắc Đăng nhập bằng một lần chạm
data-moment_callback Tên hàm của trình nghe thông báo trạng thái giao diện người dùng của lời nhắc
data-state_cookie_domain Nếu bạn cần gọi One Tap trong miền chính và các miền phụ của miền đó, hãy truyền miền chính đến thuộc tính này để sử dụng một cookie dùng chung duy nhất.
data-ux_mode Quy trình trải nghiệm người dùng của nút Đăng nhập bằng Google
data-allowed_parent_origin Các nguồn gốc được phép nhúng iframe trung gian. Tính năng Đăng nhập bằng một lần nhấn sẽ chạy ở chế độ iframe trung gian nếu thuộc tính này xuất hiện.
data-intermediate_iframe_close_callback Ghi đè hành vi mặc định của iframe trung gian khi người dùng đóng One Tap theo cách thủ công.
data-itp_support Bật UX Một lần chạm đã nâng cấp trên các trình duyệt ITP.
data-login_hint Bỏ qua bước chọn tài khoản bằng cách cung cấp gợi ý cho người dùng.
data-hd Giới hạn lựa chọn tài khoản theo miền.
data-use_fedcm_for_prompt Cho phép trình duyệt kiểm soát lời nhắc đăng nhập của người dùng và điều phối quy trình đăng nhập giữa trang web của bạn và Google.
data-use_fedcm_for_button Trường này xác định xem có nên sử dụng UX nút FedCM trên Chrome hay không (máy tính M125 trở lên và Android M128 trở lên). Giá trị mặc định là false.
data-button_auto_select Có bật lựa chọn tự động chọn cho quy trình nút FedCM hay không. Nếu được bật, những người dùng cũ có phiên hoạt động đang diễn ra trên Google sẽ tự động đăng nhập mà không cần phải thấy lời nhắc Bộ chọn tài khoản. Giá trị mặc định là false.

Các loại thuộc tính

Các phần sau đây chứa thông tin chi tiết về loại của từng thuộc tính và một ví dụ.

data-client_id

Thuộc tính này là mã ứng dụng khách của ứng dụng, được tìm thấy và tạo trong Google Cloud Console. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

Thuộc tính này xác định xem có hiển thị tính năng Đăng nhập một lần hay không. Giá trị mặc định là true. Tính năng Đăng nhập bằng một lần nhấn của Google sẽ không xuất hiện khi giá trị này là false. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-auto_prompt="true"

data-auto_select

Thuộc tính này xác định có trả về mã nhận dạng tự động hay không, mà không cần bất kỳ hoạt động tương tác nào của người dùng, nếu chỉ có một phiên Google đã phê duyệt ứng dụng của bạn. Giá trị mặc định là false. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-auto_select="true"

data-login_uri

Thuộc tính này là URI của điểm cuối đăng nhập.

Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong Nền tảng xác thực của Google và phải tuân thủ các quy tắc xác thực URI chuyển hướng của chúng tôi.

Bạn có thể bỏ qua thuộc tính này nếu trang hiện tại là trang đăng nhập của bạn. Trong trường hợp đó, thông tin đăng nhập sẽ được đăng lên trang này theo mặc định.

Phản hồi thông tin xác thực mã thông báo nhận dạng được đăng lên điểm cuối đăng nhập của bạn khi không có hàm gọi lại nào được xác định và người dùng nhấp vào nút Đăng nhập bằng Google hoặc Đăng nhập bằng một lần chạm, hoặc khi quá trình đăng nhập tự động diễn ra.

Điểm cuối đăng nhập của bạn phải xử lý các yêu cầu POST có chứa tham số credential với giá trị mã thông báo nhận dạng trong phần nội dung.

Hãy xem bảng sau để biết thêm thông tin:

Loại Không bắt buộc Ví dụ:
URL Giá trị mặc định là URI của trang hiện tại hoặc giá trị mà bạn chỉ định.
Bị bỏ qua khi bạn đặt data-ux_mode="popup"data-callback.
data-login_uri="https://www.example.com/login"

data-callback

Thuộc tính này là tên của hàm JavaScript xử lý mã thông báo nhận dạng được trả về. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Bắt buộc nếu bạn chưa đặt data-login_uri. data-callback="handleToken"

Bạn có thể dùng một trong các thuộc tính data-login_uridata-callback. Điều này phụ thuộc vào các cấu hình thành phần và chế độ trải nghiệm người dùng sau đây:

  • Thuộc tính data-login_uri là bắt buộc đối với chế độ UX của nút Đăng nhập bằng Google redirect, chế độ này bỏ qua thuộc tính data-callback.

  • Bạn phải đặt một trong hai thuộc tính này cho chế độ trải nghiệm người dùng popup của nút Đăng nhập bằng Google và tính năng Đăng nhập bằng một lần chạm của Google. Nếu bạn đặt cả hai, thì thuộc tính data-callback sẽ có mức độ ưu tiên cao hơn.

API HTML không hỗ trợ các hàm JavaScript trong một không gian tên. Thay vào đó, hãy sử dụng một hàm JavaScript toàn cục mà không có không gian tên. Ví dụ: sử dụng mylibCallback thay vì mylib.callback.

data-native_login_uri

Thuộc tính này là URL của điểm cuối trình xử lý thông tin đăng nhập bằng mật khẩu. Nếu bạn đặt thuộc tính data-native_login_uri hoặc thuộc tính data-native_callback, thì thư viện JavaScript sẽ quay lại trình quản lý thông tin đăng nhập tích hợp khi không có phiên hoạt động trên Google. Bạn không được phép đặt cả hai thuộc tính data-native_callbackdata-native_login_uri. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-login_uri="https://www.example.com/password_login"

data-native_callback

Thuộc tính này là tên của hàm JavaScript xử lý thông tin đăng nhập mật khẩu do trình quản lý thông tin đăng nhập tích hợp của trình duyệt trả về. Nếu bạn đặt thuộc tính data-native_login_uri hoặc thuộc tính data-native_callback, thư viện JavaScript sẽ quay lại trình quản lý thông tin đăng nhập tích hợp khi không có phiên hoạt động trên Google. Bạn không được phép đặt cả data-native_callbackdata-native_login_uri. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-native_callback="handlePasswordCredential"

API HTML không hỗ trợ các hàm JavaScript trong một không gian tên. Thay vào đó, hãy sử dụng một hàm JavaScript toàn cục mà không có không gian tên. Ví dụ: sử dụng mylibCallback thay vì mylib.callback.

data-native_id_param

Khi gửi thông tin đăng nhập bằng mật khẩu đến điểm cuối của trình xử lý thông tin đăng nhập bằng mật khẩu, bạn có thể chỉ định tên tham số cho trường credential.id. Tên mặc định là email. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
URL Không bắt buộc data-native_id_param="user_id"

data-native_password_param

Khi gửi thông tin đăng nhập bằng mật khẩu đến điểm cuối của trình xử lý thông tin đăng nhập bằng mật khẩu, bạn có thể chỉ định tên tham số cho giá trị credential.password. Tên mặc định là password. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
URL Không bắt buộc data-native_password_param="pwd"

data-cancel_on_tap_outside

Thuộc tính này đặt xem có huỷ yêu cầu Đăng nhập bằng một lần nhấn hay không nếu người dùng nhấp vào bên ngoài lời nhắc. Giá trị mặc định là true. Để tắt, hãy đặt giá trị thành false. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-cancel_on_tap_outside="false"

data-prompt_parent_id

Thuộc tính này đặt mã nhận dạng DOM của phần tử vùng chứa. Nếu bạn chưa đặt, lời nhắc Đăng nhập bằng một lần nhấn sẽ xuất hiện ở góc trên cùng bên phải của cửa sổ. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-prompt_parent_id="parent_id"

Sử dụng cookie để kiểm soát việc hiển thị lời nhắc Đăng nhập bằng một lần nhấn. Nếu cookie do thuộc tính này chỉ định có giá trị không trống, thì lời nhắc sẽ không xuất hiện. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-skip_prompt_cookie="SID"

data-nonce

Thuộc tính này là một chuỗi ngẫu nhiên được mã thông báo nhận dạng dùng để ngăn chặn các cuộc tấn công phát lại. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-nonce="biaqbm70g23"

Độ dài của số chỉ dùng một lần bị giới hạn ở kích thước JWT tối đa mà môi trường của bạn hỗ trợ, cũng như các hạn chế về kích thước HTTP của từng trình duyệt và máy chủ.

data-context

Trường này thay đổi văn bản của tiêu đề và thông báo xuất hiện trong lời nhắc Đăng nhập bằng một lần nhấn, không ảnh hưởng đến các trình duyệt ITP. Giá trị mặc định là signin.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-context="use"

Bảng sau đây liệt kê tất cả các bối cảnh có sẵn và nội dung mô tả của chúng:

Ngữ cảnh
signin "Đăng nhập vào"
signup "Đăng ký"
use "Sử dụng"

data-moment_callback

Thuộc tính này là tên hàm của trình nghe thông báo trạng thái giao diện người dùng lời nhắc. Để biết thêm thông tin, hãy tham khảo kiểu dữ liệu PromptMomentNotification.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-moment_callback="logMomentNotification"

API HTML không hỗ trợ các hàm JavaScript trong một không gian tên. Thay vào đó, hãy sử dụng một hàm JavaScript toàn cục mà không có không gian tên. Ví dụ: sử dụng mylibCallback thay vì mylib.callback.

Nếu bạn cần hiển thị tính năng Đăng nhập một lần trong một miền chính và các miền con của miền đó, hãy truyền miền chính vào thuộc tính này để sử dụng một cookie trạng thái dùng chung duy nhất. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-state_cookie_domain="example.com"

data-ux_mode

Thuộc tính này đặt quy trình trải nghiệm người dùng mà nút Đăng nhập bằng Google sử dụng. Giá trị mặc định là popup. Thuộc tính này không ảnh hưởng đến trải nghiệm người dùng của tính năng Đăng nhập bằng một lần nhấn. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-ux_mode="redirect"

Bảng sau đây liệt kê các chế độ trải nghiệm người dùng hiện có và nội dung mô tả của các chế độ đó.

Chế độ UX
popup Thực hiện quy trình trải nghiệm người dùng đăng nhập trong một cửa sổ bật lên.
redirect Thực hiện quy trình trải nghiệm người dùng đăng nhập bằng cách chuyển hướng toàn bộ trang.

data-allowed_parent_origin

Các nguồn gốc được phép nhúng iframe trung gian. One Tap sẽ chạy ở chế độ iframe trung gian nếu thuộc tính này xuất hiện. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi hoặc mảng chuỗi Không bắt buộc data-allowed_parent_origin="https://example.com"

Bảng sau đây liệt kê các loại giá trị được hỗ trợ và nội dung mô tả của các loại giá trị đó.

Loại giá trị
string Một URI miền duy nhất. "https://example.com"
string array Danh sách các URI miền được phân tách bằng dấu phẩy. "https://news.example.com,https://local.example.com"

Nếu giá trị của thuộc tính data-allowed_parent_origin không hợp lệ, thì quá trình khởi chạy One Tap ở chế độ iframe trung gian sẽ không thành công và dừng lại.

Tiền tố có ký tự đại diện cũng được hỗ trợ. Ví dụ: "https://*.example.com" khớp với example.com và các miền con của miền này ở mọi cấp (ví dụ: news.example.com, login.news.example.com). Những điều cần lưu ý khi sử dụng ký tự đại diện:

  • Chuỗi mẫu không được chỉ bao gồm một ký tự đại diện và một miền cấp cao nhất. Ví dụ: https://.comhttps://.co.uk không hợp lệ vì "https://.example.com" khớp với example.com và tất cả các miền phụ của miền đó. Sử dụng danh sách được phân tách bằng dấu phẩy để biểu thị 2 miền khác nhau. Ví dụ: "https://example1.com,https://.example2.com" khớp với các miền example1.com, example2.com và các miền con của example2.com
  • Các miền ký tự đại diện phải bắt đầu bằng một giao thức https:// an toàn, vì vậy "*.example.com" được coi là không hợp lệ.

data-intermediate_iframe_close_callback

Ghi đè hành vi mặc định của iframe trung gian khi người dùng đóng One Tap theo cách thủ công bằng cách nhấn vào nút "X" trong giao diện người dùng One Tap. Hành vi mặc định là xoá ngay iframe trung gian khỏi DOM.

Trường data-intermediate_iframe_close_callback chỉ có hiệu lực ở chế độ iframe trung gian. Và nó chỉ ảnh hưởng đến iframe trung gian, thay vì iframe Đăng nhập bằng một lần nhấn. Giao diện người dùng One Tap sẽ bị xoá trước khi lệnh gọi lại được gọi.

Loại Bắt buộc Ví dụ:
hàm Không bắt buộc data-intermediate_iframe_close_callback="logBeforeClose"

API HTML không hỗ trợ các hàm JavaScript trong một không gian tên. Thay vào đó, hãy sử dụng một hàm JavaScript toàn cục mà không có không gian tên. Ví dụ: sử dụng mylibCallback thay vì mylib.callback.

data-itp_support

Trường này xác định xem có nên bật UX Một lần nhấn đã nâng cấp trên các trình duyệt hỗ trợ tính năng Ngăn chặn theo dõi thông minh (ITP) hay không. Giá trị mặc định là false. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-itp_support="true"

data-login_hint

Nếu biết trước người dùng nào sẽ đăng nhập, ứng dụng của bạn có thể cung cấp một gợi ý đăng nhập cho Google. Nếu thành công, bước chọn tài khoản sẽ được bỏ qua. Các giá trị được chấp nhận là: địa chỉ email hoặc mã thông báo nhận dạng trường sub.

Để biết thêm thông tin, hãy xem tài liệu về OpenID Connect cho login_hint.

Loại Bắt buộc Ví dụ:
Chuỗi. Có thể là địa chỉ email hoặc giá trị trường sub trong mã thông báo nhận dạng. Không bắt buộc data-login_hint="elisa.beckett@gmail.com"

data-hd

Khi người dùng có nhiều tài khoản và chỉ nên đăng nhập bằng tài khoản Workspace, hãy dùng tham số này để cung cấp gợi ý về tên miền cho Google. Khi thành công, các tài khoản người dùng xuất hiện trong quá trình chọn tài khoản sẽ bị giới hạn trong miền được cung cấp. Giá trị ký tự đại diện: * chỉ cung cấp tài khoản Workspace cho người dùng và loại trừ tài khoản người tiêu dùng (user@gmail.com) trong quá trình chọn tài khoản.

Để biết thêm thông tin, hãy xem tài liệu về OpenID Connect cho hd.

Loại Bắt buộc Ví dụ:
Chuỗi. Tên miền đủ điều kiện hoặc *. Không bắt buộc data-hd="*"

data-use_fedcm_for_prompt

Cho phép trình duyệt kiểm soát lời nhắc đăng nhập của người dùng và điều phối quy trình đăng nhập giữa trang web của bạn và Google. Giá trị mặc định là false. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-use_fedcm_for_prompt="true"

data-use_fedcm_for_button

Trường này xác định xem có nên sử dụng UX nút FedCM trên Chrome (máy tính M125 trở lên và Android M128 trở lên) hay không. Giá trị mặc định là false. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-use_fedcm_for_button="true"

data-button_auto_select

Trường này xác định có bật lựa chọn tự động chọn cho quy trình nút FedCM hay không. Nếu được bật, những người dùng cũ có phiên hoạt động trên Google sẽ tự động đăng nhập mà không cần phải chọn tài khoản. Giá trị mặc định là false. Bạn cần bật rõ ràng tính năng tự động đăng nhập bằng nút trong quá trình khởi chạy chọn sử dụng. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
boolean Không bắt buộc data-button_auto_select="true"

Phần tử có lớp "g_id_signin"

Nếu bạn thêm g_id_signin vào thuộc tính class của một phần tử, phần tử đó sẽ hiển thị dưới dạng nút Đăng nhập bằng Google.

Bạn có thể hiển thị nhiều nút Đăng nhập bằng Google trên cùng một trang. Mỗi nút có thể có chế độ cài đặt hình ảnh riêng. Các chế độ cài đặt được xác định bằng các thuộc tính dữ liệu sau.

Thuộc tính dữ liệu trực quan

Bảng sau đây liệt kê các thuộc tính dữ liệu trực quan và nội dung mô tả của các thuộc tính đó:

Thuộc tính
data-type Loại nút: biểu tượng hoặc nút tiêu chuẩn.
data-theme Giao diện nút. Ví dụ: filled_blue hoặc filled_black.
data-size Kích thước nút. Ví dụ: nhỏ hoặc lớn.
data-text Văn bản trên nút. Ví dụ: "Đăng nhập bằng Google" hoặc "Đăng ký bằng Google".
data-shape Hình dạng nút. Ví dụ: hình chữ nhật hoặc hình tròn.
data-logo_alignment Vị trí căn chỉnh biểu trưng của Google: bên trái hoặc ở giữa.
data-width Chiều rộng của nút, tính bằng pixel.
data-locale Văn bản trên nút sẽ hiển thị bằng ngôn ngữ được đặt trong thuộc tính này.
data-click_listener Nếu được đặt, hàm này sẽ được gọi khi người dùng nhấp vào nút Đăng nhập bằng Google.
data-state Nếu được đặt, chuỗi này sẽ trả về cùng với mã thông báo nhận dạng.

Các loại thuộc tính

Các phần sau đây chứa thông tin chi tiết về loại của từng thuộc tính và một ví dụ.

data-type

Loại nút. Giá trị mặc định là standard. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi data-type="icon"

Bảng sau đây liệt kê tất cả các loại nút hiện có và nội dung mô tả của từng loại:

Loại
standard
Một nút có văn bản hoặc thông tin được cá nhân hoá.
icon
Một nút dạng biểu tượng không có văn bản.

data-theme

Giao diện nút. Giá trị mặc định là outline. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-theme="filled_blue"

Bảng sau đây liệt kê các giao diện hiện có và nội dung mô tả của từng giao diện:

Chủ đề
outline
Một nút tiêu chuẩn có nền màu trắng Nút biểu tượng có nền màu trắng Một nút được cá nhân hoá có nền màu trắng
Giao diện nút tiêu chuẩn.
filled_blue
Một nút tiêu chuẩn có nền màu xanh dương Nút biểu tượng có nền màu xanh dương Một nút được cá nhân hoá có nền màu xanh dương
Giao diện nút có màu xanh dương.
filled_black
Một nút tiêu chuẩn có nền màu đen Nút biểu tượng có nền màu đen Một nút được cá nhân hoá có nền màu đen
Giao diện nút có màu đen.

data-size

Kích thước nút. Giá trị mặc định là large. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-size="small"

Bảng sau đây liệt kê các kích thước nút hiện có và nội dung mô tả của từng kích thước.

Kích thước
large
Một nút tiêu chuẩn lớn Nút biểu tượng lớn Một nút lớn, được cá nhân hoá
Một nút lớn.
medium
Nút tiêu chuẩn cỡ trung Nút biểu tượng cỡ trung bình
Một nút có kích thước trung bình.
small
Nút đăng nhập nhỏ Nút biểu tượng nhỏ
Một nút nhỏ.

data-text

Văn bản trên nút. Giá trị mặc định là signin_with. Không có sự khác biệt về hình ảnh đối với văn bản của các nút biểu tượng có thuộc tính data-text khác nhau. Trường hợp ngoại lệ duy nhất là khi văn bản được đọc để hỗ trợ tiếp cận màn hình.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-text="signup_with"

Bảng sau đây liệt kê các văn bản nút hiện có và nội dung mô tả của chúng:

Văn bản
signin_with
Một nút tiêu chuẩn có nhãn &quot;Đăng nhập bằng Google&quot; Một nút biểu tượng không có văn bản hiển thị
Văn bản trên nút là "Đăng nhập bằng Google".
signup_with
Một nút tiêu chuẩn có nhãn &quot;Đăng ký bằng Google&quot; Một nút biểu tượng không có văn bản hiển thị
Văn bản trên nút là "Đăng ký bằng Google".
continue_with
Một nút chuẩn có nhãn &quot;Tiếp tục bằng Google&quot; Một nút biểu tượng không có văn bản hiển thị
Văn bản trên nút là "Tiếp tục bằng Google".
signin
Một nút tiêu chuẩn có nhãn &quot;Đăng nhập&quot; Một nút biểu tượng không có văn bản hiển thị
Văn bản trên nút là "Đăng nhập".

data-shape

Hình dạng nút. Giá trị mặc định là rectangular. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-shape="rectangular"

Bảng sau đây liệt kê các hình dạng nút hiện có và nội dung mô tả của chúng:

Hình dạng
rectangular
Nút tiêu chuẩn hình chữ nhật Nút biểu tượng hình chữ nhật Một nút cá nhân hoá hình chữ nhật
Nút có hình chữ nhật. Nếu được dùng cho loại nút icon, thì thuộc tính này giống như square.
pill
Nút tiêu chuẩn có hình viên thuốc Nút biểu tượng có hình viên thuốc Nút được cá nhân hoá có hình viên thuốc
Nút có hình viên thuốc. Nếu được dùng cho loại nút icon, thì giá trị này giống như circle.
circle
Nút tiêu chuẩn hình tròn Nút biểu tượng hình tròn Nút cá nhân hoá hình tròn
Nút có hình tròn. Nếu được dùng cho loại nút standard, thì thuộc tính này giống như pill.
square
Nút tiêu chuẩn hình vuông Nút biểu tượng hình vuông Nút hình vuông được cá nhân hoá
Nút có hình vuông. Nếu được dùng cho loại nút standard, thì thuộc tính này giống như rectangular.

data-logo_alignment

Vị trí căn chỉnh của biểu trưng Google. Giá trị mặc định là left. Thuộc tính này chỉ áp dụng cho loại nút standard. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-logo_alignment="center"

Bảng sau đây liệt kê các chế độ căn chỉnh hiện có và nội dung mô tả của từng chế độ:

logo_alignment
left
Một nút tiêu chuẩn có biểu trưng G ở bên trái
Căn trái biểu trưng của Google.
center
Một nút tiêu chuẩn có biểu trưng chữ G ở chính giữa
Căn giữa biểu trưng của Google.

data-width

Chiều rộng tối thiểu của nút, tính bằng pixel. Chiều rộng tối đa có thể sử dụng là 400 pixel.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-width=400

data-locale

Không bắt buộc. Hiển thị văn bản nút bằng ngôn ngữ đã chỉ định, nếu không, hệ thống sẽ mặc định sử dụng Tài khoản Google hoặc chế độ cài đặt trình duyệt của người dùng. Thêm tham số hl và mã ngôn ngữ vào chỉ thị src khi tải thư viện, ví dụ: gsi/client?hl=<iso-639-code>.

Nếu bạn không đặt giá trị này, thì hệ thống sẽ sử dụng ngôn ngữ mặc định của trình duyệt hoặc lựa chọn ưu tiên của người dùng trong phiên Google. Do đó, mỗi người dùng có thể thấy các phiên bản nút đã bản địa hoá khác nhau, và có thể có kích thước khác nhau.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-locale="zh_CN"

data-click_listener

Bạn có thể xác định một hàm JavaScript sẽ được gọi khi người dùng nhấp vào nút Đăng nhập bằng Google bằng cách sử dụng thuộc tính 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>

Trong ví dụ này, thông báo Sign in with Google button clicked... sẽ được ghi vào bảng điều khiển khi người dùng nhấp vào nút Đăng nhập bằng Google.

data-state

Không bắt buộc, vì bạn có thể hiển thị nhiều nút Đăng nhập bằng Google trên cùng một trang, nên bạn có thể chỉ định cho mỗi nút một chuỗi riêng biệt. Cùng một chuỗi sẽ trả về cùng với mã thông báo nhận dạng, vì vậy, bạn có thể xác định người dùng đã nhấp vào nút nào để đăng nhập.

Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
chuỗi Không bắt buộc data-state="button 1"

Tích hợp phía máy chủ

Các điểm cuối phía máy chủ phải xử lý các yêu cầu HTTP POST sau đây.

Điểm cuối trình xử lý mã thông báo nhận dạng

Điểm cuối của trình xử lý mã thông báo nhận dạng sẽ xử lý mã thông báo nhận dạng. Dựa trên trạng thái của tài khoản tương ứng, bạn có thể đăng nhập cho người dùng và chuyển họ đến trang đăng ký hoặc trang liên kết tài khoản để biết thêm thông tin.

Ví dụ về yêu cầu đến điểm cuối đăng nhập của bạn:

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>

Yêu cầu HTTP POST chứa các thông tin sau:

Định dạng Tên Mô tả
Cookie g_csrf_token Một chuỗi ngẫu nhiên thay đổi theo từng yêu cầu đến điểm cuối đăng nhập do data-login_uri chỉ định, phải khớp với giá trị trong tham số yêu cầu g_csrf_token.
Tham số yêu cầu g_csrf_token Một chuỗi ngẫu nhiên thay đổi theo từng yêu cầu đến điểm cuối đăng nhập do data-login_uri chỉ định, phải khớp với giá trị của cookie g_csrf_token.
Tham số yêu cầu credential Mã thông báo JWT ID được mã hoá mà Google phát hành.
Tham số yêu cầu select_by Cách người dùng đăng nhập.
Tham số yêu cầu state Tham số này chỉ được xác định khi người dùng nhấp vào nút Đăng nhập bằng Google để đăng nhập và thuộc tính state của nút được chỉ định.

giấy chứng nhận

Khi được giải mã, mã nhận dạng sẽ có dạng như ví dụ sau:

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"
}

Trường sub là giá trị nhận dạng duy nhất trên toàn cầu cho Tài khoản Google. Chỉ sử dụng trường sub làm giá trị nhận dạng cho người dùng vì trường này là duy nhất trong tất cả Tài khoản Google và không bao giờ được dùng lại.

Bằng cách sử dụng các trường email, email_verifiedhd, bạn có thể xác định xem Google có lưu trữ và có quyền đối với một địa chỉ email hay không. Trong trường hợp Google là nguồn đáng tin cậy, người dùng được xác nhận là chủ sở hữu hợp pháp của tài khoản.

Các trường hợp Google là nguồn thông tin xác thực:

  • email có hậu tố @gmail.com, đây là tài khoản Gmail.
  • email_verified là true và hd được đặt, đây là tài khoản Google Workspace.

Người dùng có thể đăng ký Tài khoản Google mà không cần sử dụng Gmail hoặc Google Workspace. Khi email không chứa hậu tố @gmail.comhd không có, Google không phải là nguồn đáng tin cậy và bạn nên dùng mật khẩu hoặc các phương thức xác thực khác để xác minh người dùng. email_verified cũng có thể đúng vì ban đầu Google đã xác minh người dùng khi Tài khoản Google được tạo, tuy nhiên, quyền sở hữu tài khoản email bên thứ ba có thể đã thay đổi kể từ đó.

Trường exp cho biết thời gian hết hạn để bạn xác minh mã thông báo ở phía máy chủ. Thời gian này là 1 giờ đối với mã thông báo nhận dạng thu được từ tính năng Đăng nhập bằng Google. Bạn cần xác minh mã thông báo trước khi hết thời gian hiệu lực. Đừng dùng exp để quản lý phiên. Mã thông báo nhận dạng đã hết hạn không có nghĩa là người dùng đã đăng xuất. Ứng dụng của bạn chịu trách nhiệm quản lý phiên của người dùng.

g_csrf_token

Mã thông báo trạng thái chống giả mạo. Đây là mã thông báo Giả mạo yêu cầu trên nhiều trang web (CSRF) do thư viện gsi/client tạo. Một giá trị ngẫu nhiên được đưa vào cả dưới dạng Cookie và Tham số yêu cầu trong phần nội dung hữu ích của yêu cầu POST. Nếu hai giá trị này không khớp khi xử lý yêu cầu trên máy chủ của bạn, thì yêu cầu đó sẽ được coi là không hợp lệ.

select_by

Bảng sau đây liệt kê các giá trị có thể có cho trường select_by. Loại nút được dùng cùng với trạng thái phiên và trạng thái đồng ý được dùng để đặt giá trị,

  • Người dùng đã nhấn nút Một lần chạm hoặc Đăng nhập bằng Google hoặc sử dụng quy trình Tự động đăng nhập không cần chạm.

  • Hệ thống tìm thấy một phiên hiện có hoặc người dùng đã chọn và đăng nhập vào một Tài khoản Google để thiết lập một phiên mới.

  • Trước khi chia sẻ thông tin đăng nhập mã thông báo nhận dạng với ứng dụng của bạn, người dùng có thể

    • nhấn nút Xác nhận để đồng ý chia sẻ thông tin đăng nhập, hoặc
    • trước đây đã đồng ý và sử dụng tính năng Chọn một tài khoản để chọn một Tài khoản Google.

Giá trị của trường này được đặt thành một trong các loại sau,

Giá trị Mô tả
auto Tự động đăng nhập người dùng có phiên hiện tại và trước đó đã đồng ý chia sẻ thông tin đăng nhập. Chỉ áp dụng cho các trình duyệt không hỗ trợ FedCM.
user Một người dùng có phiên hiện tại đã từng đồng ý nhấn nút "Tiếp tục với" của tính năng Đăng nhập một lần để chia sẻ thông tin đăng nhập. Chỉ áp dụng cho các trình duyệt không hỗ trợ FedCM.
fedcm Người dùng nhấn vào nút "Tiếp tục với" của tính năng Đăng nhập bằng một lần nhấn để chia sẻ thông tin xác thực bằng FedCM. Chỉ áp dụng cho các trình duyệt hỗ trợ FedCM.
fedcm_auto Tự động đăng nhập người dùng có phiên hiện tại và trước đó đã đồng ý chia sẻ thông tin đăng nhập bằng FedCM One Tap. Chỉ áp dụng cho các trình duyệt hỗ trợ FedCM.
user_1tap Một người dùng có phiên hiện tại đã nhấn vào nút "Tiếp tục với" của tính năng Đăng nhập một lần để đồng ý và chia sẻ thông tin đăng nhập. Chỉ áp dụng cho Chrome phiên bản 75 trở lên.
user_2tap Một người dùng không có phiên hiện tại đã nhấn vào nút "Tiếp tục với" của tính năng Đăng nhập một lần để chọn một tài khoản, sau đó nhấn vào nút Xác nhận trong cửa sổ bật lên để đồng ý và chia sẻ thông tin đăng nhập. Áp dụng cho các trình duyệt không dựa trên Chromium.
btn Một người dùng có phiên hiện tại đã đồng ý trước đó nhấn vào nút Đăng nhập bằng Google và chọn một Tài khoản Google trong phần "Chọn tài khoản" để chia sẻ thông tin đăng nhập.
btn_confirm Một người dùng có phiên hiện tại đã nhấn vào nút Đăng nhập bằng Google và nhấn vào nút Xác nhận để đồng ý và chia sẻ thông tin đăng nhập.
btn_add_session Người dùng chưa có phiên hiện tại và trước đó đã đồng ý nhấn vào nút Đăng nhập bằng Google để chọn một Tài khoản Google và chia sẻ thông tin đăng nhập.
btn_confirm_add_session Người dùng chưa có phiên hiện tại trước tiên nhấn nút Đăng nhập bằng Google để chọn một Tài khoản Google, sau đó nhấn nút Xác nhận để đồng ý và chia sẻ thông tin đăng nhập.

tiểu bang

Tham số này chỉ được xác định khi người dùng nhấp vào nút Đăng nhập bằng Google để đăng nhập và thuộc tính data-state của nút đã nhấp được chỉ định. Giá trị của trường này giống với giá trị mà bạn đã chỉ định trong thuộc tính data-state của nút.

Vì nhiều nút Đăng nhập bằng Google có thể được hiển thị trên cùng một trang, nên bạn có thể chỉ định cho mỗi nút một chuỗi duy nhất. Do đó, bạn có thể dùng tham số state này để xác định nút mà người dùng đã nhấp vào để đăng nhập.

Điểm cuối của trình xử lý thông tin xác thực mật khẩu

Điểm cuối trình xử lý thông tin xác thực mật khẩu sẽ xử lý thông tin xác thực mật khẩu mà trình quản lý thông tin xác thực tích hợp truy xuất.

Yêu cầu HTTP POST chứa các thông tin sau:

Định dạng Tên Mô tả
Cookie g_csrf_token Một chuỗi ngẫu nhiên thay đổi theo từng yêu cầu đến điểm cuối đăng nhập do data-native_login_uri chỉ định, phải khớp với giá trị trong tham số yêu cầu g_csrf_token.
Tham số yêu cầu g_csrf_token Một chuỗi ngẫu nhiên thay đổi theo từng yêu cầu đến điểm cuối đăng nhập do data-native_login_uri chỉ định, phải khớp với giá trị của cookie g_csrf_token.
Tham số yêu cầu email Mã thông báo nhận dạng này do Google phát hành.
Tham số yêu cầu password Cách chọn thông tin đăng nhập.