インテントとインテント フィルタ

Intent は、別のアプリ コンポーネントからのアクションをリクエストするために使用できるメッセージング オブジェクトです。インテントを使用することでコンポーネント間の通信を促進する方法はいくつかありますが、基本的な使用例は次の 3 つです。

  • アクティビティの開始

    Activity はアプリ内の 1 つの画面を表します。Activity の新しいインスタンスを開始するには、IntentstartActivity() に渡します。Intent は、開始するアクティビティを記述し、必要なデータすべてを含んでいます。

    アクティビティの完了時に結果を受け取る場合は、startActivityForResult() を呼び出します。アクティビティは、その結果をアクティビティの onActivityResult() コールバック内の個別の Intent オブジェクトとして受け取ります。詳しくは、アクティビティ ガイドをご覧ください。

  • サービスの開始

    Service は、ユーザー インターフェースを持たず、バックグラウンドで操作を実行するコンポーネントです。Android 5.0(API レベル 21)以降では、JobScheduler を使用してサービスを開始できます。JobScheduler の詳細については、API-reference documentation をご覧ください。

    Android 5.0(API レベル 21)より前のバージョンでは、Service クラスのメソッドを使用してサービスを開始できます。サービスを開始して 1 回限りの操作を実行する(ファイルのダウンロードなど)には、IntentstartService() に渡します。Intent は、開始するサービスを記述し、必要なデータすべてを含んでいます。

    サービスがクライアント サーバー インターフェースを使用して設計されている場合は、IntentbindService() に渡すことで、別のコンポーネントからサービスにバインドできます。詳細については、サービス ガイドをご覧ください。

  • ブロードキャストの配信

    ブロードキャストは、アプリが受け取ることのできるメッセージです。システムは、システムの起動や端末の充電開始など、さまざまなシステム イベントを配信します。IntentsendBroadcast() または sendOrderedBroadcast() に渡すことで、他のアプリにブロードキャストを配信できます。

このページの後半では、インテントの仕組みと使用方法について説明します。関連情報については、他のアプリと連携するコンテンツを共有するをご覧ください。

インテントのタイプ

インテントには 2 つのタイプがあります。

  • 明示的インテントでは、完全な ComponentName を指定することで、インテントを満たすアプリのコンポーネントを指定します。通常は開始するアクティビティやサービスのクラス名がわかっているため、明示的インテントを使用してアプリ内のコンポーネントを開始します。たとえば、ユーザー操作に応答してアプリ内で新しいアクティビティを開始したり、バックグラウンドでファイルをダウンロードするサービスを開始したりできます。
  • 暗黙的インテントでは、特定のコンポーネントを指定せず、代わりに実行する全般的な動作を宣言することで、他のアプリからコンポーネントを処理できるようにします。たとえば、マップ上にユーザーの位置を表示する場合、暗黙的インテントを使って、特定の場所をマップ上に表示できる別のアプリにその操作を要求します。

図 1 は、アクティビティの開始時にインテントがどのように使用されるかを示しています。Intent オブジェクトで特定のアクティビティ コンポーネントの名前を明示的に指定すると、システムはすぐにそのコンポーネントを起動します。

図 1. 暗黙的インテントが他のアクティビティを開始するようシステム内に配信される仕組み: [1] Activity A がアクションの記述を使って Intent を作成し、それを startActivity() に渡します。[2] Android システムは、すべてのアプリでインテントに一致するインテント フィルタを検索します。一致するものが見つかったら、[3] システムは onCreate() メソッドを呼び出して Intent を渡すことで、一致するアクティビティ(Activity B)を開始します。

暗黙的インテントを使用すると、Android システムはインテントの内容を、デバイス上の他のアプリのマニフェスト ファイルで宣言されたインテント フィルタと比較して、開始すべきコンポーネントを見つけます。インテントがインテント フィルタと一致する場合、システムはそのコンポーネントを起動し、Intent オブジェクトを配信します。複数のインテント フィルタが競合する場合、ユーザーが仕様するアプリを選択できるようシステムによってダイアログが表示されます。

インテント フィルタは、コンポーネントが受け取りたいインテントのタイプを指定する式で、アプリのマニフェスト ファイルに含まれています。たとえば、アクティビティに対してインテント フィルタを宣言すると、他のアプリが特定のインテントでアクティビティを直接開始できるようになります。同様に、アクティビティに対してインテント フィルタを宣言しない場合は、明示的インテントでのみ開始できます。

注意: アプリの安全性を確保するため、Service の起動には必ず明示的インテントを使用します。このサービスにはインテント フィルタを宣言しないでください。暗黙的インテントを使用してサービスを開始すると、どのサービスがインテントに応答するのかを把握できず、ユーザーにはどのサービスが開始するのかがわからないため、セキュリティ上の危険が伴います。Android 5.0(API レベル 21)以降では、暗黙的インテントを使用して bindService() を呼び出すと、システムから例外がスローされます。

インテントを作成する

Intent オブジェクトには、Android システムが起動するコンポーネントを決定するために使用する情報(インテントを受け取る正確なコンポーネント名やコンポーネント カテゴリなど)と、受信側のコンポーネントがアクションを適切に実行するために使用する情報(実行するアクションや操作対象のデータなど)が含まれます。

