Omówienie pliku manifestu aplikacji

Każdy projekt aplikacji musi mieć plik AndroidManifest.xml z dokładnie taką nazwą w katalogu głównym zbioru źródłowego projektu. Plik manifestu zawiera podstawowe informacje o aplikacji udostępnianej w narzędziach do tworzenia aplikacji na Androida, systemie operacyjnym Android i w Google Play.

Plik manifestu musi między innymi zadeklarować:

• Komponenty aplikacji, w tym cała aktywność, usługi, odbiorniki i dostawcy treści. Każdy komponent musi definiować właściwości podstawowe, takie jak nazwa klasy Kotlin czy Java. Może też zadeklarować możliwości, np. obsługiwane konfiguracje urządzeń, które obsługuje, oraz filtry intencji, które opisują sposób uruchomienia komponentu. W następnej sekcji znajdziesz więcej informacji o komponentach aplikacji.
• Uprawnienia wymagane przez aplikację do korzystania z chronionych części systemu lub innych aplikacji. Deklarują one również wszelkie uprawnienia, które inne aplikacje muszą mieć, aby uzyskać dostęp do treści z tej aplikacji. Więcej informacji o uprawnieniach znajdziesz w następnej sekcji.
• Sprzęt i funkcje oprogramowania, których wymaga aplikacja, wpływają na to, na jakich urządzeniach można ją zainstalować z Google Play. Więcej informacji o zgodności urządzeń znajdziesz w następnej sekcji.

Jeśli do tworzenia aplikacji używasz Android Studio, plik manifestu jest tworzony za Ciebie. Większość niezbędnych elementów jest dodawana podczas tworzenia aplikacji, zwłaszcza w przypadku korzystania z szablonów kodu.

Funkcje pliku

W sekcjach poniżej opisujemy, jak niektóre najważniejsze cechy aplikacji są odzwierciedlane w pliku manifestu.

Komponenty aplikacji

Dla każdego komponentu aplikacji utworzonego w aplikacji zadeklaruj odpowiedni element XML w pliku manifestu:

• <activity> dla każdej podklasy w klasie Activity
• <service> dla każdej podklasy w klasie Service
• <receiver> dla każdej podklasy w klasie BroadcastReceiver
• <provider> dla każdej podklasy w klasie ContentProvider

Jeśli podklasyfikujesz którykolwiek z tych komponentów bez zadeklarowania go w pliku manifestu, system nie będzie mógł go uruchomić.

Podaj nazwę podklasy za pomocą atrybutu name, korzystając z pełnego oznaczenia pakietu. Na przykład podklasa Activity jest zadeklarowana w ten sposób:

<manifest ... >
    <application ... >
        <activity android:name="com.example.myapp.MainActivity" ... >
        </activity>
    </application>
</manifest>

Jeśli jednak pierwszym znakiem wartości name jest kropka, nazwa jest poprzedzona przestrzenią nazw aplikacji z właściwości namespace na poziomie modułu build.gradle. Jeśli np. przestrzeń nazw to "com.example.myapp", ta nazwa aktywności przyjmuje postać com.example.myapp.MainActivity:

<manifest ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

Więcej informacji o ustawianiu nazwy pakietu lub przestrzeni nazw znajdziesz w artykule Ustawianie przestrzeni nazw.

Jeśli masz komponenty aplikacji znajdujące się w podpakietach, np. w com.example.myapp.purchases, wartość name musi dodać brakujące nazwy podpakietów, takie jak ".purchases.PayActivity", lub użyć w pełni kwalifikowanej nazwy pakietu.

Filtry intencji

Działania, usługi i odbiorniki w aplikacji są aktywowane przez zamiary. Intencja to komunikat zdefiniowany przez obiekt Intent opisujący działanie do wykonania, w tym dane, na których ma zostać wykonana, kategoria komponentu, który powinien wykonać to działanie, oraz inne instrukcje.

Gdy aplikacja zgłasza intencję do systemu, system znajduje komponent aplikacji, który może obsłużyć intencję na podstawie deklaracji filtra intencji w pliku manifestu każdej aplikacji. System uruchamia instancję pasującego komponentu i przekazuje do niego obiekt Intent. Jeśli więcej niż 1 aplikacja obsługuje intencję, użytkownik może wybrać aplikację, której chce użyć.

Komponent aplikacji może mieć dowolną liczbę filtrów intencji (zdefiniowanych za pomocą elementu <intent-filter>), z których każdy opisuje inne możliwości danego komponentu.

Więcej informacji znajdziesz w dokumentacji intencji i filtrów intencji.

