Lật ứng dụng cho iOS

Tính năng liên kết Lật ứng dụng dựa trên OAuth (App Flip) sẽ mở ứng dụng iOS của bạn từ một ứng dụng của Google để giúp người dùng ứng dụng Google liên kết tài khoản của họ dễ dàng hơn. Bạn cần thực hiện các thay đổi nhỏ về mã đối với ứng dụng iOS để triển khai tính năng này.

Trong tài liệu này, bạn sẽ tìm hiểu cách sửa đổi ứng dụng iOS của mình để hỗ trợ tính năng Lật ứng dụng.

Dùng thử mẫu

Ứng dụng mẫu App Flip minh hoạ hoạt động tích hợp liên kết tài khoản trên iOS tương thích với ứng dụng App Flip. Bạn có thể dùng ứng dụng này để xác minh cách phản hồi một lượt chuyển đổi ứng dụng đến ở dạng phổ quát liên kết từ ứng dụng di động của Google.

Ứng dụng mẫu được định cấu hình sẵn để tích hợp với Công cụ kiểm thử độ lật ứng dụng cho iOS, mà bạn có thể sử dụng để xác minh việc tích hợp ứng dụng iOS của mình với App Flip trước bạn định cấu hình liên kết tài khoản với Google. Ứng dụng này mô phỏng đường liên kết phổ quát được kích hoạt bởi các ứng dụng di động của Google khi Lật ứng dụng được bật.

Cách hoạt động

Sau đây là các bước quy trình mà ứng dụng Google và ứng dụng của bạn sẽ thực hiện khi Lật ứng dụng sẽ diễn ra:

1. Ứng dụng Google cố gắng mở đường liên kết chung của ứng dụng. Công cụ này có thể mở ứng dụng của bạn nếu ứng dụng đó được cài đặt trên thiết bị của người dùng và được liên kết với đường liên kết phổ quát. Hãy xem phần Hỗ trợ đường liên kết phổ quát để biết thông tin chi tiết.

2. Ứng dụng của bạn sẽ kiểm tra để đảm bảo rằng tham số client_id và redirect_uri đã mã hoá trong URL đến khớp với đường liên kết chung dự kiến của Google.

3. Ứng dụng của bạn yêu cầu mã uỷ quyền từ máy chủ OAuth2. Ở cuối của quy trình này, ứng dụng của bạn sẽ trả về một mã uỷ quyền hoặc một lỗi ứng dụng Google. Để thực hiện thao tác này, thao tác này sẽ mở đường liên kết chung của Google với các tham số cho mã hoặc lỗi uỷ quyền.

4. Ứng dụng Google xử lý đường liên kết phổ quát đến của Google và tiếp tục với phần còn lại của quy trình. Nếu bạn cung cấp mã uỷ quyền, việc liên kết sẽ hoàn tất ngay lập tức. Quá trình trao đổi mã thông báo diễn ra từ máy chủ đến máy chủ, tương tự như trong quy trình liên kết OAuth dựa trên trình duyệt. Nếu mã lỗi là sẽ trả về, quy trình liên kết sẽ tiếp tục với các tuỳ chọn thay thế.

Sửa đổi ứng dụng iOS của bạn để hỗ trợ tính năng Lật ứng dụng

Để hỗ trợ App Flip (Lật ứng dụng), hãy thay đổi mã sau đây cho ứng dụng iOS của bạn:

1. Xử lý NSUserActivityTypeBrowsingWeb trong Uỷ quyền ứng dụng.
2. Thu thập tham số redirect_uri và state từ URL để sử dụng sau này.
3. Kiểm tra để đảm bảo redirect_uri khớp với định dạng sau:

   https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
   https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

4. Xác minh rằng mã ứng dụng khách khớp với giá trị dự kiến. Sử dụng mã mẫu:

   func application(_ application: UIApplication,
                    continue userActivity: NSUserActivity,
                    restorationHandler: @escaping ([Any]?) -> Void) -> Bool
   {
       guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let incomingURL = userActivity.webpageURL,
           let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
           let params = components.queryItems else {
               return false
       }
   
       if let clientId = params.filter({$0.name == "client_id"}).first?.value,
           let state = params.filter({$0.name == "state"}).first?.value,
           let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {
   
           // Save the redirect_uri and state for later...
   
           // Verify the client id
           return (clientId == GOOGLE_CLIENT_ID)
       } else {
           // Missing required parameters
           return false
       }
   }
   