Intent に含まれる主な情報は次のとおりです。

コンポーネント名
開始するコンポーネントの名前。

これは省略可能ですが、インテントを明示的にするためには不可欠な情報です。つまり、コンポーネント名で定義されたアプリ コンポーネントにのみ、インテントが配信されます。コンポーネント名がない場合、インテントは暗黙的になり、他のインテント情報(下記で説明するアクション、データ、カテゴリなど)に基づいてインテントを受け取るべきコンポーネントをシステムが決定します。アプリ内の特定のコンポーネントを開始する必要がある場合は、コンポーネント名を指定する必要があります。

注: Service を起動するときは、必ずコンポーネント名を指定してください。指定しない場合、どのサービスがインテントに応答するかが把握できなくなり、ユーザーはどのサービスが開始するのかがわからなくなります。

Intent のこのフィールドは ComponentName オブジェクトです。このオブジェクトは、ターゲット コンポーネントの完全修飾クラス名(アプリのパッケージ名など)を使用して指定できます(例: com.example.ExampleActivity)。コンポーネント名は、setComponent()setClass()setClassName()、または Intent コンストラクタを使用して設定できます。

操作
実行する全体的なアクションを指定する文字列です(閲覧や選択など)。

ブロードキャスト インテントの場合、これは実行され、報告されるアクションです。ほとんどのアクションは、残りのインテントがどのように構成されているか、特にデータやエクストラに含まれている情報によって決まります。

アプリ内のインテントで使用する(または他のアプリがアプリ内のコンポーネントを呼び出すために)使用する独自のアクションを指定できますが、通常は Intent クラスまたは他のフレームワーク クラスで定義されたアクション定数を指定します。アクティビティを開始する際の一般的な操作は次のとおりです。

ACTION_VIEW
ギャラリー アプリで表示する写真や、マップアプリで表示する住所など、アクティビティ内にユーザーに表示する情報がある場合は、startActivity() を使ってインテントにこのアクションを使用します。
ACTION_SEND
これは「共有」インテントとしても知られており、メールアプリやソーシャル シェアリング アプリなどの他のアプリ経由でユーザーが共有できるデータがある場合に、startActivity() でインテントに使用します。

汎用アクションを定義するその他の定数については、Intent クラスのリファレンスをご覧ください。システムの設定アプリで特定の画面を開くアクションの Settings など、他のアクションは Android フレームワークの別の場所で定義されます。

インテントのアクションは、setAction() または Intent コンストラクタを使って指定できます。

独自のアクションを定義する場合は、次の例に示すように、接頭辞としてアプリのパッケージ名を必ず含めます。

Kotlin

const val ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL"

Java

static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";
データ
アクションの実行対象であるデータや、データの MIME タイプを参照する URI(Uri オブジェクト)です。提供されるデータのタイプは、一般にインテントのアクションによって決まります。たとえば、アクションが ACTION_EDIT の場合、データには編集するドキュメントの URI が含まれている必要があります。

インテントを作成するときは、URI だけでなくデータのタイプ(MIME タイプ)も指定することが重要になります。たとえば、画像を表示できるアクティビティは、URI の形式が類似していても、音声ファイルを再生できない可能性があります。データの MIME タイプを指定すると、Android システムがインテントを受け取る最適なコンポーネントを見つけやすくなります。ただし、特にデータが content: URI の場合、MIME タイプは URI から推測できる場合があります。content: URI は、データがデバイス上にあり、ContentProvider によって制御されていることを示します。これにより、データの MIME タイプがシステムに表示されます。

データ URI のみを設定するには、setData() を呼び出します。MIME タイプのみを設定するには、setType() を呼び出します。必要に応じて、setDataAndType() を使用して両方を明示的に設定することもできます。

注意: URI と MIME タイプの両方を設定する場合は、setData()setType() を呼び出さないでください。どちらも互いの値を null にするためです。URI と MIME タイプの両方を設定する場合は、必ず setDataAndType() を使用してください。

カテゴリ
インテントを処理するコンポーネントの種類に関する追加情報が含まれた文字列です。カテゴリの記述は、インテントにいくつでも含めることができますが、ほとんどのインテントではカテゴリは必須ではありません。一般的なカテゴリは次のとおりです。
CATEGORY_BROWSABLE
ターゲットのアクティビティは、ウェブブラウザから開始して画像やメール メッセージなど、リンクで参照されたデータを表示できます。
CATEGORY_LAUNCHER
アクティビティはタスクの初期アクティビティであり、システムのアプリ ランチャーにリストされます。

カテゴリの全一覧は、Intent クラスの説明をご覧ください。

カテゴリは addCategory() で指定できます。

上記のプロパティ(コンポーネント名、アクション、データ、カテゴリ)は、インテントの特性の定義を表しています。Android システムは、これらのプロパティを読み取ることで、開始するアプリ コンポーネントを解決できます。ただし、インテントにはアプリ コンポーネントの解決に影響を与えない追加情報を含めることもできます。インテントに含めることのできる情報は次のとおりです。

おまけ
要求されたアクションの実行に必要な追加情報のキーと値のペアです。一部のアクションが特定の種類のデータ URI を使用するのと同様に、一部のアクションは特定のエクストラを使用します。

