Định cấu hình ứng dụng trong SDK Google Workspace Marketplace

Trang này giải thích cách sử dụng SDK Google Workspace Marketplace để định cấu hình và quản lý ứng dụng của bạn trên Google Workspace Marketplace.

Để người dùng có thể sử dụng ứng dụng của bạn, bạn cần thiết lập ứng dụng đó trong Marketplace SDK. Marketplace SDK là một bộ công cụ cho phép bạn tạo và kiểm soát ứng dụng của mình trên Marketplace. Bạn sử dụng Marketplace SDK để quản lý các chế độ cài đặt của Marketplace, chẳng hạn như:

  • Ứng dụng của bạn có được cung cấp cho một tổ chức Google Workspace cụ thể (ứng dụng riêng tư) hay cho tất cả người dùng Marketplace (ứng dụng công khai)
  • Các loại người dùng Marketplace có thể cài đặt ứng dụng của bạn
  • (Các) ứng dụng Google Workspace mà ứng dụng của bạn tích hợp
  • Các phạm vi OAuth mà ứng dụng của bạn yêu cầu
  • Thông tin về người tạo và duy trì ứng dụng

Bất kể bạn xuất bản ứng dụng ở chế độ riêng tư hay công khai, bạn đều phải sử dụng Marketplace SDK để quản lý ứng dụng của mình trên Marketplace.

Bật Marketplace SDK

Nếu bạn chưa làm việc này, hãy bật Marketplace SDK trong dự án trên đám mây của Google Cloud.

Mở dự án trên đám mây trong Cloud Console

Nếu chưa mở, hãy mở dự án trên đám mây mà bạn dự định dùng cho mẫu này:

  1. Trong Google Cloud Console, hãy chuyển đến trang Chọn một dự án.

    Chọn một dự án trên đám mây

  2. Chọn dự án trên Google Cloud mà bạn muốn sử dụng. Hoặc nhấp vào Tạo dự án rồi làm theo hướng dẫn trên màn hình. Nếu tạo một dự án trên Google Cloud, bạn có thể cần phải bật tính năng thanh toán cho dự án trên đám mây.

Bật Marketplace SDK

Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.

  • Trong Cloud Console, hãy bật Google Workspace Marketplace SDK.

    Bật SDK

Xác định chế độ cài đặt cấu hình cho ứng dụng của bạn

Thông tin tham khảo sau đây mô tả các chế độ cài đặt có trên trang Cấu hình ứng dụng của SDK Marketplace.

Chọn người có thể xem và cài đặt ứng dụng của bạn

Khi định cấu hình ứng dụng, bạn chỉ định những người dùng có thể truy cập vào ứng dụng của bạn bằng các chế độ cài đặt sau:

  • Khả năng hiển thị của ứng dụng: Nếu bạn đang xuất bản một ứng dụng trong một tổ chức Google Workspace, thì trang thông tin ứng dụng của bạn sẽ ở trạng thái chưa công khai, hiển thị cho tất cả người dùng trong tổ chức của bạn hoặc bất kỳ ai sử dụng Google Workspace.
  • Chế độ cài đặt khi cài đặt: Ứng dụng có chỉ được cài đặt bởi quản trị viên Google Workspace hay không.

Bất kể chế độ cài đặt mà bạn chỉ định trong trang thông tin ứng dụng, những người dùng thuộc một tổ chức Google Workspace có thể không khám phá, cài đặt hoặc sử dụng được ứng dụng của bạn dựa trên các chế độ cài đặt do quản trị viên của họ đặt. Quản trị viên có thể ảnh hưởng đến phạm vi cung cấp ứng dụng của bạn theo những cách sau:

  • Kiểm soát việc người dùng có thể xem ứng dụng trên Marketplace và cài đặt ứng dụng thay mặt cho người dùng hay không.
  • Sử dụng danh sách cho phép để quản lý và tuyển chọn các ứng dụng cho tổ chức của họ. Nếu bạn đang phát triển một ứng dụng cho tổ chức sử dụng danh sách cho phép, hãy trao đổi với quản trị viên về việc thêm ứng dụng vào danh sách cho phép.
  • Tắt một số ứng dụng của Google Workspace, chẳng hạn như xoá quyền truy cập vào Google Chat, các ứng dụng Google Chat hoặc cả hai. Trong những trường hợp này, người dùng sẽ không thể cài đặt ứng dụng của bạn từ Marketplace.