5. Sau khi uỷ quyền thành công, hãy gọi URI chuyển hướng bằng lệnh uỷ quyền . Hãy sử dụng mã mẫu sau:

   func returnAuthCode(code: String, state: String, redirectUri: String) {
       var redirectURL = URL(string: redirectUri)
       var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
   
       // Return the authorization code and original state
       let paramAuthCode = URLQueryItem(name: "code", value: code)
       let paramState = URLQueryItem(name: "state", value: state)
       components?.queryItems = [paramAuthCode, paramState]
       if let resultURL = components?.url {
           UIApplication.shared.open(
               resultURL,
               options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
               completionHandler: nil)
       }
   }
   

6. Nếu xảy ra lỗi, hãy đính kèm kết quả lỗi vào URI chuyển hướng. Hãy sử dụng mã mẫu sau:

   Lưu ý: Không xử lý lỗi trực tiếp trong ứng dụng, thay vào đó, hãy trả về kết quả lỗi với REDIRECT_URL. Điều này đảm bảo rằng phương án dự phòng thích hợp sẽ được phân loại nếu quy trình liên kết ứng dụng không thành công.

   func returnError(redirectUri: String) {
       var redirectURL = URL(string: redirectUri)
       var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
   
       // Return the authorization code and original state
       let paramError = URLQueryItem(name: "error", value: "invalid_request")
       let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
       components?.queryItems = [paramError, paramDescription]
       if let resultURL = components?.url {
           UIApplication.shared.open(
               resultURL,
               options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
               completionHandler: nil)
       }
   }
   

Tham số truy vấn cho đường liên kết chung của ứng dụng

Khi ứng dụng Google mở, đường liên kết chung của ứng dụng sẽ chứa những thông tin sau tham số truy vấn:

• client_id (String): Google client_id được đăng ký trong ứng dụng của bạn.
• scope (List of String): Danh sách các phạm vi được phân tách bằng dấu cách được yêu cầu.
• state (String): Một số chỉ dùng một lần được Google sử dụng để xác minh rằng lệnh uỷ quyền là nhằm phản hồi yêu cầu gửi đi của Google.
• redirect_uri (String): Đường liên kết phổ quát của Google. "Lật trang" URI sẽ mở ứng dụng Google và chuyển kết quả.

Tham số truy vấn cho đường liên kết phổ quát của Google

Các tham số được dùng khi kết quả uỷ quyền được trả về thành công:

• code (String): Giá trị của mã uỷ quyền, nếu có.
• state (String): Giá trị chính xác nhận được từ đường liên kết chung đến.

Các tham số được dùng khi kết quả uỷ quyền được trả về không thành công:

• error (String), với các giá trị sau:

  • cancelled: Lỗi có thể khôi phục. Ứng dụng Google sẽ cố gắng tìm tài khoản bằng cách sử dụng URL uỷ quyền. Một số ví dụ là người dùng không thành công để đăng nhập, thiết bị không có kết nối mạng hoặc hết thời gian kết nối.
  • unrecoverable: Lỗi không thể khôi phục. Ví dụ: người dùng cố gắng liên kết với một tài khoản đã bị vô hiệu hoá.Ứng dụng Google sẽ huỷ việc liên kết tài khoản.
  • invalid_request: Tham số yêu cầu không hợp lệ hoặc bị thiếu. Đây là lỗi có thể khôi phục. Ứng dụng Google sẽ cố gắng liên kết tài khoản bằng URL uỷ quyền.
  • access_denied: Người dùng từ chối yêu cầu đồng ý. Đây là lỗi không thể khôi phục; ứng dụng Google sẽ huỷ liên kết.

• error_description (String, không bắt buộc): Thông báo lỗi thân thiện với người dùng.

  Lưu ý: Để biết thêm thông tin về các lỗi có thể xảy ra và nội dung không bắt buộc của trường error_description, hãy xem OAuth 2.0 chuẩn.

Đối với tất cả các loại lỗi, bạn phải trả về dữ liệu phản hồi cho REDIRECT_URI để đảm bảo phân loại dự phòng thích hợp.

Sửa đổi điểm cuối uỷ quyền để hỗ trợ App Flip

Định cấu hình nền tảng của bạn để chấp nhận các yêu cầu sử dụng URL chuyển hướng App Flip của Google:

• Ứng dụng Google Home

  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast
  

• Ứng dụng Trợ lý Google

  https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
  https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
  https://oauth-redirect.googleusercontent.com/a/com.google.OPA
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA
  

Kiểm tra để đảm bảo client_id và URL được chỉ định bởi tham số redirect_uri khớp với các giá trị dự kiến khi nhận được yêu cầu. nếu khách hàng xác minh không thành công, hãy trả về lỗi invalid_request cho redirect_uri.