<uses-feature>

cú pháp:

<uses-feature
  android:name="string"
  android:required=["true" | "false"]
  android:glEsVersion="integer" />

có trong:

<manifest>

mô tả:

Khai báo một tính năng phần cứng hoặc phần mềm mà ứng dụng sử dụng.

Mục đích của việc khai báo <uses-feature> là để thông báo cho mọi thực thể bên ngoài về tập hợp tính năng phần cứng và phần mềm mà ứng dụng phụ thuộc. Phần tử này cung cấp thuộc tính required cho phép bạn chỉ định rằng ứng dụng buộc phải có tính năng đã khai báo thì mới hoạt động được, hoặc rằng ứng dụng nên có tính năng đó nhưng vẫn hoạt động được nếu không có.

Vì khả năng hỗ trợ tính năng có thể thay đổi tuỳ theo thiết bị Android, nên phần tử <uses-feature> đóng vai trò quan trọng trong việc cho phép ứng dụng mô tả các tính năng phụ thuộc vào thiết bị mà ứng dụng sử dụng.

Tập hợp các tính năng có sẵn mà ứng dụng khai báo phải tương ứng với tập hợp hằng số tính năng do PackageManager của Android cung cấp. Bạn có thể xem danh sách các hằng số tính năng ở phần Tài liệu tham khảo về tính năng trong tài liệu này.

Bạn phải chỉ định từng tính năng trong một phần tử <uses-feature> riêng. Như vậy, nếu yêu cầu nhiều tính năng, ứng dụng sẽ phải khai báo nhiều phần tử <uses-feature>. Ví dụ: một ứng dụng yêu cầu cả tính năng Bluetooth và máy ảnh trong thiết bị sẽ khai báo 2 phần tử sau:

<uses-feature android:name="android.hardware.bluetooth" android:required="true" />
<uses-feature android:name="android.hardware.camera.any" android:required="true" />

Nhìn chung, bạn cần phải khai báo các phần tử <uses-feature> cho tất cả các tính năng mà ứng dụng yêu cầu.

Các phần tử <uses-feature> đã khai báo chỉ mang tính chất cung cấp thông tin, nghĩa là hệ thống Android không tự kiểm tra xem thiết bị có hỗ trợ tính năng trên hay không trước khi cài đặt ứng dụng.

Tuy nhiên, các dịch vụ (chẳng hạn như Google Play) hoặc ứng dụng khác có thể kiểm tra phần khai báo <uses-feature> của ứng dụng trong quá trình xử lý hoặc tương tác với ứng dụng. Vì lý do này, bạn cần phải khai báo tất cả các tính năng mà ứng dụng sử dụng.

Đối với một số tính năng, có thể có một thuộc tính cụ thể cho phép bạn xác định phiên bản của tính năng, chẳng hạn như phiên bản OpenGL được dùng (khai báo bằng glEsVersion). Các tính năng khác có hoặc không có trên thiết bị, chẳng hạn như máy ảnh, được khai báo bằng thuộc tính name.

Mặc dù phần tử <uses-feature> chỉ được kích hoạt cho các thiết bị chạy API cấp 4 trở lên, nhưng bạn nên đưa những phần tử này vào tất cả các ứng dụng, ngay cả khi minSdkVersion là 3 trở xuống. Các thiết bị đang chạy những phiên bản cũ hơn của nền tảng sẽ bỏ qua phần tử này.

Lưu ý: Khi khai báo một tính năng, hãy nhớ rằng bạn cũng phải yêu cầu quyền truy cập tương ứng. Ví dụ: bạn cần yêu cầu quyền CAMERA để ứng dụng có thể truy cập vào API máy ảnh. Khi bạn yêu cầu quyền, ứng dụng sẽ có quyền truy cập vào phần cứng và phần mềm thích hợp. Việc khai báo các tính năng mà ứng dụng sử dụng giúp đảm bảo khả năng tương thích phù hợp của thiết bị.

thuộc tính:

android:name

Chỉ định một tính năng phần cứng hoặc phần mềm mà ứng dụng sử dụng dưới dạng chuỗi đặc tả (descriptor string). Các giá trị thuộc tính hợp lệ được liệt kê trong mục Tính năng phần cứng và Tính năng phần mềm. Các giá trị thuộc tính này phân biệt chữ hoa chữ thường.

android:required

Giá trị Boolean cho biết ứng dụng có yêu cầu tính năng được chỉ định trong android:name hay không.

• Việc khai báo android:required="true" cho một tính năng cho biết rằng ứng dụng không thể hoạt động hoặc không được thiết kế để hoạt động khi tính năng được chỉ định không có trên thiết bị.
• Việc khai báo android:required="false" cho một tính năng cho biết rằng ứng dụng sẽ sử dụng tính năng này nếu có trên thiết bị. Tuy nhiên, ứng dụng được thiết kế để hoạt động mà không có tính năng này, nếu cần.

