Tài liệu tham khảo API JavaScript của Google Đăng nhập bằng Google

Trang tham khảo này mô tả API JavaScript đăng nhập. Bạn có thể sử dụng API này để hiển thị lời nhắc Một lần chạm hoặc nút Đăng nhập bằng Google trên các trang web của mình.

Phương thức: google.accounts.id.initialize

Phương thức google.accounts.id.initialize khởi chạy ứng dụng Đăng nhập bằng Google dựa trên đối tượng cấu hình. Hãy xem mã ví dụ sau đây của phương thức này:

google.accounts.id.initialize(IdConfiguration)

Ví dụ về mã sau đây triển khai phương thức google.accounts.id.initialize bằng hàm onload:

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

Phương thức google.accounts.id.initialize tạo một thực thể ứng dụng Đăng nhập bằng Google mà tất cả các mô-đun trên cùng một trang web đều có thể sử dụng ngầm.

  • Bạn chỉ cần gọi phương thức google.accounts.id.initialize một lần ngay cả khi sử dụng nhiều mô-đun (như Một lần nhấn, Nút cá nhân hoá, thu hồi, v.v.) trong cùng một trang web.
  • Nếu bạn gọi phương thức google.accounts.id.initialize nhiều lần, chỉ các cấu hình trong lệnh gọi gần đây nhất mới được ghi nhớ và sử dụng.

Bạn sẽ đặt lại các cấu hình mỗi khi gọi phương thức google.accounts.id.initialize và tất cả các phương thức tiếp theo trong cùng một trang web đều sử dụng cấu hình mới ngay lập tức.

Loại dữ liệu: IdConfiguration

Bảng sau đây liệt kê các trường và nội dung mô tả về loại dữ liệu IdConfiguration:

Trường
client_id Mã ứng dụng khách của ứng dụng
auto_select Bật tính năng tự động chọn.
callback Hàm JavaScript xử lý mã thông báo giá trị nhận dạng. Tính năng Chạm vào Google One và nút Đăng nhập bằng Google popup Chế độ trải nghiệm người dùng sử dụng thuộc tính này.
login_uri URL của điểm cuối đăng nhập của bạn. Nút Đăng nhập bằng Google redirect Chế độ trải nghiệm người dùng sử dụng thuộc tính này.
native_callback Hàm JavaScript xử lý thông tin xác thực mật khẩu.
cancel_on_tap_outside Huỷ lời nhắc nếu người dùng nhấp vào bên ngoài lời nhắc.
prompt_parent_id Mã DOM của phần tử vùng chứa lời nhắc Một lần chạm
nonce Chuỗi ngẫu nhiên cho mã thông báo giá trị nhận dạng
context Tiêu đề và từ ngữ trong câu lệnh Một lần chạm
state_cookie_domain Nếu bạn cần gọi một lần chạm trong miền gốc và các miền con của miền đó, hãy chuyển miền gốc đến trường này để sử dụng một cookie dùng chung.
ux_mode Quy trình trải nghiệm người dùng của nút Đăng nhập bằng Google
allowed_parent_origin Các nguồn gốc được phép nhúng iframe trung gian. Tính năng Một lần chạm sẽ chạy ở chế độ iframe trung gian nếu có trường này.
intermediate_iframe_close_callback Ghi đè hành vi của iframe trung gian mặc định khi người dùng đóng tính năng Một lần chạm theo cách thủ công.
itp_support Bật trải nghiệm người dùng một lần chạm đã nâng cấp trên trình duyệt ITP.
login_hint Bỏ qua bước lựa chọn tài khoản bằng cách cung cấp gợi ý cho người dùng.
hd Giới hạn việc lựa chọn tài khoản theo miền.
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à dàn xếp quy trình đăng nhập giữa trang web của bạn và Google.

client_id

Trường này là mã ứng dụng khách của ứng dụng, bạn có thể tìm thấy và tạo mã này trong bảng điều khiển Google Cloud. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
string client_id: "CLIENT_ID.apps.googleusercontent.com"

auto_select

