<uses-sdk>

Google Play sử dụng các thuộc tính <uses-sdk> được khai báo trong tệp kê khai ứng dụng để lọc từ các thiết bị không đáp ứng yêu cầu về phiên bản nền tảng của ứng dụng đó. Trước khi đặt các thuộc tính này, hãy đảm bảo bạn hiểu rõ bộ lọc của Google Play.

cú pháp:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

có trong:

<manifest>

nội dung mô tả:

Cho phép bạn thể hiện khả năng tương thích của ứng dụng với một hoặc nhiều phiên bản nền tảng Android, thông qua một số nguyên chỉ định cấp độ API. Cấp độ API mà ứng dụng biểu thị sẽ được so sánh với cấp độ API của một hệ thống Android nhất định vốn có thể khác nhau giữa các thiết bị Android khác nhau.

Phần tử này dùng để chỉ định cấp độ API, không phải số phiên bản của bộ phát triển phần mềm (SDK) hoặc nền tảng Android như tên gọi của nó. Cấp độ API luôn là một số nguyên duy nhất. Bạn không được lấy cấp độ API từ số phiên bản Android liên kết. Ví dụ: API này không giống với phiên bản chính hoặc tổng các phiên bản chính và phụ.

Bạn cũng cần tham khảo tài liệu về cách tạo phiên bản cho ứng dụng của bạn.

thuộc tính:

android:minSdkVersion

Một số nguyên chỉ định cấp độ API tối thiểu cần thiết để ứng dụng chạy. Hệ thống Android sẽ ngăn người dùng cài đặt ứng dụng nếu cấp độ API của hệ thống thấp hơn giá trị được chỉ định trong thuộc tính này. Hãy luôn khai báo thuộc tính này.

Thận trọng: Nếu bạn không khai báo thuộc tính này, hệ thống sẽ giả định một giá trị mặc định là "1". Giá trị này cho biết ứng dụng của bạn tương thích với mọi phiên bản Android. Nếu không phải như vậy và bạn không khai báo minSdkVersion thích hợp, thì khi được cài đặt trên hệ thống có cấp độ API không tương thích, ứng dụng sẽ gặp sự cố trong thời gian chạy khi cố truy cập vào các API không được hỗ trợ. Vì lý do này, hãy nhớ khai báo cấp độ API thích hợp trong thuộc tính minSdkVersion.

android:targetSdkVersion

Một số nguyên chỉ định cấp độ API mà ứng dụng nhắm mục tiêu. Nếu không được thiết lập, giá trị mặc định sẽ bằng giá trị minSdkVersion.

Thuộc tính này thông báo cho hệ thống là bạn đã kiểm thử so với phiên bản đích và hệ thống không cho phép bất kỳ hành vi tương thích nào duy trì khả năng tương thích chuyển tiếp của ứng dụng với phiên bản mục tiêu. Ứng dụng vẫn có thể chạy trên các phiên bản thấp hơn (xuống đến minSdkVersion).

Vì Android phát triển với mỗi phiên bản mới, một số hành vi và thậm chí giao diện có thể thay đổi. Tuy nhiên, nếu cấp độ API của nền tảng cao hơn phiên bản được targetSdkVersion của ứng dụng khai báo, hệ thống có thể kích hoạt hành vi tương thích để ứng dụng tiếp tục hoạt động như dự kiến. Bạn có thể tắt các hành vi tương thích đó bằng cách chỉ định targetSdkVersion để khớp với cấp độ API của nền tảng nơi hành vi đang chạy.

Ví dụ: nếu bạn đặt giá trị này thành "11" trở lên, hệ thống sẽ áp dụng giao diện mặc định Holo cho ứng dụng của bạn khi chạy trên Android 3.0 trở lên, đồng thời tắt chế độ tương thích màn hình khi chạy trên màn hình lớn (vì tính năng hỗ trợ cho API cấp độ 11 ngầm hỗ trợ màn hình lớn).

Có nhiều hành vi tương thích mà hệ thống có thể bật dựa trên giá trị bạn đặt cho thuộc tính này. Một số hành vi nêu trên được mô tả theo các phiên bản nền tảng tương ứng trong tệp tham chiếu Build.VERSION_CODES.