Ikony i etykiety

Niektóre elementy pliku manifestu mają atrybuty icon i label, które służą do wyświetlania użytkownikom odpowiednio małej ikony i etykiety tekstowej.

W każdym przypadku ikona i etykieta ustawione w elemencie nadrzędnym stają się wartością domyślną icon i label wszystkich elementów podrzędnych. Na przykład ikona i etykieta ustawione w elemencie <application> są domyślną ikoną i etykietą każdego komponentu aplikacji, np. wszystkich aktywności.

Ikona i etykieta ustawione w elemencie <intent-filter> komponentu wyświetlają się użytkownikowi, gdy ten komponent pojawia się jako opcja realizacji intencji. Domyślnie ikona jest dziedziczona z ikony zadeklarowanej w komponencie nadrzędnym – z elementu <activity> lub <application>.

Możesz zmienić ikonę filtra intencji, jeśli zawiera on unikalne działanie, które chcesz lepiej wskazać w oknie wyboru. Więcej informacji znajdziesz w artykule Zezwalanie innym aplikacjom na rozpoczynanie Twojej aktywności.

Uprawnienia

Aplikacje na Androida muszą prosić o pozwolenie na dostęp do poufnych danych użytkownika, takich jak kontakty i SMS-y, lub do niektórych funkcji systemu, takich jak aparat czy dostęp do internetu. Każde uprawnienie jest oznaczone unikalną etykietą. Na przykład aplikacja, która musi wysyłać SMS-y, musi mieć w pliku manifestu ten wiersz:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

Począwszy od Androida 6.0 (poziom interfejsu API 23) użytkownik może zatwierdzać i odrzucać niektóre uprawnienia aplikacji w czasie działania. Niezależnie od tego, którą wersję Androida obsługuje Twoja aplikacja, wszystkie żądania uprawnień musisz zadeklarować za pomocą elementu <uses-permission> w pliku manifestu. Jeśli to zrobisz, aplikacja będzie mogła korzystać z chronionych funkcji. W przeciwnym razie próby uzyskania dostępu do tych funkcji zakończą się niepowodzeniem.

Aplikacja może też chronić własne komponenty za pomocą uprawnień. Może korzystać z dowolnych uprawnień zdefiniowanych przez Androida (wymienionych w sekcji android.Manifest.permission) lub z uprawnień zadeklarowanych w innej aplikacji. Aplikacja może też definiować własne uprawnienia. W elemencie <permission> zadeklarowano nowe uprawnienie.

Więcej informacji znajdziesz w sekcji Uprawnienia na Androidzie.

Zgodność urządzeń

W pliku manifestu możesz też określić, jakich typów sprzętu lub oprogramowania wymaga Twoja aplikacja, a także – z jakich typów urządzeń jest zgodna. Sklep Google Play nie umożliwia użytkownikom instalowania Twojej aplikacji na urządzeniach, które nie mają wymaganych funkcji lub wersji systemu.

Istnieje kilka tagów manifestu, które określają, z którymi urządzeniami zgodna jest Twoja aplikacja. Oto kilka najczęstszych.

<uses-feature>

Element <uses-feature> pozwala zadeklarować funkcje sprzętu i oprogramowania, których potrzebuje Twoja aplikacja. Jeśli np. aplikacja nie może działać na urządzeniu bez czujnika kompasu, możesz go zadeklarować jako wymagany, używając tego tagu manifestu:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

Uwaga: jeśli chcesz udostępniać aplikację na Chromebookach, musisz wziąć pod uwagę pewne ograniczenia funkcji sprzętu i oprogramowania. Więcej informacji znajdziesz w artykule na temat zgodności pliku manifestu aplikacji na Chromebookach.

<uses-sdk>

Każda kolejna wersja platformy często dodaje nowe interfejsy API, które nie były dostępne w poprzedniej wersji. Aby wskazać minimalną wersję, z którą jest zgodna Twoja aplikacja, plik manifestu musi zawierać tag <uses-sdk> i jego atrybut minSdkVersion.

Pamiętaj jednak, że atrybuty w elemencie <uses-sdk> są zastępowane przez odpowiednie właściwości w pliku build.gradle. Jeśli używasz Androida Studio, zamiast tego podaj w nich wartości minSdkVersion i targetSdkVersion:

android {
    defaultConfig {
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdkVersion 21

        // Specifies the API level used to test the app.
        targetSdkVersion 33
        ...
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(21)

        // Specifies the API level used to test the app.
        targetSdkVersion(33)
        ...
    }
}

