Cấp phép tài khoản do người dùng kiểm soát – Hướng dẫn cho nhà phát triển API

Tài liệu này giải thích các khái niệm quan trọng về cách sử dụng API cấp phép để tạo tài khoản Google Analytics mới.

Giới thiệu

Bạn có thể sử dụng API cấp phép để tạo tài khoản Google Analytics mới và bật Google Analytics cho khách hàng của mình trên quy mô lớn. API này dành cho các nhà cung cấp dịch vụ đủ điều kiện và các đối tác lớn. Hãy truy cập phần Tổng quan về API cấp phép để xem giới thiệu về API cấp phép.

Trước khi bắt đầu

Tất cả API Google Analytics đều được truy cập theo cách tương tự. Trước khi bắt đầu sử dụng API cấp phép, bạn nên:

  • Hãy đọc trang thư viện ứng dụng để biết danh sách đầy đủ các thư viện ứng dụng cụ thể của ngôn ngữ lập trình hoạt động với API.
  • Đọc Hướng dẫn tham khảo để tìm hiểu về giao diện API và cách truy cập vào dữ liệu mà không cần thư viện ứng dụng.

Mỗi thư viện ứng dụng cung cấp một đối tượng dịch vụ phân tích duy nhất để truy cập API cấp phép. Để tạo đối tượng dịch vụ, thường thì bạn phải trải qua các bước sau:

  1. Đăng ký ứng dụng của bạn trong Google API Console.
  2. Uỷ quyền tạo tài khoản Google Analytics mới.
  3. Tạo một đối tượng dịch vụ Analytics.

Nếu bạn chưa hoàn tất các bước này, vui lòng dừng lại và đọc Xin chào hướng dẫn về API Google Analytics. Hướng dẫn này sẽ hướng dẫn bạn qua các bước tạo ứng dụng API Google Analytics đầu tiên. Sau khi hoàn tất, bạn sẽ hiểu cách truy cập vào các API Google Analytics để thực hiện các công việc thực tế.

Tổng quan

Khi tạo tài khoản Google Analytics bằng API cấp phép, bạn cần cân nhắc sử dụng 2 quy trình riêng biệt:

  • Quy trình kỹ thuật: Quy trình toàn diện để cung cấp tài khoản Google Analytics cho người dùng theo phương thức lập trình.
  • Luồng người dùng: Những điểm cần cân nhắc khi triển khai mà bạn nên thực hiện cho quy trình tạo tài khoản từ góc độ của người dùng.

Tài liệu này mô tả các bước và yêu cầu cấp cao cho từng quy trình.

Quy trình kỹ thuật

Sau đây là các bước sử dụng API cấp phép nhằm tạo tài khoản mới và tích hợp với Google Analytics:

  1. Nhắc người dùng xác thực và uỷ quyền ứng dụng/dịch vụ bằng OAuth 2.0.
  2. Tạo Phiếu yêu cầu hỗ trợ tài khoản bằng cách sử dụng API cấp phép.
  3. Chuyển hướng người dùng để chấp nhận Điều khoản dịch vụ (TOS) của Google Analytics và xử lý nội dung phản hồi.
  4. (Không bắt buộc) Thiết lập tài khoản và các cơ hội tích hợp.

Nếu tất cả các bước này được hoàn tất thành công, hệ thống sẽ tạo một tài khoản Google Analytics cho người dùng và bạn sẽ có Mã tài khoản, Mã tài sản và Mã chế độ xem (Hồ sơ) cho tài khoản mới.

Đối với mỗi bước bên dưới, có Yêu cầu để hoàn thành bước, Kết quả của bước và mô tả về Quy trình kỹ thuật cho bước đó.

1. Xác thực và uỷ quyền

Mỗi người dùng cần phải ủy quyền cho ứng dụng của bạn và cấp cho ứng dụng khả năng thay mặt họ cấp phép một tài khoản Google Analytics. Bạn nên thực hiện bước này cho quy trình đăng ký Máy chủ web OAuth 2.0.