Để duy trì ứng dụng tích hợp với mỗi bản phát hành Android, bạn hãy tăng giá trị của thuộc tính này để phù hợp với cấp độ API mới nhất, sau đó kiểm thử kỹ ứng dụng của bạn trên phiên bản nền tảng tương ứng.

Giới thiệu trong API cấp độ 4

android:maxSdkVersion

Một số nguyên chỉ định cấp độ API tối đa mà ứng dụng được thiết kế để chạy.

Trên Android 1.5, 1.6, 2.0 và 2.0.1, hệ thống sẽ kiểm tra giá trị của thuộc tính này khi cài đặt ứng dụng và xác thực lại ứng dụng sau quá trình cập nhật hệ thống. Trong cả hai trường hợp, nếu thuộc tính maxSdkVersion của ứng dụng thấp hơn cấp độ API mà hệ thống sử dụng, thì hệ thống sẽ không cho phép cài đặt ứng dụng đó. Trong trường hợp xác thực lại sau khi cập nhật hệ thống, điều này sẽ xoá ứng dụng của bạn khỏi thiết bị một cách hiệu quả.

Để minh hoạ cách thuộc tính này ảnh hưởng đến ứng dụng của bạn sau khi cập nhật hệ thống, hãy xem xét ví dụ sau đây:

Một ứng dụng khai báo maxSdkVersion="5" trong tệp kê khai đã được xuất bản trên Google Play. Một người dùng có thiết bị đang chạy Android 1.6 (API cấp độ 4) sẽ tải xuống và cài đặt ứng dụng. Sau vài tuần, người dùng sẽ nhận được bản cập nhật hệ thống lên Android 2.0 (API cấp độ 5) qua mạng không dây. Sau khi cài đặt bản cập nhật, hệ thống sẽ kiểm tra maxSdkVersion của ứng dụng và xác thực lại thành công ứng dụng đó.

Ứng dụng này hoạt động như bình thường. Tuy nhiên, sau một thời gian, thiết bị nhận được một bản cập nhật hệ thống khác, lần này là lên Android 2.0.1 (API cấp độ 6). Sau khi cập nhật, hệ thống không thể xác thực lại ứng dụng đó nữa vì cấp độ API của chính hệ thống (6) hiện đã cao hơn cấp độ tối đa mà ứng dụng hỗ trợ (5). Hệ thống ngăn ứng dụng đó hiển thị với người dùng, trên thực tế là xoá ứng dụng đó khỏi thiết bị.

Cảnh báo: Bạn không nên khai báo thuộc tính này. Thứ nhất, bạn không cần phải đặt thuộc tính này làm phương thức chặn triển khai ứng dụng của mình trên các phiên bản nền tảng Android mới khi các phiên bản đó được phát hành. Theo thiết kế, các phiên bản mới của nền tảng hoàn toàn tương thích ngược. Ứng dụng của bạn sẽ hoạt động bình thường trên các phiên bản mới, miễn là ứng dụng đó chỉ sử dụng API tiêu chuẩn và tuân thủ các phương pháp phát triển hay nhất. Thứ hai, trong một số trường hợp, nếu bạn khai báo thuộc tính này, ứng dụng của bạn có thể bị xoá khỏi thiết bị của người dùng sau khi cập nhật hệ thống lên một cấp độ API cao hơn. Hầu hết các thiết bị mà ứng dụng của bạn có thể cài đặt được sẽ nhận bản cập nhật hệ thống định kỳ qua mạng không dây. Vì vậy, hãy cân nhắc tác động của các thiết bị đó đến ứng dụng trước khi đặt thuộc tính này.

Giới thiệu trong API cấp độ 4

Một số phiên bản Android (ngoài Android 2.0.1) không kiểm tra hoặc thực thi thuộc tính maxSdkVersion trong quá trình cài đặt hoặc xác thực lại. Tuy nhiên, Google Play sẽ tiếp tục sử dụng thuộc tính này làm bộ lọc khi cho người dùng thấy các ứng dụng có thể tải xuống.

ra mắt từ:

API cấp 1

Cấp độ API là gì?

Cấp độ API là một giá trị số nguyên xác định duy nhất bản sửa đổi API khung do một phiên bản nền tảng Android cung cấp.

Nền tảng Android cung cấp một API khung mà các ứng dụng có thể sử dụng để tương tác với hệ thống Android cơ bản. API khung bao gồm:

• Tập hợp lõi các gói và lớp
• Tập hợp các phần tử và thuộc tính XML để khai báo tệp kê khai
• Tập hợp các phần tử và thuộc tính XML để khai báo và truy cập các tài nguyên
• Một tập hợp ý định
• Một tập hợp các quyền mà ứng dụng có thể yêu cầu, cũng như quyền thực thi quyền truy cập được đưa vào hệ thống

Mỗi phiên bản kế tiếp của nền tảng Android đều có thể bao gồm nội dung cập nhật cho API khung ứng dụng Android mà nền tảng phân phối.

Các bản cập nhật cho API khung được thiết kế để API mới vẫn tương thích với các phiên bản API cũ. Điều này nghĩa là hầu hết các thay đổi trong API đều có tính bổ sung và giới thiệu chức năng mới hoặc thay thế. Khi các phần của API được nâng cấp, những phần cũ hơn đã được thay thế sẽ không được dùng nữa nhưng không bị xoá để các ứng dụng hiện có vẫn có thể sử dụng chúng.

Trong số ít trường hợp, một vài phần của API được sửa đổi hoặc xoá, mặc dù thông thường, những thay đổi đó chỉ cần để hỗ trợ độ mạnh của API và bảo mật ứng dụng hoặc hệ thống. Chúng tôi sẽ chuyển tất cả các phần API khác trong bản sửa đổi trước đó mà không cần sửa đổi.

API khung mà nền tảng Android phân phối được chỉ định bằng cách sử dụng giá trị nhận dạng số nguyên gọi là cấp độ API. Mỗi phiên bản nền tảng Android đều hỗ trợ chính xác một cấp độ API mặc dù chức năng hỗ trợ được ngầm định cho tất cả cấp độ API trước đó (xuống đến API cấp độ 1). Bản phát hành ban đầu của nền tảng Android đã cung cấp API cấp độ 1 và các bản phát hành tiếp theo đã tăng cấp độ API.

Bảng sau đây chỉ định cấp độ API mà mỗi phiên bản nền tảng Android hỗ trợ. Để biết thông tin về số lượng thiết bị tương đối đang chạy từng phiên bản, hãy xem Trang tổng quan về hoạt động phân phối.

Sử dụng cấp độ API trong Android

Giá trị nhận dạng cấp độ API đóng vai trò quan trọng trong việc đảm bảo mang lại trải nghiệm tốt nhất cho người dùng và nhà phát triển ứng dụng:

• API này cho phép nền tảng Android mô tả bản sửa đổi API khung tối đa mà nền tảng hỗ trợ.
• API này cho phép các ứng dụng mô tả bản sửa đổi API khung mà chúng yêu cầu.
• API này cho phép hệ thống cân nhắc việc cài đặt các ứng dụng trên thiết bị của người dùng, để không cài đặt các ứng dụng không tương thích với phiên bản.

Mỗi phiên bản nền tảng Android đều lưu trữ mã nhận dạng cấp độ API trong hệ thống Android.

Các ứng dụng có thể dùng một phần tử tệp kê khai do API khung cung cấp – <uses-sdk> –để mô tả cấp độ API tối thiểu và tối đa mà chúng có thể chạy, cũng như cấp độ API ưu tiên mà các phần tử đó được thiết kế để hỗ trợ. Phần tử này cung cấp 3 thuộc tính chính:

• android:minSdkVersion: cấp độ API tối thiểu mà ứng dụng có thể chạy. Giá trị mặc định là "1".
• android:targetSdkVersion: cấp độ API mà ứng dụng được thiết kế để chạy. Trong một số trường hợp, việc này cho phép ứng dụng sử dụng các phần tử hoặc hành vi tệp kê khai được xác định ở cấp độ API mục tiêu, thay vì giới hạn chỉ dùng các phần tử được xác định cho cấp độ API tối thiểu.
• android:maxSdkVersion: cấp độ API tối đa mà ứng dụng có thể chạy. Lưu ý quan trọng: Vui lòng đọc thông tin về thuộc tính này trên trang này trước khi sử dụng.