Giá trị mặc định của android:required là "true".

android:glEsVersion

Phiên bản OpenGL ES mà ứng dụng yêu cầu. Số 16 bit lớn hơn đại diện cho số chính và số 16 bit nhỏ hơn đại diện cho số phụ. Ví dụ: để chỉ định phiên bản OpenGL ES 2.0, bạn sẽ đặt giá trị là "0x00020000" hoặc để chỉ định OpenGL ES 3.2, bạn sẽ đặt giá trị là "0x00030002".

Một ứng dụng chỉ định tối đa một thuộc tính android:glEsVersion trong tệp kê khai. Nếu chỉ định nhiều thuộc tính thì ứng dụng sẽ sử dụng android:glEsVersion có giá trị (số) cao nhất và bỏ qua các giá trị khác.

Nếu ứng dụng không chỉ định thuộc tính android:glEsVersion, thì mặc định rằng ứng dụng chỉ yêu cầu OpenGL ES phiên bản 1.0 được hỗ trợ trên tất cả các thiết bị chạy Android.

Ứng dụng có thể giả định rằng nếu một nền tảng hỗ trợ một phiên bản OpenGL ES nhất định, thì nền tảng đó cũng hỗ trợ mọi phiên bản OpenGL ES có số thấp hơn. Do đó, đối với ứng dụng yêu cầu cả OpenGL ES 1.0 và OpenGL ES 2.0, hãy nêu rõ rằng ứng dụng yêu cầu OpenGL ES 2.0.

Đối với ứng dụng có thể hoạt động với một số phiên bản OpenGL ES, bạn chỉ cần chỉ định phiên bản OpenGL ES có số thấp nhất mà ứng dụng yêu cầu. Ứng dụng có thể kiểm tra trong thời gian chạy xem có phiên bản OpenGL ES nào cao hơn hay không.

Để biết thêm thông tin về cách sử dụng OpenGL ES, bao gồm cả cách kiểm tra phiên bản OpenGL ES được hỗ trợ trong thời gian chạy, hãy xem phần Hướng dẫn về API OpenGL ES.

ra mắt từ:

API cấp độ 4

xem thêm:

• PackageManager
• FeatureInfo
• ConfigurationInfo
• <uses-permission>
• Bộ lọc trên Google Play

Google Play và cơ chế lọc dựa trên tính năng

Google Play lọc ứng dụng mà người dùng thấy để họ chỉ xem và tải được các ứng dụng tương thích với thiết bị của mình. Một trong những cách để lọc ứng dụng là lọc theo khả năng tương thích tính năng.

Để xác định khả năng tương thích tính năng của ứng dụng với một thiết bị của người dùng nhất định, Google Play so sánh:

• Các tính năng mà ứng dụng yêu cầu, như được khai báo trong các phần tử <uses-feature> trong tệp kê khai của ứng dụng.
• Các tính năng có sẵn trên thiết bị (trong phần cứng hoặc phần mềm) như đã báo cáo bằng cách sử dụng các thuộc tính hệ thống chỉ có thể đọc.

Để so sánh chính xác các tính năng, Trình quản lý gói của Android (Android Package Manager) cung cấp một tập hợp các hằng số tính năng dùng chung mà cả ứng dụng và thiết bị đều sử dụng để khai báo các yêu cầu và hỗ trợ về tính năng. Bạn có thể xem danh sách hằng số tính năng hiện có ở mục Tài liệu tham khảo về tính năng trong tài liệu này và trong tài liệu về lớp PackageManager.

Khi người dùng chạy Google Play, ứng dụng sẽ truy vấn trình quản lý gói để lấy danh sách tính năng có trên thiết bị bằng cách gọi getSystemAvailableFeatures(). Sau đó, ứng dụng Cửa hàng sẽ truyền danh sách tính năng lên cho Google Play khi thiết lập phiên truy cập cho người dùng.

Mỗi lần bạn tải một ứng dụng lên Google Play Console, Google Play sẽ quét tệp kê khai của ứng dụng đó. Google Play sẽ tìm các phần tử <uses-feature> và đánh giá chúng cùng với các phần tử khác, chẳng hạn như các phần tử <uses-sdk> và <uses-permission> trong một số trường hợp. Sau khi thiết lập nhóm tính năng bắt buộc của ứng dụng, Google Play sẽ lưu trữ nội bộ danh sách dưới dạng siêu dữ liệu được liên kết với APK ứng dụng và phiên bản ứng dụng.

