Tài liệu tham khảo về ứng dụng JavaScript đăng nhập bằng Google

Tài liệu tham khảo này mô tả các thuộc tính và phương thức ứng dụng JavaScript mà bạn sẽ dùng để triển khai tính năng Đăng nhập bằng Google trong các ứng dụng web của mình.

Nếu bạn gặp vấn đề khi sử dụng thư viện, hãy báo cáo vấn đề đó cho kho lưu trữ GitHub của chúng tôi. .

Thiết lập xác thực

Tải thư viện nền tảng API của Google để tạo đối tượng gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

Sau khi thư viện nền tảng tải, hãy tải thư viện auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Khởi động đối tượng GoogleAuth. Bạn phải gọi phương thức này trước khi gọi các phương thức của gapi.auth2.GoogleAuth.

Khi khởi chạy đối tượng GoogleAuth, bạn sẽ định cấu hình đối tượng đó bằng mã ứng dụng khách OAuth 2.0 và mọi tuỳ chọn bổ sung mà bạn muốn chỉ định. Sau đó, nếu người dùng đã đăng nhập, đối tượng GoogleAuth sẽ khôi phục trạng thái đăng nhập của người dùng từ phiên trước.

{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}

GoogleAuth.the(onInit; onError)

Gọi hàm onInit khi đối tượng GoogleAuth được khởi chạy đầy đủ. Nếu lỗi xảy ra trong khi khởi chạy (điều này có thể xảy ra trong các trình duyệt cũ không được hỗ trợ), thì hàm onError sẽ được gọi.

Mã lỗi

idpiframe_initialization_failed

Không khởi chạy được iframe bắt buộc từ Google, ví dụ: do một môi trường không được hỗ trợ. Thuộc tính details sẽ cung cấp thêm thông tin về lỗi đã xảy ra.

gapi.auth2.ClientConfig

Giao diện đại diện cho các tham số cấu hình khác nhau cho phương thức gapi.auth2.init.

Xác thực

GoogleAuth là một lớp singleton cung cấp các phương thức cho phép người dùng đăng nhập bằng Tài khoản Google, nhận trạng thái đăng nhập hiện tại của người dùng, nhận dữ liệu cụ thể từ hồ sơ Google của người dùng, yêu cầu các phạm vi bổ sung và đăng xuất khỏi tài khoản hiện tại.

gapi.auth2.getAuthInstance()

Trả về đối tượng GoogleAuth. Bạn phải khởi tạo đối tượng GoogleAuth bằng gapi.auth2.init() trước khi gọi phương thức này.

GoogleAuth.isSignedIn.get()

Trả về thông tin người dùng hiện tại có đăng nhập hay không.

GoogleAuth.isSignedIn.listen(listener)

Theo dõi các thay đổi về trạng thái đăng nhập của người dùng hiện tại.

GoogleAuth.signIn()

Đăng nhập người dùng bằng các tuỳ chọn được chỉ định cho gapi.auth2.init().

Mã lỗi

Hãy xem GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Đăng nhập người dùng bằng các tuỳ chọn đã chỉ định.

Mã lỗi

popup_closed_by_user

Người dùng đã đóng cửa sổ bật lên trước khi hoàn tất quy trình đăng nhập.

access_denied

Người dùng từ chối cấp quyền cho các phạm vi bắt buộc.

immediate_failed

Không thể tự động chọn người dùng mà không nhắc người dùng thực hiện quy trình đồng ý. Lỗi xảy ra khi sử dụng signIn với tuỳ chọn prompt: 'none'. Bạn không bắt buộc phải sử dụng tuỳ chọn này vì gapi.auth2.init sẽ tự động đăng nhập người dùng nếu người dùng đã đăng nhập trong một phiên trước đó.

gapi.auth2.SignInOptions

Giao diện đại diện cho các tham số cấu hình khác nhau cho phương thức GoogleAuth.signIn(options).

GoogleAuth.signOut()

Đăng xuất tài khoản hiện tại khỏi ứng dụng.

GoogleAuth.disconnect()

Thu hồi tất cả các phạm vi mà người dùng đã cấp.

GoogleAuth.grantOfflineAccess(options)

Yêu cầu người dùng cho phép truy cập vào các phạm vi đã chỉ định khi không có mạng.

{
  scope: 'profile email'
}

auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Mã lỗi

popup_closed_by_user

Người dùng đã đóng cửa sổ bật lên trước khi hoàn tất quy trình yêu cầu đồng ý.

access_denied

Người dùng từ chối cấp quyền cho các phạm vi bắt buộc.

immediate_failed

Hệ thống không thể chọn tự động người dùng mà không nhắc quy trình đồng ý. Lỗi xảy ra khi sử dụng signIn với tuỳ chọn prompt: 'none'. Bạn không bắt buộc phải sử dụng tuỳ chọn này, vì gapi.auth2.init sẽ tự động đăng nhập người dùng nếu người dùng từng đăng nhập trong phiên trước đó.