Những việc bạn cần làm để hoàn thành bước này

  • Mã ứng dụng khách – Client ID của dự án mà bạn sẽ sử dụng. Bảng điều khiển này có trong Google Developers Console. Hãy đọc về quy trình Máy chủ web OAuth 2.0 để tìm hiểu thêm.
  • URI chuyển hướng – Đây là nơi người dùng được chuyển hướng đến và phản hồi OAuth 2.0 được gửi.
    • Định cấu hình Redirect URIs và lấy Client ID cho dự án của bạn bằng cách sử dụng Google Developers Console.
    • Giá trị của tham số này phải khớp chính xác với một trong các giá trị được đăng ký trong Google Developers Console (bao gồm cả giao thức http hoặc https, cách viết hoa và '/' ở cuối).
  • Phạm vi xác thực cho API cấp phép Google Analytics

Kết quả của bước này

Sau khi quy trình OAuth 2.0 hoàn tất, người dùng sẽ thay mặt họ ủy quyền cho ứng dụng của bạn cung cấp một tài khoản và bạn sẽ có một Mã thông báo truy cập cho người dùng đó.

Lưu ý về mã thông báo và phạm vi:

  • Nếu định thực hiện thêm các yêu cầu khác cho cấu hình tài khoản của người dùng hoặc dữ liệu báo cáo sau khi tạo tài khoản, thì bạn cũng có thể cấp phép thêm các phạm vi trong bước này. Ví dụ: phạm vi readonly hoặc edit.
  • Mã truy cập có thời gian tồn tại giới hạn. Nếu ứng dụng của bạn cần quyền truy cập vào API Google Analytics sau thời gian hoạt động của một mã truy cập, thì bạn cũng có thể yêu cầu mã làm mới bằng cách đặt access_type=offline. Mã làm mới nên được lưu trong bộ nhớ dài hạn an toàn cho mỗi người dùng vì mã này cho phép ứng dụng của bạn lấy mã truy cập mới. Hãy xem phần Truy cập ngoại tuyến để biết thêm thông tin chi tiết.

Quy trình kỹ thuật cho bước này

Bạn cần lấy Mã thông báo truy cập cho người dùng. Dựa trên quy trình được mô tả tại Máy chủ web OAuth 2.0, hãy chuyển người dùng đến dịch vụ Tài khoản Google rồi xử lý phản hồi khi người dùng được chuyển hướng lại dịch vụ của bạn sau khi hoàn tất quy trình xác thực.

Tạo URL OAuth 2.0 để người dùng truy cập

Khi người dùng nhấp vào một nút hoặc đường liên kết để Bắt đầu hoặc Tạo tài khoản, đường liên kết sẽ trỏ đến đầu quy trình OAuth 2.0 để yêu cầu người dùng cấp quyền cấp phép. Ví dụ:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Xử lý Phản hồi từ Dịch vụ Tài khoản Google

Sau khi quyết định cấp quyền truy cập vào ứng dụng của bạn, người dùng sẽ được chuyển hướng đến redirect_uri như được chỉ định trong URL mà bạn đã tạo bằng tham số truy vấn chứa mã uỷ quyền. Nếu người dùng đã phê duyệt yêu cầu, thì phản hồi mã uỷ quyền có thể được dùng để trao đổi mã uỷ quyền lấy mã truy cập bằng cách gửi yêu cầu POST tới API Tài khoản Google.

Lưu Mã làm mới (nếu có)

Mã truy cập sẽ được dùng trong bước tiếp theo để bạn có thể lưu trữ tạm thời mã truy cập đó. Nếu cũng đã yêu cầu mã làm mới cho người dùng, thì bạn nên lưu trữ mã này một cách an toàn để sử dụng trong thời gian dài hơn. Mã làm mới là mã tồn tại lâu dài và có thể được dùng để phát hành mã truy cập mới.

2. Tạo Yêu cầu hỗ trợ tài khoản bằng cách sử dụng API cấp phép

Sau khi có mã truy cập cho người dùng được uỷ quyền, bạn có thể sử dụng mã này để yêu cầu API cấp phép tạo Phiếu yêu cầu hỗ trợ tài khoản cho người dùng đó. Phiếu yêu cầu hỗ trợ tài khoản là bước đầu tiên để tạo tài khoản cho một người dùng.

Những việc bạn cần làm để hoàn thành bước này

