Định cấu hình phân phối có điều kiện

Phương thức phân phối có điều kiện hỗ trợ bạn đặt một số yêu cầu về cấu hình thiết bị để hệ thống tự động tải các mô-đun tính năng xuống trong quá trình cài đặt ứng dụng. Ví dụ: bạn có thể định cấu hình cho một mô-đun tính năng có chức năng thực tế tăng cường (AR) khi cài đặt ứng dụng dành cho những thiết bị hỗ trợ AR.

Cơ chế phân phối này hiện hỗ trợ việc kiểm soát lượt tải xuống của một mô-đun tại thời điểm cài đặt ứng dụng dựa trên các cấu hình thiết bị sau:

Nếu thiết bị không đáp ứng mọi yêu cầu mà bạn đưa ra, thì mô-đun sẽ không được tải xuống tại thời điểm cài đặt ứng dụng. Tuy nhiên, ứng dụng của bạn sau đó có thể yêu cầu tải mô-đun xuống theo yêu cầu bằng Thư viện Play Core.

Trước khi bắt đầu, hãy đảm bảo bạn đang sử dụng Android Studio phiên bản 3.5 trở lên. Các phần sau sẽ cho bạn biết cách thêm hỗ trợ phân phối có điều kiện đến các mô-đun tính năng.

Thêm mô-đun mới với các tùy chọn phân phối có điều kiện

Cách dễ nhất để tạo một mô-đun tính năng mới với tùy chọn phân phối có điều kiện là sử dụng trình hướng dẫn New Module (Mô-đun mới) như sau:

  1. Để mở hộp thoại New Module (Mô-đun mới), chọn File > New > New Module (Tệp > Mới > Mô-đun mới) từ thanh trình đơn.
  2. Trong hộp thoại, hãy chọn Dynamic Feature Module (Mô-đun tính năng động) rồi nhấp vào Next (Tiếp theo).
  3. Định cấu hình mô-đun như bạn thường làm và nhấp vào Next (Tiếp theo).

  4. Trong phần Module Download Options (Tùy chọn tải mô-đun xuống), hãy hoàn thành các thao tác sau:

    1. Chỉ định Tên mô-đun (tối đa 50 ký tự). Nền tảng sử dụng tiêu đề này để xác định mô-đun cho người dùng, chẳng hạn như khi xác nhận xem người dùng có muốn tải mô-đun xuống hay không. Vì lý do này, mô-đun cơ sở của ứng dụng phải bao gồm cả tên mô-đun dưới dạng tài nguyên chuỗi mà bạn có thể dịch. Khi tạo mô-đun bằng Android Studio, IDE thêm tài nguyên chuỗi vào mô-đun cơ sở cho bạn và chèn nội dung sau vào tệp kê khai của mô-đun tính năng:

      <dist:module
    ...
    dist:title="@string/feature_title">
</dist:module>

    2. Trong trình đơn thả xuống bên dưới phần Install-time inclusion (Bao gồm thời gian cài đặt), chọn Only include module at app install for devices with specified features (Chỉ bao gồm mô-đun lúc cài đặt ứng dụng cho các thiết bị có các tính năng cụ thể) để tạo một mô-đun đi kèm ứng dụng của bạn tại thời điểm cài đặt ứng dụng chỉ trên thiết bị có cấu hình nhất định mà bạn có thể chỉ định, chẳng hạn như các tính năng thiết bị hoặc quốc gia. Android Studio sẽ chèn nội dung sau vào tệp kê khai của mô-đun để phản ánh lựa chọn của bạn:

      <dist:module ... >
  <dist:delivery>
      <dist:install-time>
          <dist:conditions>
              <!-- If you specify conditions, as described in the steps
                   below, the IDE includes them here. -->
          </dist:conditions>
      </dist:install-time>
  </dist:delivery>