エクストラはさまざまな putExtra() メソッドを使って追加でき、それぞれがキー名と値の 2 つのパラメータを受け入れます。追加データをすべて含む Bundle オブジェクトを作成し、putExtras() を使用して IntentBundle を挿入することもできます。

たとえば、ACTION_SEND を使ってメールを送信するインテントを作成するとき、EXTRA_EMAIL キーを使って「宛先」の受信者を指定したり、EXTRA_SUBJECT キーを使って「件名」を指定したりできます。

Intent クラスは、標準化されたデータ型の多くの EXTRA_* 定数を指定します。(アプリが受け取るインテントのために)独自の追加キーを宣言する必要がある場合は、次の例のようにアプリのパッケージ名を接頭辞として含めてください。

Kotlin

const val EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS"

Java

static final String EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS";

注意: 別のアプリが受信することを想定したインテントを送信する場合は、Parcelable データまたは Serializable データを使用しないでください。アプリが Bundle オブジェクト内のデータにアクセスしようとしたものの、Parceled クラスまたはシリアル化されたクラスにアクセスできない場合、システムは RuntimeException を発生させます。

フラグ
フラグは、インテントのメタデータとして機能する Intent クラスで定義されます。フラグは、Android システムにアクティビティの起動方法(アクティビティがどのタスクに属するかなど)や、起動後の取り扱い方法(最近のアクティビティの一覧に含めるかどうかなど)を指示します。

詳細については、setFlags() メソッドをご覧ください。

明示的インテントの例

明示的インテントは、アプリ内の特定のアクティビティやサービスなど、特定のアプリ コンポーネントを起動する際に使用するものです。明示的インテントを作成するには、Intent オブジェクトのコンポーネント名を定義します。他のインテント プロパティはすべて省略可能です。

たとえば、アプリでウェブからファイルをダウンロードするサービスを DownloadService という名前で作成した場合、次のコードでそれを開始できます。

Kotlin

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
val downloadIntent = Intent(this, DownloadService::class.java).apply {
    data = Uri.parse(fileUrl)
}
startService(downloadIntent)

Java

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
Intent downloadIntent = new Intent(this, DownloadService.class);
downloadIntent.setData(Uri.parse(fileUrl));
startService(downloadIntent);

Intent(Context, Class) コンストラクタはアプリ Context とコンポーネントに Class オブジェクトを提供します。そのため、このインテントはアプリの DownloadService クラスを明示的に開始します。

サービスの作成と起動の詳細については、サービスのガイドをご覧ください。

暗黙的インテントの例

暗黙的インテントは、端末上のどんなアプリでも実行できるアクションを指定します。暗黙的インテントは、自身のアプリではそのアクションを実行できないが、他のアプリでは実行可能であり、どのアプリを使うかをユーザーに選ばせたい場合に便利です。

たとえば、他のユーザーに共有してほしいコンテンツがある場合は、ACTION_SEND アクションでインテントを作成し、共有するコンテンツを指定するエクストラを追加します。そのインテントで startActivity() を呼び出すと、ユーザーはどのアプリでコンテンツを共有するかを選択できます。

Kotlin

// Create the text message with a string.
val sendIntent = Intent().apply {
    action = Intent.ACTION_SEND
    putExtra(Intent.EXTRA_TEXT, textMessage)
    type = "text/plain"
}

// Try to invoke the intent.
try {
    startActivity(sendIntent)
} catch (e: ActivityNotFoundException) {
    // Define what your app should do if no activity can handle the intent.
}

Java

// Create the text message with a string.
Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, textMessage);
sendIntent.setType("text/plain");

// Try to invoke the intent.
try {
    startActivity(sendIntent);
} catch (ActivityNotFoundException e) {
    // Define what your app should do if no activity can handle the intent.
}

startActivity() が呼び出されたとき、システムによってすべてのインストール済みアプリの中にこのタイプのインテント(ACTION_SEND アクションとテキスト/プレーン データが含まれるインテント)を処理できるものがあるかどうかが確認されます。インテントを処理できるアプリが 1 つしかない場合は、そのアプリがすぐに開いてインテントを受け取ります。他のアプリがこれを処理できない場合、アプリは、発生した ActivityNotFoundException をキャッチできます。インテントを処理できるアクティビティが複数ある場合、図 2 のようなダイアログが表示され、ユーザーが使用するアプリを選択できます。

他のアプリの起動について詳しくは、ユーザーを別のアプリに誘導するに関するガイドをご覧ください。

図 2. チューザ ダイアログ

アプリチューザを表示する

暗黙的インテントに応答するアプリが 2 つ以上ある場合、ユーザーは使用するアプリを選択でき、そのアプリをアクションに対するデフォルトの選択肢にすることができます。デフォルトを選択できる機能は、ウェブページを開くときなど、ユーザーが毎回同じアプリを使用したいアクションを実行する場合に便利です(多くの場合、ユーザーは 1 つのウェブブラウザのみを希望します)。

ただし、複数のアプリがインテントに応答でき、ユーザーが毎回異なるアプリを使用したい場合は、選択ツール ダイアログを明示的に表示する必要があります。チューザ ダイアログでは、アクションに使用するアプリを選択するようユーザーに求めます(ユーザーはアクションのデフォルト アプリを選択することはできません)。たとえば、アプリが ACTION_SEND アクションを使って「共有」を実行するとき、ユーザーが現在の状況によって別のアプリを使用して共有する場合もあるため、図 2 のようにチューザのダイアログは常に表示する必要があります。

