Chuẩn bị phát hành thư viện

Trang này trình bày các thuộc tính và tuỳ chọn cần thiết để chuẩn bị phát hành dự án thư viện Android bằng trình bổ trợ Android cho Gradle (AGP). Kể cả khi đã thiết lập một số thuộc tính này ngay từ khi bắt đầu tạo thư viện, bạn vẫn nên xem hướng dẫn sau đây để tối ưu hoá các chế độ cài đặt.

Chọn một không gian tên

Thư viện Android cần khai báo một không gian tên để có thể tạo lớp R duy nhất khi tài nguyên trong thư viện được biên dịch. Không gian tên này phải khớp hoàn toàn với gói lớp gốc của thư viện để tránh nhầm lẫn khi người dùng nhập các lớp thông thường từ thư viện và lớp R của thư viện.

Kể từ phiên bản AGP 7.0, bạn có thể đặt không gian tên trong tệp build.gradle của ứng dụng như trong đoạn mã ví dụ dưới đây:

android {
  namespace = 'com.example.library'
}

android {
  namespace = "com.example.library"
}

Không gian tên là một thuộc tính dành cho nhà phát triển của thư viện. Không gian này không liên quan đến nhận dạng của ứng dụng (được thiết lập bằng thuộc tính applicationId).

Trong các phiên bản AGP trước đây, cả thuộc tính applicationId (cho ứng dụng) và thuộc tính namespace (cho thư viện) đều có thể được thiết lập bằng thuộc tính package của tệp kê khai nên dẫn đến sự nhầm lẫn.

Chọn một giá trị minSdkVersion

Việc chọn minSdkVersion cho thư viện là một khâu quan trọng khi phát hành thư viện. minSdkVersion phải phản ánh phiên bản Android tối thiểu mà mã của bạn có thể hỗ trợ.

Khi chọn minSdkVersion, hãy cân nhắc những điều sau:

• Việc chọn minSdkVersion thấp thường giúp mở rộng phạm vi phân phối của thư viện.

  Mã của thư viện thường sẽ không được thực thi trừ phi ứng dụng gọi mã một cách rõ ràng. Nếu tiến hành kiểm tra thời gian chạy trước khi gọi thư viện, có thể ứng dụng vẫn chạy trên phiên bản Android thấp hơn so với yêu cầu của phần phụ thuộc thư viện nếu thư viện không cần thiết đối với chức năng cốt lõi của ứng dụng. Do đó, hãy đặt minSdkVersion của thư viện đủ thấp để có thể được nhúng trong ứng dụng và gọi khi có thể, để giúp tiếp cận nhiều người dùng hơn.

• Việc chọn minSdkVersion cao có thể ngăn ứng dụng sử dụng thư viện.

  Trình hợp nhất tệp kê khai là một bước trong AGP giúp hợp nhất các tệp kê khai từ ứng dụng và từ phần phụ thuộc của ứng dụng, qua đó đảm bảo rằng không phần phụ thuộc nào có minSdkVersion cao hơn ứng dụng.

• Khi chọn minSdkVersion cao, có thể nhà phát triển ứng dụng được nhắc tắt tính năng kiểm tra an toàn của trình hợp nhất tệp kê khai, dẫn đến lỗi sau này trong quy trình xây dựng.

  Do trình hợp nhất tệp kê khai ngăn dự án ứng dụng nhúng các thư viện có minSdkVersion cao hơn chính ứng dụng, nên nhà phát triển ứng dụng có thể tắt tính năng kiểm tra an toàn của trình hợp nhất tệp kê khai để giảm thiểu lỗi bản dựng. Tuy nhiên, việc này sẽ tạo rủi ro xảy ra lỗi không tương thích thực sự ở hạ nguồn.

• Có thể bạn cần phải chọn minSdkVersion cao trong những trường hợp đặc biệt, khi mà tệp kê khai của thư viện có chứa broadcast receiver hoặc một số cơ chế khác giúp tự động kích hoạt mã của thư viện.

  Trong những trường hợp như vậy, việc chọn minSdkVersion cao giúp đảm bảo đoạn mã chạy được. Bạn cũng có thể tắt hành vi tự động để ứng dụng có thể chọn thực thi thư viện sau khi tiến hành các hoạt động kiểm tra phù hợp.

Để cho phép nhúng trong ứng dụng, hãy sử dụng chú thích RequiresApi trong thư viện để phương thức gọi của ứng dụng biết chúng cần kiểm tra thời gian chạy. Android Lint dùng thông tin RequiresApi để tiến hành kiểm tra. Để tham khảo các tài nguyên khác về cách dùng chú thích nhằm cải thiện API và mã API, hãy tham khảo bài viết Dùng chú thích để cải thiện chất lượng kiểm tra mã.

Thiết lập siêu dữ liệu AAR

Thư viện Android được đóng gói dưới dạng tệp Android Archive (AAR). Siêu dữ liệu AAR chứa các thuộc tính giúp AGP sử dụng thư viện. Nếu một cấu hình không tương thích sử dụng thư viện của bạn và siêu dữ liệu AAR đã được thiết lập, người dùng sẽ nhìn thấy thông báo lỗi để giúp khắc phục vấn đề.

Chọn giá trị minCompileSdk

Kể từ phiên bản 4.1, AGP hỗ trợ minCompileSdk. Hàm này cho biết compileSdk thấp nhất mà dự án có thể dùng. Nếu thư viện của bạn chứa các mục nhập tệp kê khai hoặc tài nguyên tận dụng những thuộc tính mới của nền tảng, bạn cần phải đặt giá trị này.

Bạn có thể đặt giá trị minCompileSdk trong các khối defaultConfig{}, productFlavors{} và buildTypes{} của tệp build.gradle ở cấp độ mô-đun.

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

Nếu bạn đã đặt minCompileSdk ở nhiều nơi, Gradle sẽ ưu tiên vị trí cho chế độ cài đặt như sau trong suốt quá trình xây dựng:

1. buildTypes{}

2. productFlavors{}

3. defaultConfig{}

Trong ví dụ trước, khi minCompileSdk được xác định trong cả defaultConfig{} và productFlavors{}, productFlavors{} được ưu tiên và minCompileSdk được đặt thành 30.

Để tìm hiểu thêm về các chế độ cài đặt ưu tiên của Gradle khi kết hợp mã và tài nguyên, hãy tham khảo bài viết Xây dựng bằng nhóm tài nguyên.

Bật môi trường thử nghiệm cố định

Môi trường thử nghiệm cố định thường được dùng để thiết lập đoạn mã đang được kiểm thử hoặc thúc đẩy việc kiểm thử một thành phần. Kể từ phiên bản 7.1, AGP có thể tạo môi trường thử nghiệm cố định cho các dự án thư viện (ngoài ứng dụng và các dự án có tính năng cụ thể.)

Khi phát hành thư viện để người khác sử dụng, nên cân nhắc tạo môi trường thử nghiệm cố định cho API của bạn. Bạn có thể bật môi trường thử nghiệm cố định trong tệp build.gradle ở cấp độ mô-đun:

android {
  testFixtures {
    enable = true
  }
}

android {
  testFixtures {
    enable = true
  }
}

Khi bật môi trường thử nghiệm cố định, Gradle tự động tạo một nhóm tài nguyên src/testFixtures để bạn có thể viết các môi trường thử nghiệm cố định.

Để biết thêm thông tin, hãy tham khảo tài liệu của Gradle về cách sử dụng môi trường thử nghiệm cố định.