gapi.auth2.OfflineAccessOptions

Giao diện đại diện cho các tham số cấu hình khác nhau cho phương thức GoogleAuth.grantOfflineAccess(options).

GoogleAuth.attachClickHandler(container; options; onsuccess, onfailure)

Đính kèm quy trình đăng nhập vào trình xử lý lượt nhấp của vùng chứa đã chỉ định.

Người dùng

Đối tượng GoogleUser đại diện cho một tài khoản người dùng. Các đối tượng GoogleUser thường được lấy bằng cách gọi GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Trả về một đối tượng GoogleUser đại diện cho người dùng hiện tại. Xin lưu ý rằng trong phiên bản GoogleAuth mới khởi tạo, người dùng hiện tại chưa được đặt. Sử dụng phương thức currentUser.listen() hoặc GoogleAuth.then() để lấy một thực thể GoogleAuth đã khởi chạy.

GoogleAuth.currentUser.listen(listener)

Theo dõi các thay đổi trong currentUser.

GoogleUser.getId()

Lấy chuỗi mã nhận dạng duy nhất của người dùng.

GoogleUser.isSignedIn()

Trả về true nếu người dùng đã đăng nhập.

GoogleUser.getHostedDomain()

Lấy miền G Suite của người dùng nếu người dùng đăng nhập bằng tài khoản G Suite.

GoogleUser.getGrantedScopes()

Lấy các phạm vi mà người dùng đã cấp dưới dạng một chuỗi được phân tách bằng dấu cách.

GoogleUser.getBasicProfile()

Nhận thông tin cơ bản về hồ sơ của người dùng.

GoogleUser.getAuthResponse(includeAuthorizationData)

Lấy đối tượng phản hồi từ phiên xác thực của người dùng.

GoogleUser.reloadAuthResponse()

Buộc làm mới mã thông báo truy cập, sau đó trả về một Lời hứa cho AuthResponse mới.

gapi.auth2.AuthResponse

Phản hồi được trả về khi gọi các phương thức GoogleUser.getAuthResponse(includeAuthorizationData) hoặc GoogleUser.reloadAuthResponse().

GoogleUser.hasGrantedScopes(scopes)

Trả về true nếu người dùng đã cấp các phạm vi đã chỉ định.

GoogleUser.grant(options)

Yêu cầu thêm phạm vi cho người dùng.

Hãy xem GoogleAuth.signIn() để biết danh sách tham số và mã lỗi.

GoogleUser.grantOfflineAccess(options)

Yêu cầu người dùng cho phép truy cập vào các phạm vi đã chỉ định khi không có mạng.

{
  scope: 'profile email'
}

GoogleUser.disconnect()

Thu hồi tất cả các phạm vi mà người dùng đã cấp cho ứng dụng.

Phần tử trên giao diện người dùng

gapi.signin2.render(id, options)

Hiển thị nút đăng nhập trong phần tử có mã nhận dạng đã cho, sử dụng chế độ cài đặt do đối tượng options chỉ định.

{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}

Nâng cao

gapi.auth2.authorize(params, callback)

Thực hiện uỷ quyền OAuth 2.0 một lần. Tuỳ thuộc vào các tham số được sử dụng, thao tác này sẽ mở một cửa sổ bật lên trong quy trình đăng nhập bằng Google hoặc cố gắng tải ngầm phản hồi yêu cầu mà không cần người dùng phải tương tác.

Sau đây là một số trường hợp sử dụng mà phương thức này hữu ích:

• Ứng dụng của bạn chỉ cần yêu cầu điểm cuối API của Google một lần, chẳng hạn như để tải video trên YouTube mà người dùng yêu thích trong lần đầu tiên họ đăng nhập.
• Ứng dụng của bạn có cơ sở hạ tầng quản lý phiên riêng và chỉ yêu cầu Mã thông báo giá trị nhận dạng một lần để xác định người dùng trong phần phụ trợ.
• Bạn có thể sử dụng nhiều Mã ứng dụng khách trong cùng một trang.

{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}

Ví dụ:

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Mã lỗi

idpiframe_initialization_failed

Không khởi chạy được iframe bắt buộc từ Google, ví dụ: do môi trường không được hỗ trợ. Thuộc tính details sẽ cung cấp thêm thông tin về lỗi đã xảy ra.

popup_closed_by_user

Người dùng đã đóng cửa sổ bật lên trước khi hoàn tất quy trình đăng nhập.

access_denied

Người dùng từ chối cấp quyền cho các phạm vi bắt buộc.

immediate_failed

Hệ thống không thể chọn tự động người dùng mà không nhắc quy trình đồng ý. Lỗi xảy ra khi sử dụng signIn với tuỳ chọn prompt: 'none'.

gapi.auth2.AuthorizeConfig

Giao diện đại diện cho các tham số cấu hình khác nhau cho phương thức gapi.auth2.authorize.

gapi.auth2.AuthorizeResponse

Phản hồi được trả về cho lệnh gọi lại của phương thức gapi.auth2.authorize.