Trường này xác định liệu mã thông báo giá trị nhận dạng có được tự động trả về mà không cần sự tương tác của người dùng hay không khi chỉ có một phiên hoạt động của Google từng phê duyệt ứng dụng của bạn trước đó. 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 auto_select: true

số gọi lại

Trường này là hàm JavaScript xử lý mã thông báo mã nhận dạng được trả về từ lời nhắc Một lần chạm hoặc cửa sổ bật lên. Đây là thuộc tính bắt buộc nếu bạn sử dụng chế độ Trải nghiệm người dùng bằng Google One (một lần chạm hoặc nút Đăng nhập bằng Google) popup. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
hàm Bắt buộc đối với tính năng Một lần chạm và chế độ trải nghiệm người dùng trên popup callback: handleResponse

login_uri

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

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 bảng điều khiển Google Cloud và phải tuân thủ 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 của thông tin xác thực mã thông báo được đăng lên điểm cuối đăng nhập khi người dùng nhấp vào nút Đăng nhập bằng Google và chuyển hướng chế độ trải nghiệm người dùng.

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.
Chỉ được dùng khi bạn đặt ux_mode: "redirect".
login_uri="https://www.example.com/login"

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

Sau đây là yêu cầu mẫu tới điểm cuối đăng nhập của bạn:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

native_callback

Trường này là tên của hàm JavaScript xử lý thông tin xác thực mật khẩu được trả về từ trình quản lý thông tin xác thực gốc của trình duyệt. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
hàm Không bắt buộc native_callback: handleResponse

cancel_on_tap_outside

Trường này đặt xem có huỷ yêu cầu Một lần chạm 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. Bạn có thể tắt chế độ này nếu đặ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 cancel_on_tap_outside: false

prompt_parent_id

Thuộc tính này đặt ID DOM của phần tử vùng chứa. Nếu bạn không đặt chính sách này, thì lời nhắc Một lần chạm sẽ hiển thị ở 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ụ:
string Không bắt buộc prompt_parent_id: 'parent_id'

nonce

Trường này là một chuỗi ngẫu nhiên mà mã thông báo mã 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ụ:
string Không bắt buộc 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 được môi trường của bạn hỗ trợ, cũng như các quy tắc ràng buộc về kích thước HTTP của máy chủ và trình duyệt riêng lẻ.

bối cảnh

Trường này thay đổi văn bản của tiêu đề và thông báo trong lời nhắc Một lần chạm. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
string Không bắt buộc context: "use"

Bảng sau đây liệt kê tất cả các bối cảnh hiện có và nội dung mô tả tương ứng:

Bối cảnh
signin "Đăng nhập bằng Google"
signup "Đăng ký bằng Google"
use "Sử dụng với Google"

Nếu bạn cần hiển thị tính năng Một lần chạm trong miền gốc và các miền con của miền đó, hãy chuyển miền gốc đến trường này để sử dụng một cookie trạng thái chia sẻ. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
string Không bắt buộc state_cookie_domain: "example.com"

ux_mode

Sử dụng trường 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 OneTap. Hãy xem bảng sau để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
string Không bắt buộc 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ả về các chế độ đó.

Chế độ UX
popup Thực hiện quy trình đăng nhập trải nghiệm người dùng trong 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.

allowed_parent_origin

Các nguồn gốc được phép nhúng iframe trung gian. Tính năng Một lần chạm sẽ chạy ở chế độ iframe trung gian nếu có trường này. Hãy xem bảng sau đây để biết thêm thông tin:

Loại Bắt buộc Ví dụ:
mảng chuỗi hoặc chuỗi Không bắt buộc 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ả tương ứng.

Loại giá trị
string Một URI miền. "https://example.com"
string array Một mảng URI miền. ["https://news.example.com", "https://local.example.com"]

Tiền tố 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 thuộc tính 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ệ. Như đã lưu ý ở trên, "https://.example.com" khớp với example.com và các miền con của example.com. Bạn cũng có thể dùng một mảng để đại diện cho 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
  • Miền ký tự đại diện phải bắt đầu bằng một giao thức https:// bảo mật và vì vậy "*.example.com" bị coi là không hợp lệ.