Mã thông báo truy cập cho người dùng được uỷ quyền như mô tả trong phần Xác thực và uỷ quyền và thông tin chi tiết về việc cấp phép sau đây:

  • URI chuyển hướng
    • Xác định nơi người dùng được chuyển hướng đến sau trang Điều khoản dịch vụ (TOS) của Google Analytics. URL này có thể khác với URI chuyển hướng được chỉ định trong quy trình uỷ quyền OAuth 2.0.
    • Giá trị của tham số URI chuyển hướng phải khớp chính xác với một trong các giá trị đã đăng ký trong Google Developers Console (bao gồm cả giao thức http hoặc https, cách viết hoa và theo sau là "/").
  • Trường tài khoản
    • Bắt buộc phải có thuộc tính name cho tài khoản.
  • Trường Thuộc tính web
    • Bắt buộc phải có thuộc tính name cho thuộc tính này.
    • Bắt buộc phải có websiteUrl.
  • Trường hồ sơ
    • Bạn bắt buộc phải thuộc tính name cho hồ sơ.
    • Bạn có thể cung cấp timezone nếu muốn. Giá trị mặc định là America/Los_Angeles.

Khi tạo phiếu yêu cầu hỗ trợ tài khoản, bạn chỉ có thể đặt các trường cơ bản đã xác định ở trên. Sau khi tạo tài khoản, bạn có thể thực hiện mọi thay đổi bổ sung về cấu hình đối với tài sản hoặc chế độ xem (hồ sơ) bằng cách sử dụng API Quản lý.

Hãy xem Tài liệu tham khảo API cho Tài khoản, Thuộc tính và Chế độ xem (Hồ sơ) để biết thêm thông tin chi tiết về các trường này.

Kết quả của bước này

Sau khi gửi yêu cầu thành công tới API cấp phép, bạn sẽ có một Phiếu yêu cầu hỗ trợ tài khoản ngắn hạn cho người dùng. Mã phiếu yêu cầu hỗ trợ tài khoản được sử dụng ở bước cuối cùng để nhắc người dùng chấp nhận Điều khoản dịch vụ (TOS) và kích hoạt tài khoản của họ. Bạn không thể sử dụng tài khoản cho đến khi Điều khoản dịch vụ được chấp nhận.

Quy trình kỹ thuật cho bước này

Sử dụng mã truy cập cho người dùng được lấy trong quá trình Xác thực và ủy quyền, yêu cầu HTTP POST được gửi đến API cấp phép.

Yêu cầu API cấp phép để tạo Vé tài khoản

Xem lại phương thức createAccountTicket trong tài liệu tham khảo API cấp phép để biết thông tin chi tiết về cách đưa ra yêu cầu.

Phản hồi từ API cấp phép

Yêu cầu thành công sẽ trả về phản hồi 200. Nội dung phản hồi chứa một Phiếu yêu cầu hỗ trợ tài khoản (dành cho thời gian ngắn). Phiếu yêu cầu hỗ trợ tài khoản bao gồm một mã nhận dạng và thông tin chi tiết cho cây tài khoản mới.

Xem lại Account Ticket resource trong tài liệu tham khảo về API cấp phép để biết thông tin chi tiết về phản hồi.

Ứng dụng cũng cần xử lý phản hồi lỗi.

3. Người dùng chấp nhận Điều khoản dịch vụ của Google Analytics (TOS)

Sau khi có mã phiếu yêu cầu hỗ trợ tài khoản cho người dùng, bạn có thể sử dụng mã này với yêu cầu Điều khoản dịch vụ để nhắc người dùng chấp nhận Điều khoản dịch vụ của Google Analytics.

Những việc bạn cần làm để hoàn thành bước này

Mã yêu cầu hỗ trợ tài khoản cho người dùng được uỷ quyền.

Kết quả của bước này

Sau khi hoàn tất thành công Quy trình điều khoản dịch vụ bằng cách sử dụng mã phiếu yêu cầu hỗ trợ tài khoản, tài khoản, tài sản và chế độ xem (hồ sơ) sẽ được tạo. Người dùng hiện sẽ có một tài khoản đang hoạt động. Phản hồi từ trang Điều khoản dịch vụ sẽ bao gồm Mã tài khoản, Mã tài sản và Mã chế độ xem (Hồ sơ).

Quy trình kỹ thuật cho bước này