Ví dụ: để chỉ định cấp độ API tối thiểu của hệ thống mà một ứng dụng đòi hỏi phải có để chạy, ứng dụng đó sẽ đưa tệp kê khai vào phần tử <uses-sdk> có thuộc tính android:minSdkVersion. Giá trị của android:minSdkVersion là số nguyên tương ứng với cấp độ API của phiên bản nền tảng Android ban đầu mà ứng dụng có thể chạy.

Khi người dùng cố gắng cài đặt một ứng dụng hoặc khi xác thực lại một ứng dụng sau khi cập nhật hệ thống, trước tiên, hệ thống Android sẽ kiểm tra các thuộc tính <uses-sdk> trong tệp kê khai của ứng dụng và so sánh các giá trị với cấp độ API nội bộ của chính nó. Hệ thống chỉ cho phép bắt đầu quá trình cài đặt nếu các điều kiện sau được đáp ứng:

• Nếu bạn khai báo thuộc tính android:minSdkVersion thì giá trị của thuộc tính đó phải nhỏ hơn hoặc bằng số nguyên chỉ định cấp độ API của hệ thống. Nếu bạn không khai báo, hệ thống sẽ giả định rằng ứng dụng yêu cầu API cấp độ 1.
• Nếu bạn khai báo thuộc tính android:maxSdkVersion thì giá trị của thuộc tính đó phải bằng hoặc lớn hơn số nguyên chỉ định cấp độ API của hệ thống. Nếu bạn không khai báo, hệ thống sẽ giả định rằng ứng dụng không có cấp độ API tối đa. Vui lòng đọc nội dung mô tả về thuộc tính này để biết thêm thông tin về cách hệ thống xử lý thuộc tính đó.

Khi được khai báo trong tệp kê khai của một ứng dụng, phần tử <uses-sdk> sẽ có dạng như sau:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Lý do chính khiến một ứng dụng khai báo cấp độ API trong android:minSdkVersion là để cho hệ thống Android biết ứng dụng đó đang sử dụng các API đã được giới thiệu trong cấp độ API được chỉ định.

Nếu ứng dụng cài đặt theo cách nào đó trên nền tảng có cấp độ API thấp hơn, thì ứng dụng đó sẽ gặp lỗi trong thời gian chạy khi cố gắng truy cập vào các API không tồn tại. Hệ thống sẽ ngăn điều này xảy ra bằng cách không cho phép ứng dụng đó cài đặt nếu cấp độ API thấp nhất mà ứng dụng yêu cầu cao hơn phiên bản nền tảng trên thiết bị mục tiêu.

Điều cần cân nhắc khi phát triển ứng dụng

Các phần sau đây cung cấp thông tin liên quan đến cấp độ API mà bạn cần cân nhắc khi phát triển ứng dụng.

Khả năng tương thích chuyển tiếp của ứng dụng

Các ứng dụng Android thường tương thích chuyển tiếp với các phiên bản mới của nền tảng Android.

Hầu hết các thay đổi đối với API khung đều mang tính bổ sung, do đó, một ứng dụng Android được phát triển sử dụng bất kỳ phiên bản cụ thể nào của API (như đã chỉ định ở cấp độ API) đều tương thích chuyển tiếp với các phiên bản sau của nền tảng Android và các cấp độ API cao hơn. Ứng dụng phải chạy được trên tất cả các phiên bản mới hơn của nền tảng Android, ngoại trừ một số trường hợp khi ứng dụng sử dụng một phần của API sau đó bị xoá vì lý do nào đó.