Nếu giá trị của trường allowed_parent_origin không hợp lệ, việc khởi chạy chế độ iframe trung gian bằng một lần chạm sẽ không thành công và dừng lại.

intermediate_iframe_close_callback

Ghi đè hành vi của iframe trung gian mặc định khi người dùng đóng tính năng Một lần chạm 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 Một lần chạm. Hành vi mặc định là xoá iframe trung gian khỏi DOM ngay lập tức.

Trường intermediate_iframe_close_callback chỉ có hiệu lực ở chế độ iframe trung gian. Điều này chỉ ảnh hưởng đến iframe trung gian, thay vì iframe Một lần chạm. Giao diện người dùng bằng một lần chạm sẽ bị xoá trước khi thực hiện lệnh gọi lại.

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

itp_support

Trường này xác định liệu có nên bật trải nghiệm người dùng Một lần chạm đã 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). 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 itp_support: true

login_hint

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

Để biết thêm thông tin, hãy xem trường login_hint trong tài liệu về OpenSL Connect.

Loại Bắt buộc Ví dụ:
Chuỗi, địa chỉ email hoặc giá trị từ trường sub của mã nhận dạng. Không bắt buộc login_hint: 'elisa.beckett@gmail.com'

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 sử dụng tính năng này để gợi ý tên miền cho Google. Khi thành công, những tài khoản người dùng hiển thị trong quá trình lựa chọn tài khoản sẽ được giới hạn trong miền đã 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 lựa chọn tài khoản.

Để biết thêm thông tin, hãy xem trường hd trong tài liệu về OpenSL Connect.

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 hd: '*'

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à dàn xếp 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 use_fedcm_for_prompt: true

Phương thức: google.accounts.id.prompt

Phương thức google.accounts.id.prompt sẽ hiển thị lời nhắc Một lần chạm hoặc trình quản lý thông tin xác thực gốc của trình duyệt sau khi phương thức initialize() được gọi. Hãy xem mã ví dụ sau đây của phương thức:

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

Thông thường, phương thức prompt() được gọi khi tải trang. Do trạng thái phiên và các chế độ cài đặt của người dùng ở phía Google, giao diện người dùng của lời nhắc Một lần chạm có thể không hiển thị. Để nhận thông báo về trạng thái giao diện người dùng trong nhiều thời điểm, hãy truyền một hàm để nhận thông báo về trạng thái giao diện người dùng.

Thông báo được kích hoạt vào những thời điểm sau đây:

  • Thời điểm hiển thị: Sự kiện này xảy ra sau khi phương thức prompt() được gọi. Thông báo chứa giá trị boolean cho biết giao diện người dùng có đang hiển thị hay không.
  • Khoảnh khắc bị bỏ qua: Sự kiện này xảy ra khi lời nhắc Một lần chạm bị đóng bằng tính năng tự động huỷ, huỷ theo cách thủ công hoặc khi Google không cấp được thông tin đăng nhập, chẳng hạn như khi phiên được chọn đã đăng xuất khỏi Google.

    Trong những trường hợp này, bạn nên tiếp tục chuyển sang các nhà cung cấp danh tính tiếp theo, nếu có.

  • Khoảnh khắc bị loại bỏ: Khi Google truy xuất thành công thông tin xác thực hoặc người dùng muốn dừng quy trình truy xuất thông tin xác thực. Ví dụ: khi người dùng bắt đầu nhập tên người dùng và mật khẩu vào hộp thoại đăng nhập, bạn có thể gọi phương thức google.accounts.id.cancel() để đóng lời nhắc Một lần chạm và kích hoạt một khoảnh khắc đóng.

Ví dụ về mã sau đây triển khai khoảnh khắc bị bỏ qua:

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

Loại dữ liệu: PromptMomentNotification

Bảng sau đây liệt kê các phương thức và nội dung mô tả của loại dữ liệu PromptMomentNotification:

Phương thức
isDisplayMoment() Thông báo này có phải là để dành cho một khoảnh khắc hiển thị không?

Lưu ý: Khi FedCM được bật, thông báo này sẽ không được kích hoạt. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.
isDisplayed() Thông báo này có phải là để hiển thị trong một khoảnh khắc và giao diện người dùng có hiển thị không?