</dist:module>

    3. Nếu bạn muốn giới hạn việc tải mô-đun xuống tự động ở một số quốc gia hoặc mức API tối thiểu, hãy nhấp vào Finish (Hoàn tất) để hoàn tất việc tạo mô-đun và sau đó tham khảo nội dung phần cách xác định các điều kiện dựa trên quốc gia hoặc cấp độ API tối thiểu. Nếu không, hãy nhấp vào + device feature (+tính năng thiết bị) để thêm một tính năng mà thiết bị yêu cầu để tải mô-đun xuống tại thời điểm cài đặt.

    4. Bên cạnh device-feature (tính năng thiết bị), hãy chọn một trong các lựa chọn sau từ trình đơn thả xuống và chỉ định giá trị cho lựa chọn đó:

      • Tên: Cho phép bạn chỉ định một tính năng phần cứng hoặc phần mềm mà thiết bị cần có để tải mô-đun xuống tại thời điểm cài đặt. Các tính năng mà chế độ phân phối có điều kiện hỗ trợ cũng giống như các tính năng được liệt kê dưới dạng hằng số FEATURE_* bởi PackageManager. Nếu bạn chọn tùy chọn này, hãy bắt đầu nhập một phần bất kỳ trong giá trị không đổi của tính năng đó, chẳng hạn như "bluetooth", trong trường bên cạnh trình đơn thả xuống, và chọn một trong các đề xuất xuất hiện.
      • Phiên bản OpenGL ES: Cho phép bạn chỉ định một phiên bản OpenGL ES mà thiết bị yêu cầu để tải mô-đun xuống tại thời điểm cài đặt. Nếu bạn chọn tùy chọn này, hãy bắt đầu nhập phiên bản, chẳng hạn như "0x00030001", vào trường bên cạnh trình đơn thả xuống và chọn một trong các đề xuất xuất hiện.

    5. Nếu bạn muốn thêm nhiều điều kiện dựa trên các tính năng thiết bị có sẵn, hãy nhấp vào + device feature (+ tính năng thiết bị) cho từng điều kiện tính năng thiết bị mà bạn muốn chỉ định.

    6. Chọn hộp bên cạnh Fusing (Hợp nhất) nếu bạn muốn mô-đun này có sẵn cho các thiết bị chạy Android 4.4 (API cấp 20) trở xuống và được bao gồm trong nhiều APK. Điều này có nghĩa là bạn có thể bật hành vi phân phát theo yêu cầu cho mô-đun này và tắt tính năng hợp nhất để bỏ mô-đun này khỏi các thiết bị không hỗ trợ tải xuống và cài đặt tệp APK phân tách. Android Studio sẽ chèn nội dung sau vào tệp kê khai của mô-đun để phản ánh lựa chọn của bạn:

      <dist:module ...>
    <dist:fusing dist:include="true | false" />
</dist:module>

  5. Khi bạn định cấu hình xong các tùy chọn tải mô-đun xuống, nhấp vào Finish (Hoàn tất).

Lưu ý trình bổ trợ Gradle của Android không hỗ trợ chạy lint (tìm lỗi mã nguồn) từ các mô-đun tính năng động. Việc chạy lint (trình tìm lỗi mã nguồn) từ mô-đun ứng dụng tương ứng sẽ chạy trình tìm lỗi mã nguồn trên các mô-đun tính năng động của ứng dụng và đưa tất cả sự cố vào báo cáo tìm lỗi mã nguồn của ứng dụng.

Thêm các tùy chọn phân phối có điều kiện vào mô-đun tính năng hiện có

Bạn có thể dễ dàng thêm các tùy chọn phân phối có điều kiện vào một mô-đun tính năng hiện có thông qua tệp kê khai của mô-đun. Tuy nhiên, trước tiên, bạn nên đọc về khả năng tương thích của các lựa chọn phân phối có điều kiện với các lựa chọn phân phối khác mà bạn có thể đã bật.

Để bắt đầu, trước tiên bạn cần di chuyển tệp kê khai của mình sang phần tử <dist:delivery> mới. Đoạn mã dưới đây cho thấy ví dụ về cú pháp cũ:

<!-- This is the old syntax. -->
<dist:module
  dist:title="@string/feature_title" dist:onDemand="true">
  <dist:fusing dist:include="true"/>
</dist:module>

Các tùy chọn phân phối ở trên hiện được chỉ định như sau.

<dist:module
  dist:title="@string/feature_title">
  <dist:delivery>
      <dist:on-demand/>
  </dist:delivery>
  <dist:fusing dist:include="true"/>
</dist:module>

Sau đó, bạn có thể bao gồm các tùy chọn phân phối có điều kiện dựa trên các tính năng của thiết bị như sau.