選択ツールを表示するには、次の例に示すように、createChooser() を使用して Intent を作成し、startActivity() に渡します。この例では、createChooser() メソッドに渡されたインテントに応答するアプリのリストを示すダイアログが表示され、指定されたテキストがダイアログのタイトルになります。

Kotlin

val sendIntent = Intent(Intent.ACTION_SEND)
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
val title: String = resources.getString(R.string.chooser_title)
// Create intent to show the chooser dialog
val chooser: Intent = Intent.createChooser(sendIntent, title)

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(packageManager) != null) {
    startActivity(chooser)
}

Java

Intent sendIntent = new Intent(Intent.ACTION_SEND);
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
String title = getResources().getString(R.string.chooser_title);
// Create intent to show the chooser dialog
Intent chooser = Intent.createChooser(sendIntent, title);

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(chooser);
}

インテントの安全でない起動を検出する

アプリは、アプリ内のコンポーネント間を移動するため、または別のアプリに代わってアクションを実行するため、インテントを起動することがあります。Android 12(API レベル 31)以降では、プラットフォームのセキュリティを強化するため、アプリがインテントの安全でない起動を実行したときに警告するデバッグ機能が導入されました。たとえば、アプリがネストされたインテントの安全でない起動を実行する場合があります。ネストされたインテントとは、別のインテント内でエクストラとして渡されるインテントのことです。

アプリが以下の両方のアクションを実行すると、システムは安全でないインテントの起動を検出し、StrictMode 違反が発生します。

  1. 配信されたインテントのエクストラから、ネストされたインテントを取り出した。
  2. そのネストされたインテントを使用して(たとえば startActivity()startService()、または bindService() にインテントを渡して)、アプリ コンポーネントを直ちに開始した。

この状況を識別してアプリに変更を加える方法について詳しくは、Medium の Android のネスト インテント に関するブログ記事をご覧ください。

安全でないインテントの起動を確認する

アプリでの安全でないインテントの起動を確認するには、VmPolicy を構成する際に detectUnsafeIntentLaunch() を呼び出します。次のコード スニペットをご覧ください。アプリで StrictMode 違反が検出された場合は、機密に該当する可能性がある情報を保護するために、アプリの実行を停止することをおすすめします。

Kotlin

fun onCreate() {
    StrictMode.setVmPolicy(VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build())
}

Java

protected void onCreate() {
    StrictMode.setVmPolicy(new VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build());
}

より厳格なインテントの使い方

安全でないインテントの起動や StrictMode 違反の発生を最小限に抑えるには、次のベスト プラクティスに従ってください。

インテント内の必須のエクストラのみをコピーして、必要なサニタイズと検証を行います。アプリは、あるインテントから、新しいコンポーネントの起動に使用される別のインテントに、エクストラをコピーすることがあります。これは、アプリが putExtras(Intent) または putExtras(Bundle) を呼び出したときに発生します。アプリがこれらのオペレーションのいずれかを実行する場合、受信コンポーネントで想定されるエクストラのみをコピーします。コピーを受信するインテントがエクスポートされていないコンポーネントを起動する場合は、エクストラをサニタイズして検証してから、コンポーネントを起動するインテントにコピーします。

アプリのコンポーネントを不必要にエクスポートしないでください。たとえば、内部ネストされたインテントを使用してアプリ コンポーネントを起動する場合は、そのコンポーネントの android:exported 属性を false に設定します。

ネストされたインテントではなく PendingIntent を使用してください。この方法では、別のアプリがそのアプリの IntentPendingIntent を展開すると、そのアプリはアプリの ID を使用して PendingIntent を起動できます。この構成により、他のアプリは、アプリのエクスポートされていないコンポーネントを含む任意のコンポーネントを安全に起動できます。

図 2 の図は、システムが(クライアント)アプリから別の(サービス)アプリに制御を渡し、アプリに戻す方法を示しています。

  1. アプリは、別のアプリのアクティビティを呼び出すインテントを作成します。そのインテント内に、PendingIntent オブジェクトをエクストラとして追加します。このペンディング インテントは、アプリ内のコンポーネントを呼び出します。このコンポーネントはエクスポートされません。
  2. アプリのインテントを受け取ると、もう一方のアプリは、ネストされた PendingIntent オブジェクトを抽出します。
  3. もう一方のアプリは、PendingIntent オブジェクトの send() メソッドを呼び出します。
  4. 制御をアプリに返すと、システムはアプリのコンテキストを使用してペンディング インテントを呼び出します。

図 2.ネストされたペンディング インテントを使用する場合のアプリ間通信の図。

暗黙的インテントを受け取る

アプリが受け取ることのできる暗黙的インテントを通知するには、マニフェスト ファイル<intent-filter> 要素を使ってアプリのコンポーネントごとに 1 つ以上のインテント フィルタを宣言します。各インテント フィルタは、インテントのアクション、データ、カテゴリに基づいて、受け入れるインテントのタイプを指定します。暗黙的インテントは、インテントがいずれかのインテント フィルタを通過できる場合にのみ、アプリ コンポーネントに配信されます。