Bằng cách sử dụng mã phiếu yêu cầu hỗ trợ tài khoản, hãy chuyển hướng người dùng đến trang Điều khoản dịch vụ của Google Analytics để họ có thể chấp nhận TOS, sau đó bạn cần xử lý phản hồi từ API.

Tạo URL của Điều khoản dịch vụ để người dùng truy cập

Chuyển hướng người dùng đến trang Điều khoản dịch vụ và đưa mã yêu cầu hỗ trợ tài khoản vào URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Xử lý phản hồi của Điều khoản dịch vụ

Sau khi thực hiện hành động nào đó trên trang Điều khoản dịch vụ, người dùng sẽ được chuyển hướng quay lại redirectUri được chỉ định trong quá trình tạo phiếu yêu cầu hỗ trợ tài khoản. Phản hồi từ trang Điều khoản dịch vụ sẽ được đưa vào chuỗi truy vấn.

Phản hồi thành công sẽ trả về dữ liệu về cấu trúc tài khoản mới tạo cũng như accountTicketId ban đầu:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Ví dụ: nếu trình xử lý Điều khoản dịch vụ cho ứng dụng của bạn nằm ở http://www.your-app.com/gaTOS, thì bạn nên đặt thuộc tính này thành redirectUri khi tạo yêu cầu tài khoản. Trình xử lý TOS của ứng dụng phải dự kiến và xử lý đúng cách các yêu cầu HTTP GET chứa tham số truy vấn accountId, webPropertyId, profileId và accountTicketId trong trường hợp phiếu yêu cầu hỗ trợ tài khoản hợp lệ và người dùng đã chấp nhận TOS.

Phản hồi không thành công sẽ bao gồm nội dung phản hồi lỗi:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Trình xử lý TOS cũng phải xử lý đúng cách các yêu cầu HTTP GET chứa tham số truy vấn error, cho biết đã xảy ra lỗi. Bạn có thể dùng giá trị của tham số truy vấn để thực hiện thêm hành động hoặc hiển thị một thông báo cho người dùng:

  • error=user_cancel – Người dùng không chấp nhận điều khoản dịch vụ.
  • error=max_accounts_reached – Người dùng đã đạt đến giới hạn tài khoản Google Analytics.
  • error=backend_error – Lỗi chung. Máy chủ trả về một lỗi không thuộc các danh mục ở trên.

4. (Không bắt buộc) Cơ hội tích hợp

Nếu đã làm theo Quy trình kỹ thuật ở trên thì bạn sẽ tạo một tài khoản cho người dùng và sẽ có Mã tài khoản, Mã thuộc tính và Mã chế độ xem (Hồ sơ). Nếu cũng yêu cầu thêm quyền, bạn cũng có thể có mã làm mới cho người dùng. Với dữ liệu này, bạn có thể:

  • Nếu có thể, hãy tự động chèn đoạn mã theo dõi Google Analytics chuẩn cùng với Mã tài sản của tài khoản mới tạo cho từng trang trên trang web của người dùng.
  • Tự động định cấu hình Thuộc tính của người dùng bằng API Quản lý.
  • Cung cấp báo cáo cho người dùng trong sản phẩm của bạn (ví dụ: trong bảng điều khiển quản trị) bằng cách sử dụng API Nhúng hoặc API Báo cáo chính.

Luồng người dùng

Phần này mô tả các cân nhắc về cách triển khai liên quan đến các bước trong quy trình tạo tài khoản từ góc độ của người dùng.

Quy trình bắt đầu bằng việc người dùng đưa ra 2 lựa chọn sau để bật tính năng phân tích cho tài sản của họ:

  1. Tạo tài khoản Google Analytics
  2. Sử dụng tài khoản Google Analytics hiện có. (Lưu ý: Quy trình này không được đề cập trong tài liệu này. Hãy xem API Quản lý để biết thông tin chi tiết về cách truy cập vào dữ liệu cấu hình Google Analytics của người dùng.)

Khi tạo một tài khoản Google Analytics mới, bạn phải gửi thông tin cùng với yêu cầu cấp phép, chẳng hạn như tên tài khoản, tên thuộc tính, v.v. Tuỳ thuộc vào thông tin bạn có về người dùng và quy trình ưu tiên mà bạn muốn cho họ thấy, có 3 lựa chọn chính để bắt đầu luồng người dùng sau khi người dùng nhấp vào "tạo tài khoản":