Để tìm hiểu cách quản trị viên quản lý quyền truy cập vào Marketplace, hãy xem tài liệu Trợ giúp dành cho quản trị viên Marketplace.

Chế độ cài đặt hiển thị ứng dụng

Bạn sẽ thấy lựa chọn Khả năng hiển thị của ứng dụng nếu đang sử dụng tài khoản Google Workspace (tài khoản do tổ chức nơi bạn làm việc hoặc trường học tạo). Nếu đang dùng tài khoản người dùng cá nhân (tài khoản có đuôi "@gmail.com"), bạn chỉ có thể xuất bản công khai.

  • Công khai: Những người bên ngoài miền của bạn có thể tìm thấy và cài đặt ứng dụng này. Nếu bạn chọn chế độ hiển thị công khai, Google sẽ xem xét và phê duyệt trang thông tin ứng dụng của bạn trước khi xuất bản.
  • Riêng tư: Chỉ những người trong miền của bạn mới có thể tìm thấy và cài đặt ứng dụng của bạn.

Nếu bạn chọn xuất bản ở chế độ Không công khai, trang thông tin ứng dụng sẽ không xuất hiện trong kết quả duyệt xem hoặc kết quả tìm kiếm. Người dùng chỉ có thể truy cập vào trang cửa hàng của ứng dụng bằng URL trực tiếp.

Nếu muốn giới hạn những quốc gia và khu vực mà bạn cung cấp ứng dụng, bạn có thể thiết lập trong phần Phân phối khi tạo trang thông tin trên Cửa hàng Play.

Chế độ cài đặt lượt cài đặt ứng dụng

Lựa chọn Cài đặt khi cài đặt xác định xem người dùng hoặc quản trị viên Google Workspace có thể cài đặt ứng dụng của bạn từ trang thông tin của bạn trên Cửa hàng Play trên Marketplace hay không.

  • Cài đặt cho cá nhân + Quản trị viên (mặc định): Người dùng cá nhân hoặc quản trị viên có thể cài đặt ứng dụng này cho miền, đơn vị tổ chức hoặc một nhóm người dùng. Các chính sách miền của người dùng có thể ngăn họ cài đặt ứng dụng ngay cả khi bạn đã bật chế độ cài đặt riêng lẻ.
  • Chỉ quản trị viên mới có thể cài đặt: Chỉ quản trị viên mới có thể cài đặt ứng dụng này cho miền, đơn vị tổ chức hoặc một nhóm người dùng. Ứng dụng của bạn chỉ xuất hiện trong kết quả tìm kiếm trên Google Workspace Marketplace đối với quản trị viên và những người chưa đăng nhập vào Tài khoản Google của họ. Chọn lựa chọn này nếu ứng dụng của bạn yêu cầu cài đặt miền.

Các chế độ cài đặt phổ biến về việc cài đặt và hiển thị

Bảng sau đây tóm tắt một số lựa chọn cấu hình ứng dụng phổ biến để cài đặt và hiển thị:

Người dùng ứng dụng mục tiêu Chế độ cài đặt khả năng hiển thị của ứng dụng Chế độ cài đặt Cài đặt ứng dụng Những ai có thể cài đặt ứng dụng của tôi? Ai có thể sử dụng ứng dụng của tôi?
Đối với các ứng dụng được tạo cho một tổ chức sử dụng Google Workspace  
Một số người dùng cụ thể trong tổ chức của bạn Riêng tư và Không công khai Cài đặt riêng lẻ + Cài đặt quản trị Nếu được phép, bất cứ ai trong tổ chức của bạn có URL trang thông tin ứng dụng. Nếu được phép, bất cứ ai trong tổ chức của bạn có URL trang thông tin ứng dụng.
Tổ chức của bạn Riêng tư Cài đặt riêng lẻ + Cài đặt quản trị Nếu được phép, bất kỳ ai trong tổ chức của bạn. Nếu được phép, bất kỳ ai trong tổ chức của bạn.
Tổ chức của bạn Riêng tư Chỉ quản trị viên Quản trị viên Người dùng đã được quản trị viên cài đặt ứng dụng.
Đối với những ứng dụng mà người dùng bên ngoài một tổ chức Google Workspace cụ thể có thể sử dụng  
Người dùng trong các tổ chức Google Workspace Công khai Chỉ quản trị viên Quản trị viên Người dùng đã được quản trị viên cài đặt ứng dụng.
Tất cả người dùng Google Workspace Công khai Cài đặt riêng lẻ + Cài đặt quản trị
  • Bất kỳ ai sử dụng các ứng dụng của Google Workspace cho mục đích cá nhân.
  • Nếu được phép, người dùng trong các tổ chức Google Workspace.
  • Bất kỳ ai sử dụng các ứng dụng của Google Workspace cho mục đích cá nhân.
  • Nếu được phép, người dùng trong các tổ chức Google Workspace.

Xác định cách ứng dụng của bạn tích hợp với các ứng dụng của Google Workspace

Lựa chọn Tích hợp ứng dụng cho phép bạn chọn các dịch vụ của Google Workspace mà ứng dụng hoặc tiện ích bổ sung của bạn được thiết kế để hoạt động cùng, chẳng hạn như một tiện ích bổ sung của Google Workspace hoặc một ứng dụng Google Chat. Bạn phải chọn ít nhất một lựa chọn. Trong một số trường hợp, bạn có thể thêm nhiều tính năng tích hợp ứng dụng vào trang thông tin ứng dụng. Xem phần Liệt kê các chế độ tích hợp ứng dụng với nhau.

Đối với mỗi tiện ích bổ sung của Google Workspace, trang này sẽ hiển thị trạng thái xuất bản của từng sản phẩm lưu trữ mà tiện ích bổ sung đó hỗ trợ. Điều này giúp bạn biết được những tính năng tích hợp mà người dùng có thể sử dụng. Có thể có các trạng thái tích hợp ứng dụng sau:

  • Unsaved: Bạn đã thêm hoặc sửa đổi một chế độ tích hợp nhưng chưa lưu các thay đổi trên thẻ Cấu hình ứng dụng.
  • Draft: Các thay đổi của bạn đã được lưu nhưng chưa được xuất bản.
  • Under review: Bạn đã gửi bản tích hợp ứng dụng mới cập nhật để chúng tôi xem xét.
  • Published: Thông tin tích hợp ứng dụng của bạn có trong trang thông tin trên Marketplace.

Tuỳ thuộc vào các chế độ tích hợp ứng dụng mà bạn chọn, bạn có thể cần cung cấp thêm thông tin và bật các API có liên quan trong dự án trên đám mây của Google. Bảng sau đây mô tả chế độ thiết lập bổ sung cần thiết cho từng trường hợp:

Tiện ích bổ sung cho Google Workspace

Để xuất bản một tiện ích bổ sung Google Workspace, bạn phải cung cấp mã nhận dạng triển khai của tiện ích bổ sung đó.

Để tìm mã nhận dạng lượt triển khai trong Apps Script, hãy làm theo các bước sau:

  1. Mở tiện ích bổ sung Google Workspace trong trình chỉnh sửa Apps Script.
  2. Nhấp vào Triển khai > Quản lý các phiên bản triển khai.
  3. Bên dưới mã nhận dạng triển khai, hãy nhấp vào Sao chép.

Để tìm mã nhận dạng lượt triển khai cho một tiện ích bổ sung HTTP, hãy làm theo các bước sau:

  1. Trên trang Cấu hình ứng dụng trong mục "Tiện ích bổ sung cho Google Workspace", hãy nhấp vào HTTP hoặc các hoạt động triển khai khác > Chọn Triển khai.
  2. Chọn bản triển khai mà bạn muốn xuất bản.
  3. Nhấp vào Chọn.

Tiện ích bổ sung dành cho trình chỉnh sửa (Tài liệu, Trang tính, Trang trình bày, Biểu mẫu)

