Skip to main content

Android - Third-Party Libraries in Your Module

When developing Android modules for the Q2 Mobile App, we follow strict security and performance guidelines that restrict the use of additional Maven repositories. This ensures that our app remains secure and manageable by keeping external dependencies to a minimum.

Standard maven repositories like google and mavenCentral are accessible and should provide no problems in using.

If your module requires third-party libraries that are private or not on one of these maven servers, we provide a process for adding these libraries to the Q2 repository infrastructure.

This document outlines how to handle third-party libraries, especially those hosted in private Maven repositories or repositories that we cannot access directly. We will explain how to submit your .aar (Android Archive) and .pom (Project Object Model) files to Q2, so that we can host them and ensure your module can access them securely.

Key Points​

  • No Additional Maven Repositories: For security reasons, the Q2 Mobile App does not allow adding additional Maven repositories beyond our approved set. This helps to maintain a controlled environment and ensures all dependencies are vetted and accessible.
  • Private Libraries: If your module requires a private library, or a library from a Maven repository we cannot access, we can host the library's artifact for you.
  • Process for Hosting Libraries: You will submit your library's .aar and .pom files, and we will upload them to your Android repositories package registry. After that, you can implement the library using a standard Maven-style dependency call.

Step-by-Step Process for Using Third-Party Libraries​

Understanding POM Files​

Before submitting your library artifacts, it's important to understand what a POM (Project Object Model) file is and how it should be structured.

A POM file is an XML document that describes a Maven project. It contains information about the project's coordinates (groupId, artifactId, version), packaging type, dependencies, and other metadata. For GitLab's package registry to correctly expose your library to Gradle, the POM file must be properly formatted and its contents must match the file names exactly.

Required POM Elements​

Your POM file must include the following elements:

  • <modelVersion>: Must be set to 4.0.0 (the current POM model version)
  • <groupId>: The unique identifier for your organization or project (e.g., com.example.library)
  • <artifactId>: The name of the library (e.g., my-android-library)
  • <version>: The version number following semantic versioning (e.g., 1.0.0, 1.0-SNAPSHOT)
  • <packaging>: Must be set to aar for Android libraries
  • <dependencies>: (If applicable) List of dependencies required by your library

File Naming Convention​

Critical: Both the .aar and .pom files must follow Maven's standard naming convention and must have identical names except for their extensions:

{artifactId}-{version}.aar
{artifactId}-{version}.pom

For example, if your POM declares:

  • <artifactId>my-android-library</artifactId>
  • <version>1.0.0</version>

Then your files must be named:

  • my-android-library-1.0.0.aar
  • my-android-library-1.0.0.pom

Important Notes:

  • The artifactId and version in the file names must exactly match the values in your POM file
  • While not strictly required, it's recommended to use lowercase and follow kebab-case naming (e.g., my-library-name)
  • Version strings must not contain double dots (..) or trailing dots
  • Valid version examples: 1.0.0, 1.0-SNAPSHOT, 2.1.3-alpha

Example POM File​

Here's a complete example of a properly formatted POM file for an Android library:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example.library</groupId>
    <artifactId>my-android-library</artifactId>
    <version>1.0.0</version>
    <packaging>aar</packaging>

    <dependencies>
        <!-- Add any dependencies your library requires -->
        <dependency>
            <groupId>androidx.appcompat</groupId>
            <artifactId>appcompat</artifactId>
            <version>1.6.1</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Preparing Your Library Files​

If your module depends on a third-party library that is not available in our allowed Maven repositories, follow these steps:

  • Obtain the .aar and .pom files: These are the key artifacts required for a library. The .aar file contains the actual Android library, while the .pom file describes the project structure and dependencies.

  • Verify file naming: Ensure both files follow the naming convention {artifactId}-{version} with .aar and .pom extensions. The names must be identical except for the extension.

  • Validate the .pom file: Open the .pom file and verify:

    • <modelVersion> is set to 4.0.0
    • <groupId>, <artifactId>, and <version> are correctly defined
    • <packaging> is set to aar
    • The <artifactId> and <version> values match the file names exactly (case-sensitive)
    • All dependencies are properly declared in the <dependencies> section

  • Place the files in an /artifacts folder: For easy organization and upload, place your .aar and .pom files in the root of your Android module under a directory named /artifacts. This structure is crucial for streamlining the hosting process.

Submit a Merge Request​