Yêu cầu thông tin chi tiết về tài khoản sau khi uỷ quyền

Trong trường hợp này, người dùng sẽ được yêu cầu cung cấp thông tin tài khoản ở giữa quá trình. Quy trình sẽ có dạng như sau:

  1. Người dùng được chuyển hướng đến Dịch vụ Tài khoản Google để xem quy trình OAuth 2.0. Nếu người dùng chưa có Tài khoản Google hoặc chưa đăng nhập, họ sẽ được yêu cầu tạo Tài khoản Google hoặc đăng nhập.
  2. Người dùng được nhắc cho phép ứng dụng "Tạo tài khoản Google Analytics".
  3. Người dùng chấp nhận yêu cầu cấp quyền cho ứng dụng.
  4. Người dùng được chuyển hướng đến Nhà cung cấp dịch vụ. Lưu ý rằng nếu người dùng từ chối cho phép thì họ vẫn được chuyển hướng trở lại Nhà cung cấp dịch vụ.
  5. Một biểu mẫu sẽ được hiển thị cho người dùng để thu thập thông tin chi tiết về tài khoản cần tạo (ví dụ: Tên tài khoản, tên tài sản, tên hồ sơ, múi giờ, URL của trang web, v.v.)
  6. Người dùng điền thông tin vào biểu mẫu rồi gửi biểu mẫu rồi được chuyển hướng đến Google/hiển thị Điều khoản dịch vụ (TOS) của Google Analytics.
  7. Người dùng chấp nhận Điều khoản dịch vụ.
  8. Người dùng được chuyển hướng đến Nhà cung cấp dịch vụ và thấy một số thông báo thành công cho biết họ đã tạo thành công tài khoản Google Analytics có thông tin chi tiết về tài khoản và cách truy cập vào tài khoản đó. Lưu ý rằng nếu người dùng không chấp nhận Điều khoản dịch vụ, họ vẫn được chuyển hướng trở lại Nhà cung cấp dịch vụ.

Hỏi thông tin tài khoản trước khi uỷ quyền

Trong trường hợp này, người dùng sẽ được yêu cầu cung cấp thông tin cấu hình của tài khoản sắp được tạo. Quy trình sẽ có dạng như sau:

  1. Trên trang web Nhà cung cấp dịch vụ, một biểu mẫu sẽ được hiển thị cho người dùng để thu thập thông tin chi tiết về tài khoản cần tạo (ví dụ: Tên tài khoản, tên tài sản, tên hồ sơ, múi giờ, URL của trang web).
  2. Người dùng điền vào biểu mẫu, nhấp vào nút gửi và được chuyển hướng đến Dịch vụ Tài khoản Google cho quy trình OAuth 2.0. Nếu người dùng chưa có Tài khoản Google hoặc chưa đăng nhập, họ sẽ được yêu cầu tạo một Tài khoản Google hoặc đăng nhập.
  3. Người dùng được nhắc cho phép ứng dụng "Tạo tài khoản Google Analytics".
  4. Người dùng chấp nhận các quyền được yêu cầu cho ứng dụng.
  5. Người dùng được chuyển hướng đến Nhà cung cấp dịch vụ.
  6. Người dùng được chuyển hướng đến Google/xem Điều khoản dịch vụ (TOS) của Google Analytics.
  7. Người dùng chấp nhận Điều khoản dịch vụ.
  8. Người dùng được chuyển hướng đến Nhà cung cấp dịch vụ và thấy một số thông báo thành công cho biết họ đã tạo thành công tài khoản Google Analytics có thông tin chi tiết về tài khoản và cách truy cập vào tài khoản đó.

Điền sẵn thông tin tài khoản hoặc bỏ qua biểu mẫu

Nếu đã có thông tin về tài khoản người dùng (ví dụ: URL của trang web, tên trang web, múi giờ, v.v.), thì bạn có thể đơn giản hoá cả hai lựa chọn ở trên bằng cách:

  • Điền sẵn vào biểu mẫu và cho phép người dùng chỉnh sửa nếu họ muốn
  • Bỏ qua hoàn toàn bước biểu mẫu và tự động tạo tài khoản bằng thông tin hiện có.