Để xuất bản một tiện ích bổ sung cho Trình chỉnh sửa, bạn phải cung cấp mã tập lệnh dự án và phiên bản mà bạn muốn xuất bản.

Để tìm mã tập lệnh dự án, hãy làm theo các bước sau:

  1. Mở tiện ích bổ sung trong trình chỉnh sửa Apps Script.
  2. Ở bên trái, hãy nhấp vào Cài đặt dự án .
  3. Trong mục "Mã nhận dạng", hãy sao chép mã nhận dạng tập lệnh.

Để tìm phiên bản, hãy làm theo các bước sau:

  1. Mở tiện ích bổ sung trong trình chỉnh sửa Apps Script.
  2. Ở trên cùng bên phải, hãy nhấp vào Triển khai > Quản lý hoạt động triển khai.
  3. Số phiên bản nằm trong phần "Cấu hình".

Ứng dụng Google Chat

Để xuất bản một ứng dụng Google Chat có tính tương tác, hãy xem tài liệu sau:

Ứng dụng Drive

Để xuất bản một ứng dụng Drive, bạn phải bật và định cấu hình API Google Drive.

Ứng dụng web

Để xuất bản một ứng dụng web, bạn phải cung cấp URL điều hướng chung của ứng dụng đó, tức là URL trỏ đến ứng dụng web từ trình đơn ứng dụng Google . Ứng dụng web của bạn phải đang trong giai đoạn phát hành công khai và hoạt động đầy đủ.

Khi điền thông tin vào trang Thông tin trên Cửa hàng Play, bạn phải cung cấp các biểu tượng bổ sung có kích thước 96x96 và 48x48 pixel.

Nếu bạn tạo ứng dụng web trong Apps Script, hãy làm theo các bước sau để lấy URL điều hướng chung:

  1. Mở tiện ích bổ sung Google Workspace trong trình chỉnh sửa Apps Script.
  2. Nhấp vào Triển khai > Triển khai mới.
  3. Trong phần "Chọn loại", hãy nhấp vào Ứng dụng web.
  4. Điền thông tin vào các lựa chọn rồi nhấp vào Triển khai.
  5. Nhấp vào Sao chép.

Chỉ định cấp độ truy cập mà ứng dụng của bạn yêu cầu

Trong phần Phạm vi OAuth, hãy cung cấp danh sách đầy đủ các phạm vi OAuth 2.0 mà ứng dụng của bạn yêu cầu. Phạm vi OAuth mà bạn nhập ở đây phải khớp với phạm vi mà bạn hiển thị trong màn hình xin phép bằng OAuth và nếu có, tệp kê khai Apps Script.

Nếu bạn thêm nhiều mối tích hợp ứng dụng, hãy nhớ thêm các phạm vi của từng mối tích hợp vào trang Cấu hình ứng dụng Marketplace SDK và màn hình xin phép bằng OAuth.

Luôn sử dụng phạm vi hẹp nhất có thể (ví dụ: không thêm phạm vi đầy đủ của Drive nếu bạn chỉ cần phạm vi chỉ đọc).

Đối với các dự án Apps Script, hãy xem bài viết Phạm vi uỷ quyền để biết thêm thông tin.

Cung cấp thông tin về nhà phát triển ứng dụng

Trong phần Thông tin về nhà phát triển, hãy điền thông tin liên hệ và các thông tin khác. Các trường này xuất hiện trên trang trang thông tin trên Cửa hàng Play của ứng dụng.

Trường
Trạng thái của người bán

Theo luật bảo vệ người tiêu dùng, người tiêu dùng tại Khu vực kinh tế Châu Âu (EEA) phải được thông báo liệu người bán trên trang web thương mại là người bán hay pháp nhân phi thương mại:

  • Thương nhân: Thương nhân là người hành động vì các mục đích liên quan đến hoạt động thương mại, kinh doanh, tay nghề hoặc nghề nghiệp; hoặc nhân danh hoặc thay mặt cho một thương nhân.
  • Pháp nhân phi thương mại: Pháp nhân phi thương mại (người tiêu dùng) là người hành động vì mục đích không chuyên nghiệp.