Aby dowiedzieć się więcej o pliku build.gradle, przeczytaj, jak skonfigurować kompilację.

Aby dowiedzieć się, jak zadeklarować obsługę różnych urządzeń, zapoznaj się z omówieniem zgodności urządzeń.

Konwencje plików

W tej sekcji opisano konwencje i reguły, które dotyczą wszystkich elementów i atrybutów w pliku manifestu.

Elementy

Wymagane są tylko elementy <manifest> i <application>. Każde z nich musi wystąpić tylko raz. Większość pozostałych elementów może wystąpić 0 lub więcej razy. Jednak niektóre z nich muszą być obecne, aby plik manifestu był przydatny.

Wszystkie wartości są ustawiane za pomocą atrybutów, a nie danych znaków w elemencie.

Elementy na tym samym poziomie zwykle nie są uporządkowane. Na przykład elementy <activity>, <provider> i <service> mogą być umieszczone w dowolnej kolejności. Istnieją 2 ważne wyjątki od tej reguły:

• Element <activity-alias> musi następować po elemencie <activity>, dla którego jest aliasem.
• Element <application> musi być ostatnim elementem w elemencie <manifest>.

Atrybuty

Z technicznego punktu widzenia wszystkie atrybuty są opcjonalne. Aby element mógł osiągnąć swój cel, trzeba jednak określić wiele atrybutów. W przypadku atrybutów naprawdę opcjonalnych w dokumentacji referencyjnej znajdziesz wartości domyślne.

Z wyjątkiem niektórych atrybutów głównego elementu <manifest> wszystkie ich nazwy zaczynają się od prefiksu android:, np. android:alwaysRetainTaskState. Prefiks jest uniwersalny, dlatego w dokumentacji zwykle jest on pomijany w przypadku atrybutów według nazwy.

Wiele wartości

Jeśli można określić więcej niż 1 wartość, element jest prawie zawsze powtarzany, a nie kilka wartości w jednym elemencie. Na przykład filtr intencji może zawierać listę kilku działań:

<intent-filter ... >
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.INSERT" />
    <action android:name="android.intent.action.DELETE" />
    ...
</intent-filter>

Wartości zasobów

Niektóre atrybuty mają wartości wyświetlane użytkownikom, takie jak tytuł aktywności lub ikona aplikacji. Wartości tych atrybutów mogą się różnić w zależności od języka użytkownika lub innych konfiguracji urządzenia (np. przez udostępnienie innego rozmiaru ikony w zależności od gęstości pikseli na urządzeniu), dlatego wartości należy ustawiać z zasobu lub motywu, a nie kodować na stałe w pliku manifestu. Rzeczywista wartość może się wtedy zmieniać w zależności od zasobów alternatywnych podanych przez Ciebie dla różnych konfiguracji urządzeń.

Zasoby są wyrażane jako wartości w następującym formacie:

"@[package:]type/name"

Możesz pominąć nazwę package, jeśli zasób jest udostępniany przez Twoją aplikację (np. jeśli jest udostępniany przez zależność biblioteki, ponieważ zasoby biblioteki są scalane w Twoją). Jedyną inną prawidłową nazwą pakietu jest android, gdy chcesz użyć zasobu ze platformy Androida.

type to typ zasobu, taki jak string lub drawable, a name to nazwa, która identyfikuje konkretny zasób. Oto przykład:

<activity android:icon="@drawable/smallPic" ... >

Więcej informacji o dodawaniu zasobów do projektu znajdziesz w artykule Omówienie zasobów aplikacji.

Aby zamiast tego zastosować wartość zdefiniowaną w motywie, pierwszym znakiem musi być ?, a nie @:

"?[package:]type/name"

Wartości ciągów znaków

Jeśli wartość atrybutu jest ciągiem znaków, użyj podwójnych ukośników lewych (\\), aby zmienić znaczenie znaków, np. \\n w przypadku nowego wiersza lub \\uxxxx w przypadku znaku Unicode.

Odniesienie do elementów pliku manifestu

W tej tabeli znajdziesz linki do dokumentów referencyjnych dotyczących wszystkich prawidłowych elementów w pliku AndroidManifest.xml.

Przykładowy plik manifestu

Poniższy kod XML to prosty przykład AndroidManifest.xml, który deklaruje 2 działania dla aplikacji.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0">

    <!-- Beware that these values are overridden by the build.gradle file -->
    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <!-- This name is resolved to com.example.myapp.MainActivity
             based on the namespace property in the build.gradle file -->
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <activity
            android:name=".DisplayMessageActivity"
            android:parentActivityName=".MainActivity" />
    </application>
</manifest>