Lưu ý: Khi FedCM được bật, thông báo này sẽ không được kích hoạt. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.
isNotDisplayed() Có phải thông báo này chỉ hiển thị trong một khoảnh khắc và giao diện người dùng không hiển thị không?

Lưu ý: Khi FedCM được bật, thông báo này sẽ không được kích hoạt. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.
getNotDisplayedReason()

Lý do chi tiết khiến giao diện người dùng không hiển thị. Sau đây là những giá trị có thể sử dụng:

  • browser_not_supported
  • invalid_client
  • missing_client_id
  • opt_out_or_no_session
  • secure_http_required
  • suppressed_by_user
  • unregistered_origin
  • unknown_reason
Lưu ý: Khi FedCM đang bật, phương thức này sẽ không được hỗ trợ. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.
isSkippedMoment() Thông báo này có phải là thông báo trong một khoảnh khắc bị bỏ qua không?
getSkippedReason()

Lý do chi tiết về khoảnh khắc bị bỏ qua. Sau đây là những giá trị có thể sử dụng:

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
Lưu ý: Khi FedCM đang bật, phương thức này sẽ không được hỗ trợ. Hãy xem trang Di chuyển sang FedCM để biết thêm thông tin.
isDismissedMoment() Thông báo này có phải là thông báo trong giây lát không?
getDismissedReason()

Lý do chi tiết của việc loại bỏ. Sau đây là những giá trị có thể xuất hiện:

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

Trả về một chuỗi cho loại khoảnh khắc. Sau đây là những giá trị có thể xuất hiện:

  • display
  • skipped
  • dismissed

Loại dữ liệu: CredentialResponse

Khi hàm callback được gọi, đối tượng CredentialResponse sẽ được truyền dưới dạng tham số. Bảng sau đây liệt kê các trường có trong đối tượng phản hồi thông tin xác thực:

Trường
credential Trường này là mã thông báo giá trị nhận dạng được trả về.
select_by Trường này đặt cách chọn thông tin xác thực.
state Trường 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.

thông tin xác thực

Trường này là mã thông báo mã nhận dạng dưới dạng chuỗi Mã thông báo web JSON được mã hoá base64 (JWT).

Khi được giải mã, JWT 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": "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"
}

Trường sub là giá trị nhận dạng duy nhất trên toàn cầu của 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ì đây là trường duy nhất trong số tất cả Tài khoản Google và không bao giờ được sử dụng lại. Không dùng địa chỉ email làm giá trị nhận dạng vì một Tài khoản Google có thể có nhiều địa chỉ email tại các thời điểm khác nhau.

Khi 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ó thẩm quyền đối với một địa chỉ email hay không. Trong trường hợp Google uỷ quyền, người dùng được xác nhận là chủ sở hữu tài khoản hợp pháp.

Những trường hợp mà Google có thẩm quyền:

  • email có hậu tố @gmail.com, đây là một Tài khoản Gmail.
  • email_verified có giá trị là true và giá trị hd đã được đặt. Đây là một 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.com và không có hd, thì Google không có thẩm quyền. Do đó, bạn nên sử 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_verfied 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 sau đó.

Trường exp cho thấy 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 cần thiết cho mã thông báo mã nhận dạng nhận được từ tính năng Đăng nhập bằng Google là 1 giờ. Bạn cần xác minh mã thông báo trước thời gian hết hạn. Không sử dụng exp để quản lý phiên. Mã thông báo giá trị 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.

select_by

Bảng sau đây liệt kê các giá trị có thể dùng cho trường select_by. Loại nút dùng cùng với trạng thái phiên và trạng thái đồng ý sẽ đượ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 chạm.

  • Đã 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 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 của mã thông báo giá trị nhận dạng với ứng dụng của bạn, người dùng

    • đã nhấn nút Xác nhận để đồng ý chia sẻ thông tin đăng nhập, hoặc
    • trước đây đã đồng ý và dùng tính năng Chọn tài khoản để chọn 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ị Nội dung mô tả