Khi người dùng tìm kiếm hoặc duyệt tìm ứng dụng trên ứng dụng Google Play, dịch vụ này sẽ so sánh các tính năng cần thiết của từng ứng dụng với các tính năng có sẵn trên thiết bị của người dùng. Nếu thiết bị có tất cả các tính năng mà ứng dụng yêu cầu, thì Google Play sẽ hiển thị ứng dụng cho người dùng và người dùng có thể tải ứng dụng đó xuống.

Nếu có bất kỳ tính năng nào ứng dụng yêu cầu mà thiết bị không hỗ trợ, thì Google Play sẽ lọc ứng dụng để người dùng không thấy cũng như không tải được ứng dụng đó xuống.

Vì các tính năng mà bạn khai báo trong phần tử <uses-feature> trực tiếp ảnh hưởng cách Google Play lọc ứng dụng, nên việc hiểu cách Google Play đánh giá tệp kê khai của ứng dụng và thiết lập nhóm tính năng bắt buộc là rất quan trọng. Các mục sau đây sẽ cung cấp thêm thông tin.

Lọc dựa trên các tính năng được khai báo rõ ràng

Tính năng được khai báo rõ ràng là tính năng mà ứng dụng của bạn khai báo trong phần tử <uses-feature>. Nội dung khai báo tính năng có thể bao gồm thuộc tính android:required=["true" | "false"] nếu bạn đang biên dịch dựa trên API cấp 5 trở lên.

Điều này cho phép bạn chỉ rõ liệu ứng dụng có yêu cầu phải có tính năng và không thể hoạt động bình thường nếu không có ("true") hay ứng dụng sẽ sử dụng tính năng (nếu có) nhưng vẫn chạy được nếu không có ("false").

Google Play xử lý các tính năng được khai báo rõ ràng theo cách sau:

• Nếu một tính năng được khai báo rõ ràng là cần phải có, như trong ví dụ sau, thì Google Play sẽ thêm tính năng đó vào danh sách tính năng bắt buộc của ứng dụng. Sau đó, Google Play sẽ lọc ứng dụng để ứng dụng không hiển thị với những người dùng trên các thiết bị không cung cấp tính năng đó.

  <uses-feature android:name="android.hardware.camera.any" android:required="true" />

• Nếu một tính năng được khai báo rõ ràng là không cần phải có, như trong ví dụ sau, thì Google Play sẽ không thêm tính năng đó vào danh sách các tính năng bắt buộc. Vì lý do đó, Google Play sẽ không xem xét tính năng được khai báo rõ ràng là không bắt buộc khi lọc ứng dụng. Ngay cả khi thiết bị không cung cấp tính năng đã khai báo, Google Play vẫn xem là ứng dụng tương thích với thiết bị và hiển thị ứng dụng với người dùng, trừ phi các quy tắc lọc khác được áp dụng.

  <uses-feature android:name="android.hardware.camera" android:required="false" />

• Nếu một tính năng được khai báo rõ ràng nhưng không có thuộc tính android:required, thì Google Play sẽ giả định rằng tính năng đó là bắt buộc và thiết lập cơ chế lọc dựa theo đó.

Nhìn chung, nếu ứng dụng được thiết kế để chạy trên Android 1.6 trở xuống, thì thuộc tính android:required sẽ không xuất hiện trong API và Google Play sẽ giả định rằng tất cả các nội dung khai báo <uses-feature> đều là bắt buộc.

Lưu ý: Bằng cách khai báo rõ ràng một tính năng và bao gồm thuộc tính android:required="false", bạn có thể tắt tất cả các cơ chế lọc trên Google Play cho tính năng đã chỉ định.

Lọc dựa trên các tính năng ngầm ẩn

Tính năng ngầm ẩn là tính năng mà ứng dụng yêu cầu phải có để hoạt động bình thường nhưng không được khai báo trong phần tử <uses-feature> của tệp kê khai. Nói một cách chính xác, tốt nhất là luôn khai báo tất cả các tính năng mà ứng dụng dùng hoặc cần đến và việc không khai báo một tính năng mà ứng dụng sử dụng có thể bị coi là lỗi.

Tuy nhiên, để bảo vệ người dùng và nhà phát triển, Google Play sẽ tìm kiếm các tính năng ngầm ẩn trong từng ứng dụng và thiết lập bộ lọc cho các tính năng đó giống như với các tính năng được khai báo rõ ràng.

Ứng dụng có thể yêu cầu một tính năng nhưng không khai báo vì những lý do sau:

• Ứng dụng được biên dịch dựa trên phiên bản thư viện Android cũ (Android 1.5 trở xuống) không có phần tử <uses-feature>.
• Nhà phát triển giả định nhầm rằng tính năng này hiện diện trên tất cả các thiết bị và việc khai báo là không cần thiết.
• Nhà phát triển vô tình bỏ qua việc khai báo tính năng.
• Nhà phát triển khai báo tính năng này một cách rõ ràng nhưng thông tin khai báo không hợp lệ. Ví dụ: lỗi chính tả trong tên phần tử <uses-feature> hoặc giá trị chuỗi không được công nhận cho thuộc tính android:name dẫn đến kết quả khai báo tính năng không hợp lệ.