Khả năng tương thích chuyển tiếp rất quan trọng vì nhiều thiết bị chạy Android nhận được bản cập nhật hệ thống không dây (OTA). Người dùng có thể cài đặt ứng dụng của bạn và sử dụng thành công, sau đó nhận bản cập nhật qua mạng không dây cho một phiên bản mới trên nền tảng Android. Sau khi bản cập nhật được cài đặt, ứng dụng của bạn sẽ chạy trong phiên bản chạy thực mới, nhưng phiên bản đó có API và các năng lực hệ thống mà ứng dụng của bạn phụ thuộc.

Những thay đổi bên dưới API như các thay đổi về chính hệ thống cơ bản có thể ảnh hưởng đến ứng dụng của bạn khi ứng dụng được chạy trong môi trường mới. Là nhà phát triển ứng dụng, bạn cần phải hiểu rõ cách ứng dụng hiển thị và hoạt động trong từng môi trường hệ thống.

Để giúp bạn kiểm thử ứng dụng của mình trên các phiên bản khác nhau của nền tảng Android, Android SDK gồm nhiều nền tảng mà bạn có thể tải xuống. Mỗi nền tảng gồm một hình ảnh hệ thống tương thích có thể chạy trong AVD để kiểm thử ứng dụng của bạn.

Khả năng tương thích ngược của ứng dụng

Các ứng dụng Android không nhất thiết phải tương thích ngược với các phiên bản nền tảng Android cũ hơn phiên bản đã được biên dịch.

Mỗi phiên bản mới của nền tảng Android có thể bao gồm các API khung mới, chẳng hạn như các API cho phép ứng dụng truy cập vào các tính năng mới của nền tảng hoặc thay thế các phần API hiện có. Các API mới có thể truy cập vào ứng dụng khi chạy trên nền tảng mới cũng như khi chạy trên các phiên bản mới hơn của nền tảng được chỉ định theo cấp độ API. Tuy nhiên, vì những phiên bản cũ hơn của nền tảng không bao gồm API mới, nên những ứng dụng sử dụng API mới không chạy được trên các nền tảng đó.

Mặc dù một thiết bị chạy Android không thể bị hạ cấp xuống phiên bản trước đó của nền tảng, nhưng bạn cần hiểu rằng có thể có nhiều thiết bị trong lĩnh vực này chạy các phiên bản trước đó của nền tảng. Ngay cả trong số những thiết bị nhận được bản cập nhật qua mạng không dây, một số thiết bị có thể bị trễ và có thể không nhận được bản cập nhật trong khoảng thời gian đáng kể.

Chọn một phiên bản nền tảng và cấp độ API

Khi phát triển ứng dụng, hãy chọn phiên bản nền tảng mà bạn sẽ biên dịch ứng dụng. Nhìn chung, bạn nên biên dịch ứng dụng trên phiên bản thấp nhất có thể của nền tảng mà ứng dụng của bạn có thể hỗ trợ.

Bạn có thể xác định phiên bản nền tảng thấp nhất có thể bằng cách biên dịch ứng dụng dựa theo mục tiêu bản dựng thấp hơn kế tiếp. Sau khi xác định phiên bản thấp nhất, bạn nên tạo AVD bằng cách sử dụng phiên bản nền tảng tương ứng và cấp độ API, đồng thời kiểm thử đầy đủ ứng dụng của bạn. Hãy nhớ khai báo một thuộc tính android:minSdkVersion trong tệp kê khai của ứng dụng và đặt giá trị của thuộc tính đó về cấp độ API của phiên bản nền tảng.

Khai báo cấp độ API tối thiểu

Nếu tạo một ứng dụng sử dụng API hoặc các tính năng hệ thống được giới thiệu trong phiên bản nền tảng mới nhất, hãy đặt thuộc tính android:minSdkVersion về cấp độ API của phiên bản nền tảng mới nhất. Khi đó, người dùng chỉ có thể cài đặt ứng dụng của bạn nếu thiết bị của họ đang chạy một phiên bản tương thích của nền tảng Android. Đổi lại, điều này giúp đảm bảo rằng ứng dụng của bạn có thể hoạt động đúng cách trên các thiết bị của họ.