auto Hoạt động tự động đăng nhập của người dùng trong phiên hoạt động hiện có mà trước đó đã đồng ý chia sẻ thông tin đăng nhập.
user Một người dùng trong phiên hoạt động trước đây từng đồng ý đã nhấn nút "Tiếp tục bằng" một lần chạm để chia sẻ thông tin đăng nhập.
user_1tap Một người dùng đang có một phiên đã nhấn vào nút "Tiếp tục bằng" một lần chạm để đồ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 chưa có phiên hoạt động đã nhấn nút "Tiếp tục bằng" bằng một lần chạm để chọn một tài khoản, sau đó nhấn 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 trong một phiên hoạt động hiện đã đồng ý đã nhấn nút Đăng nhập bằng Google và chọn một Tài khoản Google trong mục "Chọn tài khoản" để chia sẻ thông tin đăng nhập.
btn_confirm Một người dùng đang có một phiên hoạt động đã nhấn nút Đăng nhập bằng Google rồi nhấn nút Xác nhận để đồng ý và chia sẻ thông tin đăng nhập.
btn_add_session Một người dùng (không có phiên hoạt động) từng đồng ý đã nhấn 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 Trước tiên, một người dùng chưa có phiên hoạt động nào đã 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.

state

Trường 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 đã nhấp được chỉ định. Giá trị của trường này giống với giá trị bạn đã chỉ định trong thuộc tính state của nút.

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

Phương thức: google.accounts.id.renderButton

Phương thức google.accounts.id.renderButton hiển thị nút Đăng nhập bằng Google trong trang web của bạn.

Hãy xem mã ví dụ sau đây của phương thức:

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

Loại dữ liệu: GsiButtonConfiguration

Bảng sau đây liệt kê các trường và nội dung mô tả về kiểu dữ liệu GsiButtonConfiguration:

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

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

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

loại

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ụ:
string type: "icon"

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

Loại
standard
Nút có văn bản hoặc thông tin dành riêng cho bạn.
icon
Nút biểu tượng không có văn bản.

chủ đề

Giao diện của 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ụ:
string Không bắt buộc theme: "filled_blue"

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

Giao diện
outline
Giao diện nút chuẩn.
filled_blue
Giao diện nút có màu xanh dương.
filled_black
Giao diện nút có màu đen.

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ụ:
string Không bắt buộc 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ả về các nút đó:

Kích thước
large
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 chuẩn trung bình Nút biểu tượng trung bình
Nút có kích thước trung bình.
small
Một nút nhỏ Nút biểu tượng nhỏ
Một nút nhỏ.

văn bản

Văn bản của 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ó các thuộc tính text khác nhau. Ngoại lệ duy nhất là khi văn bản được đọc để hỗ trợ tiếp cận trê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ụ:
string Không bắt buộc text: "signup_with"

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

Văn bản
signin_with
Văn bản của nút là "Đăng nhập bằng Google".
signup_with
Văn bản của nút là "Đăng ký bằng Google".
continue_with
Văn bản của nút là "Tiếp tục bằng Google".
signin
Văn bản của nút là "Đăng nhập".

hình dạng

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ụ:
string Không bắt buộc shape: "rectangular"

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

Hình dạng
rectangular
Nút có hình chữ nhật. Nếu dùng cho loại nút icon, thì nút này giống với square.
pill
Nút có hình viên thuốc. Nếu dùng cho loại nút icon, thì thao tác này cũng giống như circle.
circle
Nút có hình tròn. Nếu dùng cho loại nút standard, thì nút này giống với pill.
square
Nút có hình vuông. Nếu dùng cho loại nút standard, thì nút này giống với rectangular.

logo_alignment

Độ 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ụ:
string Không bắt buộc logo_alignment: "center"

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

logo_alignment
left
Căn trái biểu trưng của Google.
center
Căn giữa biểu trưng của Google.

chiều rộng

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

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

Loại Bắt buộc Ví dụ:
string Không bắt buộc width: "400"

ngôn ngữ

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

Nếu bạn không đặt chính sách này, 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 phiên Google sẽ được sử dụng. Do đó, mỗi người dùng có thể thấy các phiên bản khác nhau của các nút đã bản địa hoá 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ụ:
string Không bắt buộc locale: "zh_CN"