注: 明示的インテントは、コンポーネントが宣言しているインテント フィルタに関係なく、常にターゲットに配信されます。

アプリ コンポーネントは、実行できる固有のジョブごとに個別のフィルタを宣言する必要があります。たとえば、画像ギャラリー アプリの 1 つのアクティビティに、画像を表示するフィルタと画像を編集するフィルタの 2 つのフィルタを設定できます。アクティビティが開始すると、Intent を調べて Intent にある情報に基づいてどのように動作するかを決定します(編集コントロールを表示するかどうかなど)。

各インテント フィルタは、アプリのマニフェスト ファイルの <intent-filter> 要素で定義され、これは対応するアプリのコンポーネント(<activity> 要素など)にネストされます。

<intent-filter> 要素を含む各アプリ コンポーネントで、android:exported の値を明示的に設定します。この属性は、他のアプリがアプリ コンポーネントにアクセスできるかどうかを示します。インテント フィルタに LAUNCHER カテゴリが含まれているアクティビティなど、この属性を true に設定すると便利な場合があります。それ以外の場合は、この属性を false に設定することをおすすめします。

警告: アプリ内のアクティビティ、サービス、ブロードキャスト レシーバがインテント フィルタを使用し、android:exported の値を明示的に設定していない場合、Android 12 以降を実行しているデバイスにアプリをインストールできません。

<intent-filter> 内で、次の 3 つの要素のなかで 1 つ以上を使用して、受け入れるインテントのタイプを指定できます。

<action>
name 属性で、受け入れるインテントのアクションを宣言します。この値は、クラス定数ではなく、アクションのリテラル文字列値にする必要があります。
<data>
データ URI(schemehostportpath)と MIME タイプのさまざまな要素を指定する 1 つ以上の属性を使用して、受け入れられるデータのタイプを宣言します。
<category>
受け入れるインテント カテゴリを name 属性で宣言します。値は、クラス定数ではなく、アクションのリテラル文字列値である必要があります。

注: 暗黙的インテントを受け取るには、インテント フィルタに CATEGORY_DEFAULT カテゴリを含める必要があります。startActivity() メソッドと startActivityForResult() メソッドは、CATEGORY_DEFAULT カテゴリを宣言しているものとして、すべてのインテントを処理します。インテント フィルタでカテゴリを宣言していない場合、暗黙的インテントはアクティビティに紐付けされません。

次に、データ タイプがテキストの場合に、ACTION_SEND インテントを受け取るインテント フィルタを使用したアクティビティ宣言の例を示します。

<activity android:name="ShareActivity" android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

<action><data><category> の複数のインスタンスが含まれるフィルタを作成できます。その場合は、コンポーネントがこれらのフィルタ要素のすべての組み合わせを処理できることを確認する必要があります。

アクション、データ、カテゴリタイプの特定の組み合わせでのみ、複数の種類のインテントを処理する場合は、複数のインテント フィルタを作成する必要があります。

暗黙的インテントは、3 つの要素それぞれへのインテントを比較して、フィルタでテストされます。コンポーネントに配信されるには、インテントが 3 つのテストすべてを通過する必要があります。いずれか 1 つでも一致しない場合、Android システムはコンポーネントにインテントを配信しません。ただし、コンポーネントは複数のインテント フィルタを保持していることもあるため、1 つのインテント フィルタを通過できなかったインテントでも、別のフィルタを通過できる場合があります。システムがインテントを解決する方法の詳細については、インテントの解決に関する後述のセクションをご覧ください。

注意: インテント フィルタを使用して他のアプリでコンポーネントを開始できないようにする方法は安全ではありません。インテント フィルタは、コンポーネントが特定の種類の暗黙的インテントのみに対応するように制限しますが、デベロッパーがコンポーネント名を決定した場合、別のアプリが明示的インテントを使用してアプリ コンポーネントを起動する可能性があります。独自のアプリのみがコンポーネントを起動できるようにすることが重要である場合は、マニフェストでインテント フィルタを宣言しないでください。代わりに、そのコンポーネントの exported 属性を "false" に設定します。

同様に、他のアプリの Service で誤って実行されないように、自身のサービスは常に明示的インテントを使用して開始してください。

注: すべてのアクティビティにおいて、インテント フィルタはマニフェスト ファイルで宣言する必要があります。ただし、ブロードキャスト レシーバのフィルタは、registerReceiver() を呼び出すことで動的に登録できます。その後、unregisterReceiver() を使用してレシーバーの登録を解除できます。これにより、アプリが実行中の特定の期間だけ、アプリが特定のブロードキャストをリッスンできるようになります。

フィルタの例

インテント フィルタの動作を示すため、ソーシャル シェアリング アプリのマニフェスト ファイルの例を以下に示します。

<activity android:name="MainActivity" android:exported="true">
    <!-- This activity is the main entry, should appear in app launcher -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity android:name="ShareActivity" android:exported="false">
    <!-- This activity handles "SEND" actions with text data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
    <!-- This activity also handles "SEND" and "SEND_MULTIPLE" with media data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <action android:name="android.intent.action.SEND_MULTIPLE"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="application/vnd.google.panorama360+jpg"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="video/*"/>
    </intent-filter>