Nếu ứng dụng của bạn sử dụng các API được giới thiệu trong phiên bản nền tảng mới nhất nhưng không khai báo thuộc tính android:minSdkVersion, thì ứng dụng đó sẽ chạy đúng cách trên các thiết bị chạy phiên bản mới nhất của nền tảng, nhưng không dùng được trên thiết bị chạy các phiên bản cũ hơn của nền tảng. Trong trường hợp sau, ứng dụng sẽ gặp lỗi trong thời gian chạy khi cố gắng sử dụng các API không có trong những phiên bản trước đó.

Kiểm thử với các cấp độ API cao hơn

Sau khi biên dịch ứng dụng, hãy kiểm thử ứng dụng đó trên nền tảng được chỉ định trong thuộc tính android:minSdkVersion của ứng dụng. Để làm điều đó, hãy tạo một AVD sử dụng phiên bản nền tảng mà ứng dụng của bạn đòi hỏi. Ngoài ra, để kiểm tra khả năng tương thích chuyển tiếp, bạn nên chạy và kiểm thử ứng dụng trên tất cả các nền tảng sử dụng cấp độ API cao hơn so với cấp độ API mà ứng dụng của bạn sử dụng.

Android SDK gồm nhiều phiên bản nền tảng mà bạn có thể sử dụng, bao gồm cả phiên bản mới nhất và cung cấp công cụ cập nhật có thể sử dụng để tải xuống các phiên bản nền tảng khác khi cần.

Để truy cập vào trình cập nhật, hãy sử dụng công cụ dòng lệnh android nằm trong thư mục <sdk>/tools. Bạn có thể chạy trình cập nhật SDK bằng cách thực thi android sdk. Bạn cũng có thể nhấp đúp vào tệp android.bat (Windows) hoặc android (OS X/Linux).

Để chạy ứng dụng của bạn dựa trên các phiên bản nền tảng khác nhau trong trình mô phỏng, hãy tạo AVD cho từng phiên bản nền tảng mà bạn muốn kiểm thử. Để biết thêm thông tin về AVD, hãy xem bài viết Tạo và quản lý thiết bị ảo. Nếu đang dùng một thiết bị thực để kiểm thử, hãy đảm bảo bạn biết cấp độ API của nền tảng Android mà nó chạy. Xem bảng tương ứng trong tài liệu này để biết danh sách các phiên bản nền tảng và cấp độ API của các phiên bản đó.

Lọc tài liệu tham khảo theo cấp độ API

Các trang tài liệu tham khảo về nền tảng Android cung cấp chế độ kiểm soát "cấp độ API" ở phần trên cùng bên trái của mỗi trang. Bạn có thể sử dụng chế độ kiểm soát này để chỉ hiện tài liệu cho các phần của API thực sự có thể truy cập vào ứng dụng của bạn, dựa trên cấp độ API mà ứng dụng chỉ định trong thuộc tính android:minSdkVersion của tệp kê khai.

Để sử dụng tính năng lọc, hãy chọn cấp độ API mà ứng dụng của bạn chỉ định trong trình đơn. Các API được giới thiệu ở một cấp độ API sau đó sẽ chuyển sang màu xám và nội dung liên quan sẽ bị ẩn đi vì ứng dụng của bạn sẽ không thể truy cập vào các API đó.

Tính năng lọc theo cấp độ API trong tài liệu không cung cấp chế độ xem nội dung mới hoặc được giới thiệu ở từng cấp độ API mà chỉ cung cấp cách xem toàn bộ API liên kết với một cấp độ API nhất định, đồng thời loại trừ phần tử API được giới thiệu ở các cấp độ API sau.

Để quay lại chế độ xem toàn bộ tài liệu, hãy chọn REL ở đầu trình đơn cấp độ API. Theo mặc định, tính năng lọc cấp độ API sẽ bị tắt để bạn có thể xem toàn bộ API khung bất kể cấp độ API.

Tài liệu tham khảo cho từng phần tử API cho biết cấp độ API mà mỗi phần tử được giới thiệu. Cấp độ API cho các gói và lớp được chỉ định là "Đã thêm vào cấp độ API" ở góc trên bên phải vùng nội dung trên mỗi trang tài liệu. Cấp độ API cho các thành phần trong lớp được chỉ định trong tiêu đề mô tả chi tiết của chúng ở lề phải.