Do tính đến các trường hợp trên nên Google Play cố gắng phát hiện các yêu cầu ngầm ẩn của ứng dụng về tính năng bằng cách kiểm tra các phần tử khác được khai báo trong tệp kê khai, cụ thể là các phần tử <uses-permission>.

Nếu một ứng dụng yêu cầu các quyền liên quan đến phần cứng, thì Google Play sẽ giả định rằng ứng dụng dùng các tính năng phần cứng cơ bản nên cần các tính năng đó, mặc dù có thể không có nội dung khai báo <uses-feature> tương ứng. Đối với các quyền như vậy, Google Play sẽ thêm các tính năng phần cứng cơ bản vào siêu dữ liệu mà Google Play lưu trữ cho ứng dụng và thiết lập các bộ lọc cho chúng.

Ví dụ: nếu một ứng dụng yêu cầu quyền truy cập vào CAMERA, thì Google Play sẽ cho rằng ứng dụng đó cần máy ảnh sau (quay ra ngoài) ngay cả khi ứng dụng không khai báo phần tử <uses-feature> cho android.hardware.camera. Do vậy, Google Play sẽ lọc các thiết bị không có camera sau.

Nếu bạn không muốn Google Play lọc dựa trên một tính năng ngầm ẩn cụ thể, hãy khai báo tường minh tính năng đó trong phần tử <uses-feature> và bổ sung thuộc tính android:required="false". Ví dụ: để vô hiệu hoá tính năng lọc mà quyền truy cập CAMERA ngụ ý, hãy khai báo các tính năng sau đây:

<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

Thận trọng: Các quyền mà bạn yêu cầu trong phần tử <uses-permission> có thể ảnh hưởng trực tiếp đến cách Google Play lọc ứng dụng của bạn. Mục Các quyền ngụ ý tính chất bắt buộc của tính năng liệt kê toàn bộ các quyền ngụ ý tính chất bắt buộc của tính năng, và theo đó kích hoạt cơ chế lọc.

Cách xử lý chuyên dụng đối với tính năng Bluetooth

Google Play áp dụng các quy tắc có phần khác so với mô tả trong ví dụ trước khi xác định cơ chế lọc cho Bluetooth.

Nếu ứng dụng khai báo quyền truy cập Bluetooth trong phần tử <uses-permission>, nhưng không khai báo rõ ràng tính năng Bluetooth trong phần tử <uses-feature>, thì Google Play sẽ kiểm tra (các) phiên bản của Nền tảng Android mà ứng dụng được thiết kế để chạy trên đó, như được chỉ định trong phần tử <uses-sdk>.

Như minh hoạ trong bảng sau, Google Play sẽ chỉ kích hoạt cơ chế lọc cho tính năng Bluetooth nếu ứng dụng khai báo nền tảng nhắm mục tiêu hoặc nền tảng thấp nhất là Android 2.0 (API cấp 5) trở lên. Tuy nhiên, hãy lưu ý rằng Google Play áp dụng các quy tắc thông thường cho cơ chế lọc khi ứng dụng khai báo rõ ràng tính năng Bluetooth trong phần tử <uses-feature>.

Bảng 1. Cách Google Play xác định yêu cầu về tính năng Bluetooth cho một ứng dụng đòi hỏi phải có quyền truy cập vào Bluetooth nhưng không khai báo tính năng Bluetooth trong phần tử <uses-feature>.

Các ví dụ sau minh hoạ các kết quả lọc khác nhau dựa trên cách Google Play xử lý tính năng Bluetooth.

Trong ví dụ đầu tiên, một ứng dụng được thiết kế để chạy ở các cấp độ API cũ hơn sẽ khai báo quyền truy cập Bluetooth nhưng không khai báo tính năng Bluetooth trong phần tử <uses-feature>.

Kết quả: Google Play không lọc ứng dụng khỏi bất kỳ thiết bị nào.

<manifest ...>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-sdk android:minSdkVersion="3" />
    ...
</manifest>

Trong ví dụ thứ hai, cũng chính ứng dụng đó khai báo cấp độ API mục tiêu là "5".

Kết quả: Giờ thì Google Play sẽ giả định rằng tính năng này là bắt buộc và lọc ứng dụng khỏi tất cả thiết bị không hỗ trợ Bluetooth, bao gồm cả các thiết bị chạy phiên bản cũ hơn của nền tảng.

<manifest ...>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
    ...
</manifest>

Ở đây, cùng một ứng dụng giờ khai báo cụ thể tính năng Bluetooth.