</activity>

最初のアクティビティ MainActivity は、アプリのメイン エントリ ポイントです。ユーザーがランチャー アイコンから初めてアプリを起動したときに開くアクティビティです。

  • ACTION_MAIN アクションが、これがメインのエントリ ポイントで、インテント データはないことを示しています。
  • CATEGORY_LAUNCHER カテゴリは、このアクティビティのアイコンをシステムのアプリ ランチャーに配置する必要があることを示しています。<activity> 要素で icon を使ってアイコンを指定しない場合、システムは <application> 要素のアイコンを使用します。

アクティビティをアプリ ランチャーに表示するには、この 2 つをペア設定する必要があります。

2 つ目のアクティビティである ShareActivity は、テキストやメディア コンテンツの共有を促すためのものです。ユーザーは MainActivity に移動することでこのアクティビティに入ることもありますが、2 つのインテント フィルタのいずれかに一致する暗黙的インテントを発行する別のアプリから直接 ShareActivity に入ることもできます。

注: MIME タイプ(application/vnd.google.panorama360+jpg)はパノラマ写真を指定する特殊なデータタイプで、Google パノラマ API で処理できます。

インテントと他のアプリのインテント フィルタを一致させる

別のアプリが Android 13(API レベル 33)以降をターゲットとしている場合、そのアプリは、アプリのインテントがそのアプリの <intent-filter> 要素のアクションとカテゴリと一致する場合にのみ、アプリのインテントを処理できます。一致が見つからない場合、ActivityNotFoundException がスローされます。送信側のアプリはこの例外を処理する必要があります。

同様に、Android 13 以上をターゲットとするようにアプリを更新した場合、外部アプリから発信されるすべてのインテントは、アプリで宣言された <intent-filter> 要素のアクションとカテゴリと一致する場合にのみ、アプリのエクスポート済みコンポーネントに配信されます。この動作は、送信元アプリのターゲット SDK バージョンに関係なく発生します。

次の場合、インテント マッチングは適用されません。

  • インテント フィルタを宣言していないコンポーネントに配信されるインテント。
  • 同じアプリからのインテント。
  • システムからのインテント、つまり「システム UID」(uid=1000)から送信されるインテント。システムアプリとしては、system_server と、android:sharedUserIdandroid.uid.system に設定するアプリがあります。
  • ルートからのインテント。

詳しくは、インテント マッチングについての記事をご覧ください。

ペンディング インテントを使用する

PendingIntent オブジェクトは、Intent オブジェクトをラップするオブジェクトです。PendingIntent の主な目的は、別のアプリケーションに、アプリ自身のプロセスから実行したように、含まれる Intent を使用できる権限を付与することです。

ペンディング インテントの主な使用例には、次のようなものがあります。

  • ユーザーが通知を使ってアクションを実行するときに実施するインテントを宣言する(Android システムの NotificationManagerIntent を実行します)。
  • ユーザーがアプリ ウィジェットを使ってアクションを実行するときに実施するインテントを宣言する(ホーム画面のアプリが Intent を実行します)。
  • 今後の指定された時間に実施するインテントを宣言する(Android システムの AlarmManagerIntent を実行します)。

Intent オブジェクトは、特定のタイプのアプリ コンポーネント(ActivityServiceBroadcastReceiver のいずれか)で処理されることを前提としているため、PendingIntent も同様の前提で作成する必要があります。ペンディング インテントを使用している場合、アプリは startActivity() などの呼び出しではインテントを実行しません。代わりに、PendingIntent の作成時にそれぞれのクリエーター メソッドを呼び出して目的のコンポーネント タイプを宣言する必要があります。

アプリが他のアプリからペンディング インテントを受け取る場合を除いて、PendingIntent の作成時に必要となる PendingIntent メソッドはほぼ上記の 3 つのみです。

各メソッドは、現在のアプリ Context、ラップする Intent、インテントの使用方法を指定する 1 つ以上のフラグ(インテントを 2 回以上できるかどうかなど)を受け取ります。

ペンディング インテントの使用に関する詳細については、通知アプリ ウィジェットの API ガイドなど、それぞれのユースケースのドキュメントをご覧ください。

可変性を指定する

Android 12 以降をターゲットとするアプリの場合、アプリが作成する各 PendingIntent オブジェクトの可変性を指定する必要があります。特定の PendingIntent オブジェクトが可変または不変であることを宣言するには、PendingIntent.FLAG_MUTABLE フラグまたは PendingIntent.FLAG_IMMUTABLE フラグをそれぞれ使用します。

アプリがどちらの可変性フラグも設定せずに PendingIntent オブジェクトを作成しようとすると、IllegalArgumentException がスローされ、logcat に次のメッセージが表示されます。

PACKAGE_NAME: Targeting S+ (version 31 and above) requires that one of \
FLAG_IMMUTABLE or FLAG_MUTABLE be specified when creating a PendingIntent.

Strongly consider using FLAG_IMMUTABLE, only use FLAG_MUTABLE if \
some functionality depends on the PendingIntent being mutable, e.g. if \
it needs to be used with inline replies or bubbles.

可能な限り不変のペンディング インテントを作成する