click_listener

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

Trong ví dụ này, thông báo Sign in with Google icon (Đã nhấp vào nút Đăng nhập bằng Google...) được ghi lại 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.

state

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

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

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

Loại dữ liệu: Thông tin xác thực

Khi hàm native_callback được gọi, đối tượng Credential sẽ được truyền dưới dạng tham số. Bảng sau đây liệt kê các trường có trong đối tượng:

Trường
id Xác định người dùng.
password Mật khẩu

Phương thức: google.accounts.id.disableAutoSelect

Khi người dùng đăng xuất khỏi trang web, bạn cần gọi phương thức google.accounts.id.disableAutoSelect để ghi lại trạng thái trong cookie. Việc này giúp ngăn chặn vòng lặp cụ thể của trải nghiệm người dùng. Hãy xem đoạn mã sau đây của phương thức:

google.accounts.id.disableAutoSelect()

Ví dụ về mã sau đây triển khai phương thức google.accounts.id.disableAutoSelect bằng hàm onSignout():

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

Phương thức: google.accounts.id.storeCredential

Phương thức này là một trình bao bọc cho phương thức store() của API trình quản lý thông tin xác thực gốc của trình duyệt. Do đó, bạn chỉ có thể dùng dịch vụ này để lưu trữ thông tin xác thực mật khẩu. Hãy xem mã ví dụ sau đây của phương thức:

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

Ví dụ về mã sau đây triển khai phương thức google.accounts.id.storeCredential bằng hàm onSignIn():

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

Phương thức: google.accounts.id.cancel

Bạn có thể huỷ quy trình Một lần chạm nếu xoá lời nhắc khỏi DOM của bên đáng tin cậy. Thao tác huỷ sẽ bị bỏ qua nếu thông tin xác thực đã được chọn. Hãy xem mã ví dụ sau đây của phương thức này:

google.accounts.id.cancel()

Ví dụ về mã sau đây triển khai phương thức google.accounts.id.cancel() bằng hàm onNextButtonClicked():

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

Lệnh gọi lại tải thư viện: onGoogleLibraryLoad

Bạn có thể đăng ký một lệnh gọi lại onGoogleLibraryLoad. Bạn sẽ nhận được thông báo sau khi thư viện JavaScript của tính năng Đăng nhập bằng Google được tải:

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

Lệnh gọi lại này chỉ là một phím tắt cho lệnh gọi lại window.onload. Không có khác biệt về hành vi.

Mã ví dụ sau đây triển khai lệnh gọi lại onGoogleLibraryLoad:

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

Phương thức: google.accounts.id.revoke

Phương thức google.accounts.id.revoke thu hồi quyền truy cập OAuth dùng để chia sẻ mã nhận dạng cho người dùng đã chỉ định. Hãy xem đoạn mã sau đây của phương thức: javascript google.accounts.id.revoke(login_hint, callback)

Thông số Loại Nội dung mô tả
login_hint string Địa chỉ email hoặc mã nhận dạng duy nhất của Tài khoản Google của người dùng. Mã nhận dạng là thuộc tính sub của tải trọng credential (thông tin xác thực).
callback hàm Trình xử lý RevocationResponse tuỳ chọn.

Mã mẫu sau đây cho biết cách sử dụng phương thức revoke kèm theo một mã nhận dạng.

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

Loại dữ liệu: ThuResponse

Khi hàm callback được gọi, đối tượng RevocationResponse sẽ được truyền dưới dạng tham số. Bảng sau đây liệt kê các trường có trong đối tượng phản hồi thu hồi:

Trường
successful Trường này là giá trị trả về của lệnh gọi phương thức.
error Trường này (không bắt buộc) chứa thông báo phản hồi lỗi chi tiết.

thành công

Trường này là một giá trị boolean được đặt thành true nếu lệnh gọi phương thức thu hồi thành công hoặc false khi không thành công.

error

Trường này là một giá trị chuỗi và chứa thông báo lỗi chi tiết nếu lệnh gọi phương thức thu hồi không thành công, thì không xác định được khi thành công.