Once you have prepared and validated your .aar and .pom files in the /artifacts folder, you need to submit them to the Q2 team for review and hosting.

  • Create a feature branch: If you haven't already, create a new branch from your current working branch (e.g., feature/add-third-party-library).

  • Commit the /artifacts folder: Commit the .aar and .pom files in the /artifacts folder to your feature branch:

    git add artifacts/
    git commit -m "Add third-party library artifacts for [library-name]"
    git push origin feature/add-third-party-library

  • Create a Merge Request to master: In GitLab, create a Merge Request from your feature branch to the master branch. In the MR description, include:

    • The name of the library and version
    • The purpose of the library (what functionality it provides)
    • Confirmation that the POM file has been validated and file names match the coordinates
    • Any transitive dependencies that also need to be hosted

Q2 Team Review and Package Publishing​

Once you submit the Merge Request, the Q2 team will:

  • Review the Merge Request: We will examine the submitted files to ensure they meet all requirements.

  • Verify the files: We will check that:

    • The .aar and .pom files follow the correct naming convention
    • The POM file is properly formatted with required elements
    • The artifactId and version in the POM match the file names exactly
    • The packaging is set to aar
    • Dependencies are correctly declared

  • Upload the artifacts: Once verified, we will upload the .aar and .pom files to your Android repositories package registry in GitLab, making them available for use in your module.

  • Merge the MR: After successful upload, we will merge your Merge Request to the master branch and notify you that the library is ready for use.

Implement the Library in Your Module​

After the artifacts have been uploaded to the registry, you can implement the third-party library in your Android module just like any other Maven dependency:

  • Update your build.gradle: In your module's build.gradle file, add the dependency using the standard Maven implementation format:
implementation 'groupId:artifactId:version'

Replace groupId, artifactId, and version with the corresponding values from the .pom file. If not sure, we can also send you the host link and or dependency implementation.

Dependencies of the Library​

If the library you're trying to implement has any other dependencies that are hosted in repositories we cannot access, we will need to host those as well. In this case, ensure that:

  • All dependencies are included: Make sure to include all .aar and .pom files for any additional dependencies in the /artifacts folder. Each dependency must follow the same naming convention and POM validation requirements.

  • List dependencies in the MR: In your Merge Request description, clearly list all transitive dependencies that are being submitted, including their groupId, artifactId, and version coordinates.

  • Submit all dependencies together: Include all required dependencies in the same Merge Request to ensure they are uploaded and available before your main library is integrated.

Final Testing​

After adding the dependency and syncing your Gradle files, make sure to test the module to ensure that:

  • The third-party library is correctly integrated.
  • All functionality works as expected.
  • There are no missing dependencies or runtime issues.

Important Considerations​

  • File Naming is Critical: The .aar and .pom files must follow the exact naming convention: {artifactId}-{version}.aar and {artifactId}-{version}.pom. The file names must match the artifactId and version values declared in the POM file exactly (case-sensitive). Mismatched names will cause GitLab's package registry to fail to expose the library to Gradle.

  • POM File Structure: The .pom file must be a valid XML document with required elements:

    • <modelVersion>4.0.0</modelVersion> (required)
    • <groupId>, <artifactId>, <version> (required, case-sensitive)
    • <packaging>aar</packaging> (required for Android libraries)
    • <dependencies> section with all transitive dependencies properly declared
    • Incorrect or incomplete POM files will cause build failures and dependency resolution errors.

  • Version String Requirements: Version strings must follow Maven conventions and cannot contain double dots (..) or trailing dots. Valid examples: 1.0.0, 1.0-SNAPSHOT, 2.1.3-alpha.

  • Private Libraries: If the library is private or cannot be accessed through our allowed repositories, Q2 will only host it upon request via the Merge Request process. Be sure to submit properly formatted .aar and .pom files for each artifact.

  • Transitive Dependencies: If the third-party library you are using has transitive dependencies (i.e., other libraries it depends on), those will also need to be hosted if they are not available in our allowed Maven repositories. Submit all dependencies in the same Merge Request with their own properly formatted .aar and .pom files.

  • Security & Compliance: We maintain strict security practices, and as such, all third-party libraries hosted on our infrastructure are carefully vetted during the Merge Request review process. Any unapproved repositories or unverified libraries will not be allowed.

Conclusion​

By following this process, you can ensure that your Android module can safely and securely use third-party libraries, even if they are hosted in private or restricted Maven repositories. The key to success is:

  1. Proper file naming: Ensure your .aar and .pom files follow the {artifactId}-{version} naming convention
  2. Valid POM structure: Include all required elements with correct values that match your file names
  3. Complete dependencies: Include all transitive dependencies that aren't available in our allowed repositories
  4. Clear Merge Request: Submit a well-documented MR with all necessary artifacts and information

The Q2 team will review your Merge Request, verify the artifacts, upload them to the package registry, and merge your MR once everything is validated. If you have questions or need assistance with preparing your POM file or understanding the requirements, please reach out to the Q2 team before submitting your Merge Request.