ほとんどの場合において、アプリでは不変の PendingIntent オブジェクトを作成するようにしてください(次のコード スニペットを参照)。PendingIntent オブジェクトが不変の場合、他のアプリはインテントを変更して、インテントの呼び出し結果を調整することはできません。

Kotlin

val pendingIntent = PendingIntent.getActivity(applicationContext,
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE)

Java

PendingIntent pendingIntent = PendingIntent.getActivity(getApplicationContext(),
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE);

ただし、次のユースケースでは可変の PendingIntent オブジェクトが必要です。

  • 通知のダイレクト返信アクションのサポート。ダイレクト返信では、返信に関連付けられた PendingIntent オブジェクト内のクリップデータの変更が必要です。通常は、fillIn() メソッドに FILL_IN_CLIP_DATA をフラグとして渡すことにより、この変更をリクエストします。
  • CarAppExtender のインスタンスを使用して、通知を Android Auto フレームワークに関連付ける。
  • PendingIntent のインスタンスを使用して会話をバブルに配置する。可変の PendingIntent オブジェクトを使用すると、システムは FLAG_ACTIVITY_MULTIPLE_TASKFLAG_ACTIVITY_NEW_DOCUMENT などの正しいフラグを適用できます。
  • requestLocationUpdates() などの API を呼び出して、デバイスの位置情報をリクエストする。可変の PendingIntent オブジェクトを使用すると、位置情報のライフサイクル イベントを表すインテント エクストラを追加できます。これらのイベントには、場所の変更やプロバイダの利用可能化が含まれます。
  • AlarmManager を使用したアラームのスケジュールの設定。可変の PendingIntent オブジェクトを使用すると、システムで EXTRA_ALARM_COUNT インテント エクストラを追加できます。この追加情報は、繰り返しアラートがトリガーされた回数を表します。このエクストラを含めると、インテントは、デバイスがスリープ状態だったときなど、繰り返しアラームが複数回トリガーされたかどうかについて、アプリに正確に通知できます。

アプリで可変の PendingIntent オブジェクトを作成する場合は、明示的インテントを使用して ComponentName を設定することを強くおすすめします。そうすれば、別のアプリが PendingIntent を呼び出してアプリに制御を戻すたびに、常にアプリ内の同じコンポーネントが開始されます。

ペンディング インテント内で明示的インテントを使用する

他のアプリがアプリのペンディング インテントを使用する方法を適切に定義するには、必ずペンディング インテントを明示的インテントでラップします。このベスト プラクティスに沿って対応するには、次の手順を行います。

  1. ベース インテントのアクション、パッケージ、コンポーネントの各フィールドが設定されていることを確認します。
  2. Android 6.0(API レベル 23)で追加された FLAG_IMMUTABLE を使用して、保留中のインテントを作成します。このフラグにより、PendingIntent を受信したアプリが未入力プロパティを入力するのを防ぐことができます。アプリの minSdkVersion22 以下の場合は、次のコードを使用して安全性と互換性を同時に提供できます。

    if (Build.VERSION.SDK_INT >= 23) {
      // Create a PendingIntent using FLAG_IMMUTABLE.
    } else {
      // Existing code that creates a PendingIntent.
    }

インテントの解決

システムがアクティビティを開始する暗黙的インテントを受け取ると、次の 3 つの側面に基づいてインテントをインテント フィルタと比較し、そのインテントに最適なアクティビティを検索します。

  • アクション。
  • データ(URI とデータタイプの両方)。
  • カテゴリ。

以下のセクションでは、アプリのマニフェスト ファイル内のインテント フィルタ宣言に従って、インテントが適切なコンポーネントとどのようにマッチングされるかを説明します。

アクションのテスト

受け入れるインテントのアクションを指定するには、インテント フィルタでゼロ個以上の <action> 要素を宣言します。次の例をご覧ください。

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

このフィルタを通過するには、Intent で指定されたアクションが、フィルタにリストされたアクションのいずれかに一致する必要があります。

フィルタのリストにアクションが 1 つもない場合は、インテントに一致するものがないため、すべてのインテントがテストに失敗します。ただし、Intent がアクションを指定していない場合でも、フィルタに少なくとも 1 つのアクションが含まれていればテストに合格します。

カテゴリのテスト

受け入れるインテント カテゴリを指定するには、次の例に示すように、インテント フィルタで 0 個以上の <category> 要素を宣言します。

<intent-filter>
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    ...
</intent-filter>

インテントがカテゴリテストに合格するには、Intent 内のすべてのカテゴリがフィルタのカテゴリと一致する必要があります。逆は必要ありません。インテント フィルタでは、Intent で指定されたカテゴリよりも多くのカテゴリが宣言されている場合もありますが、Intent は引き続き合格します。そのため、カテゴリのないインテントは、フィルタで宣言されているカテゴリに関係なく、常にこのテストに合格することになります。

注: Android では、startActivity()startActivityForResult() に渡されるすべての暗黙的インテントに CATEGORY_DEFAULT カテゴリが自動的に適用されます。アクティビティで暗黙的インテントを受け取るには、前述の <intent-filter> の例に示すように、アクティビティのインテント フィルタに "android.intent.category.DEFAULT" のカテゴリを含める必要があります。

データテスト