Nếu bạn không chỉ định, "Trạng thái người bán không xác định" sẽ xuất hiện trên trang trang thông tin trên Cửa hàng Play của ứng dụng.

Tên nhà phát triển Tên sẽ hiển thị dưới dạng tác giả của ứng dụng. Nếu bạn là người bán, hãy cung cấp tên thương mại hoặc tên pháp lý của bạn.
Địa chỉ gửi thư của nhà phát triển

Bắt buộc đối với nhà giao dịch. Không thu thập đối với pháp nhân phi thương mại.

Vị trí của doanh nghiệp bạn. Nhập một địa chỉ gửi thư hợp lệ để chúng tôi có thể liên hệ với bạn.

URL trang web của nhà phát triển Trang web mô tả bạn (hoặc tổ chức của bạn) là nhà phát triển.
Email của nhà phát triển

Địa chỉ email dùng làm đầu mối liên hệ. Nội dung này không có trong trang thông tin ứng dụng của bạn. Đảm bảo địa chỉ email này luôn được cập nhật vì địa chỉ này được dùng để:

  • Nếu Google cần liên hệ với nhà phát triển, chẳng hạn như trong quá trình xem xét ứng dụng.
  • Gửi ý kiến phản hồi từ các tiện ích bổ sung của Trình chỉnh sửa nếu không có URL Báo cáo vấn đề trên trang Thông tin trên Cửa hàng.
URL của trang web ứng dụng Không bắt buộc. Trang web mô tả thêm về ứng dụng của bạn.

Lưu chế độ cài đặt cấu hình ứng dụng trong Marketplace SDK

Sử dụng thông tin trong phần trước, hãy lưu cấu hình ứng dụng của bạn trong Marketplace SDK:

  1. Trong bảng điều khiển Cloud Console của Google Cloud, hãy chuyển đến trang Cấu hình ứng dụng của Marketplace SDK:

    Chuyển đến trang Cấu hình Marketplace SDK

  2. Điền vào từng phần dựa trên những gì bạn đã xác định trong phần trước.

  3. Nhấp vào Lưu bản nháp.

  4. (Không bắt buộc) Bạn có thể nhận số liệu phân tích về mức sử dụng ứng dụng trong Google Analytics. Để làm như vậy, hãy thêm mã Google Analytics vào Marketplace SDK.

    1. Chuyển đến thẻ Analytics.
    2. Nhập mã nhận dạng Google Analytics của bạn.
    3. Nhấp vào Lưu.

Khắc phục sự cố

Phần này mô tả các vấn đề thường gặp mà bạn có thể gặp phải.

Thiếu các quyền bắt buộc khi xuất bản ứng dụng lên Marketplace

Bạn không thể xuất bản ứng dụng trên Marketplace vì các lần thử định cấu hình ứng dụng trên trang Cấu hình ứng dụng của Marketplace SDK đều thất bại với thông báo lỗi sau:

You are missing at least one of the following required permissions: Project workspacemarketplace.appconfiguration.view / workspacemarketplace.appconfiguration.update

Lỗi này xảy ra khi bạn bật Marketplace SDK API và khi sử dụng một vai trò IAM khác ngoài Editor hoặc Owner.

Để giải quyết lỗi này, hãy triển khai một trong những giải pháp sau:

  • Yêu cầu chủ sở hữu dự án chỉ định vai trò roles/appmetadata.workspaceMarketplaceAppConfigurationAdmin cho tài khoản bị thiếu quyền để cho phép tài khoản đó định cấu hình và quản lý ứng dụng trong Marketplace SDK.

  • Yêu cầu chủ sở hữu dự án thêm các quyền còn thiếu vào một vai trò tuỳ chỉnh thông qua trang IAM & Admin > Roles trong Google Cloud Console. Sau đó, hãy chỉ định vai trò tuỳ chỉnh cho tài khoản bị thiếu quyền.

  • Bạn có thể dùng roles/editor hoặc roles/owner cơ bản để xuất bản ứng dụng. Tuy nhiên, tài liệu Sử dụng IAM một cách an toàn coi đây là một phương pháp không hay vì người dùng không thể dễ dàng hạn chế quyền chỉnh sửa đối với các tài nguyên khác trong dự án.