<dist:module
    dist:title="@string/feature_title">
    <dist:delivery>
      <dist:on-demand/>
      <dist:install-time>
        <dist:conditions>
          <!-- Requires that the device support AR to download the module at
          app install-time.  -->
          <dist:device-feature dist:name="android.hardware.camera.ar"/>
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
    <dist:fusing dist:include="true"/>
</dist:module>

Phần dưới đây thảo luận về các tùy chọn phân phối có điều kiện khác, chẳng hạn như theo quốc gia hoặc cấp API tối thiểu.

Khả năng tương thích với các tùy chọn tải xuống mô-đun khác

Bởi vì các mô-đun tính năng cung cấp nhiều tùy chọn để định cấu hình cách mỗi tính năng được phân phối đến thiết bị của người dùng, nên cần hiểu rõ các tùy chọn phân phối có điều kiện chịu ảnh hưởng như thế nào bởi các thiết lập khác. Bảng sau đây tóm tắt khả năng tương thích của phương thức phân phối có điều kiện với các tùy chọn tải xuống mô-đun khác.

Tùy chọn tải mô-đun xuống Khả năng tương thích với tính năng phân phối có điều kiện
Kết hợp (<dist:fusing dist:include="true"/>) Nếu một mô-đun đặt tùy chọn này thành true (đúng), Google Play sẽ không tuân theo các tùy chọn phân phối có điều kiện mà bạn chỉ định khi triển khai ứng dụng của bạn cho các thiết bị chạy API cấp 19 trở xuống. Nghĩa là, các mô-đun tính năng bật tính năng kết hợp luôn có trong thời gian cài đặt của thiết bị chạy API cấp 19 trở xuống.
Hỗ trợ phiên bản tức thì (<dist:module dist:instant="true"/>) Tùy chọn phân phối có điều kiện không được hỗ trợ cho các mô-đun tính năng hỗ trợ phiên bản tức thì.
Theo yêu cầu (<dist:on-demand/>) Theo mặc định, nếu bạn chỉ định các tùy chọn phân phối có điều kiện, mô-đun cũng có sẵn theo yêu cầu.

Định rõ điều kiện theo quốc gia

Phân phối có điều kiện cũng cho phép bạn chỉ định quốc gia bạn muốn loại trừ (hoặc bao gồm) khi tải xuống mô-đun tại thời điểm cài đặt ứng dụng. Việc chỉ định điều kiện này có thể hữu ích chẳng hạn trong trường hợp nếu mô-đun của bạn triển khai phương thức thanh toán không có sẵn tại một số khu vực nhất định.

Trong trường hợp này, quốc gia của thiết bị thường được xác định theo địa chỉ thanh toán của người dùng đã đăng ký trên tài khoản Google Play của họ.

Để chỉ định quốc gia cho mô-đun của bạn, hãy đưa nội dung sau vào tệp kê khai của mô-đun tính năng.

<dist:conditions>
   <!-- Set to "true" to specify countries to exclude from downloading
   this module at app install-time. By default, modules are available
   for download to all user countries. -->
  <dist:user-countries dist:exclude="true">
    <!-- Specifies the two-letter  CLDR country code for regions that should
    not download the module at app install-time. -->
    <dist:country dist:code="CN"/>
    <dist:country dist:code="HK"/>
  </dist:user-countries>
</dist:conditions>

Định rõ điều kiện cho cấp độ API

Việc chỉ định một điều kiện dựa trên cấp độ API của thiết bị có thể hữu ích nếu một mô-đun tính năng phụ thuộc vào các API chỉ có sẵn ở một số phiên bản nền tảng Android.

Để đặt điều kiện dựa trên cấp độ API tối thiểu hoặc tối đa của thiết bị, hãy đưa những nội dung sau vào tệp kê khai của mô-đun tính năng.

<dist:conditions>
    <!-- Specifies the minimum API level that the device must satisfy
         in order to download your module at app install-time. The API level you
         specify must be greater or equal to the module's own minSdkVersion. -->
   <dist:min-sdk dist:value="21"/>
    <!-- Specifies the maximum API level that the device cannot exceed
         in order to download your module at app install-time. The API level you
         specify must be less than or equal to the module's own maxSdkVersion. -->
   <dist:max-sdk dist:value="24"/>
</dist:conditions>