受け入れるインテント データを指定するには、インテント フィルタでゼロ個以上の <data> 要素を宣言します。次の例をご覧ください。

<intent-filter>
    <data android:mimeType="video/mpeg" android:scheme="http" ... />
    <data android:mimeType="audio/mpeg" android:scheme="http" ... />
    ...
</intent-filter>

<data> 要素では、URI 構造とデータタイプ(MIME メディア タイプ)を指定できます。URI の各部分は、個別の属性(schemehostportpath)です。

<scheme>://<host>:<port>/<path>

次の例は、これらの属性で使用できる値を示しています。

content://com.example.project:200/folder/subfolder/etc

この URI では、スキームが content、ホストが com.example.project、ポートが 200、パスが folder/subfolder/etc です。

<data> 要素ではこれらの各属性は省略可能ですが、線形依存関係があります。

  • スキームが指定されていない場合、このホストは無視されます。
  • ホストが指定されていない場合、ポートは無視されます。
  • スキームとホストの両方が指定されていない場合、パスは無視されます。

インテント内の URI がフィルタ内の URI 仕様と比較される際は、フィルタに含まれる URI の部分のみと比較されます。例:

  • フィルタでスキームのみが指定されている場合、そのスキームのすべての URI がフィルタと一致します。
  • フィルタでスキームと認証局が指定されていて、パスが指定されていない場合、パスにかかわらず同じスキームと認証局を持つすべての URI がフィルタを通過します。
  • フィルタでスキーム、オーソリティ、パスが指定されている場合、同じスキーム、オーソリティ、パスを持つ URI のみがフィルタを通過します。

注: パスの指定では、ワイルドカードのアスタリスク(*)を使ってパス名の部分一致のみを要求することもできます。

データテストでは、インテントの URI と MIME タイプの両方を、フィルタで指定された URI と MIME タイプと比較します。ルールは次のとおりです。

  1. URI も MIME タイプも含まないインテントは、フィルタで URI も MIME タイプも指定していない場合にのみテストに合格します。
  2. URI を含んでいて MIME タイプを含んでいないインテント(明示的にも含まれておらず、URI からも推測できない)場合は、URI がフィルタの URI 形式に一致し、フィルタが MIME タイプを指定していない場合のみテストをパスします。
  3. MIME タイプを含んでいて、URI を含んでいないインテントは、フィルタのリストに同じ MIME タイプがあり、URI 形式が指定されていない場合のみテストをパスします。
  4. URI と MIME タイプの両方を含む(明示的または URI からの推測)インテントは、MIME タイプがフィルタのリストにあるタイプに一致した場合のみ、テストの MIME タイプのパートをパスします。テストの URI のパートは、URI がフィルタの URI に一致するか、content: URI または file: URI があって URI が指定されていない場合にパスできます。つまり、フィルタリストに MIME タイプのみがある場合、コンポーネントは content: データと file: データをサポートすると推定されます。

注: インテントで URI または MIME タイプが指定されている場合、<intent-filter><data> 要素がないと、データテストは失敗します。

この最後の規則(d)は、コンポーネントがファイルやコンテンツ プロバイダからのローカル データを取得できるという予測を反映しています。そのため、フィルタにはデータタイプのみをリストして、content: スキームと file: スキームを明示的に指定する必要はありません。次の例は、コンポーネントがコンテンツ プロバイダから画像データを取得して表示できることを Android に伝える <data> 要素の一般的なケースを示しています。

<intent-filter>
    <data android:mimeType="image/*" />
    ...
</intent-filter>

データタイプを指定しても URI を指定していないフィルタは、おそらく最も一般的な方法です。利用可能なデータのほとんどはコンテンツ プロバイダによって分配されるためです。

もうひとつ一般的な設定として、スキームとデータタイプを使ったフィルタがあります。たとえば、次の <data> 要素は、アクションを実行するためにコンポーネントがネットワークから動画データを取得できることを Android に伝えています。

<intent-filter>
    <data android:scheme="http" android:mimeType="video/*" />
    ...
</intent-filter>

インテント マッチング

インテントをインテント フィルタにマッチングする目的には、アクティベートするターゲットを発見するということだけでなく、端末上のコンポーネントのセットに関連する何かを発見するという目的があります。たとえば、ホーム アプリは、ACTION_MAIN アクションと CATEGORY_LAUNCHER カテゴリを指定するインテント フィルタを持つすべてのアクティビティを見つけることで、アプリ ランチャーを設定します。一致は、IntentFilter クラスのドキュメントに記載されているように、インテントのアクションとカテゴリがフィルタと一致する場合にのみ成功します。

アプリでは、Google Home アプリと同様の方法でインテント マッチングを使用できます。PackageManager には、特定のインテントを受け入れることのできるすべてのコンポーネントを返す一連の query...() メソッドと、同様にインテントに応答できる最適なコンポーネントを返す一連の resolve...() メソッドがあります。たとえば、queryIntentActivities() は引数として渡されたインテントを実行できるすべてのアクティビティのリストを返します。queryIntentServices() は同様のサービスのリストを返します。どちらの方法でもコンポーネントはアクティブになりません。応答できるコンポーネントのみがリストされます。ブロードキャスト レシーバー用にも、同様のメソッド queryBroadcastReceivers() があります。