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

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

• アクティビティの開始

  Activity はアプリ内の単一の画面を表します。Activity の新しいインスタンスを開始するには、Intent を startActivity() に渡します。Intent は開始するアクティビティを記述し、必要なデータを格納します。

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

• サービスの起動

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

  Android 5.0（API レベル 21）より前のバージョンでは、Service クラスのメソッドを使用してサービスを開始できます。Intent を startService() に渡すことで、1 回限りのオペレーション（ファイルのダウンロードなど）を実行するサービスを開始できます。Intent は、起動するサービスを記述し、必要なデータを格納します。

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

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

  ブロードキャストは、あらゆるアプリが受信できるメッセージです。システムは、システムの起動時やデバイスの充電開始時など、システム イベントに対してさまざまなブロードキャストを配信します。他のアプリにブロードキャストを配信するには、Intent を sendBroadcast() または sendOrderedBroadcast() に渡します。

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

インテントのタイプ

インテントには次の 2 種類があります。

• 明示的インテントでは、完全な ComponentName を指定することで、インテントを満たすアプリのコンポーネントを指定します。開始するアクティビティやサービスのクラス名がわかっているため、通常は明示的インテントを使用してアプリ内のコンポーネントを起動します。たとえば、ユーザーの操作に応じてアプリ内で新しいアクティビティを開始したり、バックグラウンドでファイルをダウンロードするサービスを開始したりできます。
• 暗黙的インテントは、特定のコンポーネントに名前を付けるのではなく、実行する一般的なアクションを宣言します。これにより、別のアプリのコンポーネントがそれを処理できるようになります。たとえば、地図上でユーザーに場所を表示したい場合、暗黙的インテントを使用して、別の機能を持つアプリに地図上の特定の場所を表示するようリクエストできます。

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

図 1. 暗黙的インテントがシステム経由で送られ、別のアクティビティを開始する仕組み: [1] アクティビティ A が、アクションの説明を含む Intent を作成し、startActivity() に渡します。[2] Android システムは、すべてのアプリで、インテントに一致するインテント フィルタを検索します。一致が見つかると、[3] システムは onCreate() メソッドを呼び出して Intent を渡すことで、一致するアクティビティ（アクティビティ B）を開始します。

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

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

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

インテントを作成する

Intent オブジェクトには、Android システムが開始するコンポーネントの決定に使用する情報（インテントを受け取る正確なコンポーネント名やコンポーネント カテゴリなど）と、受信コンポーネントがアクションを適切に実行するために使用する情報（実行するアクション、処理するデータなど）が格納されています。

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

コンポーネント名

起動するコンポーネントの名前。

これは省略可能ですが、インテントが「明示的」に、つまり、コンポーネント名で定義されたアプリ コンポーネントにのみインテントを配信できるようにする重要な情報です。コンポーネント名がないと、インテントは暗黙的になり、システムは他のインテント情報（後述のアクション、データ、カテゴリなど）に基づいて、インテントを受け取るコンポーネントを決定します。アプリ内の特定のコンポーネントを開始する必要がある場合は、そのコンポーネント名を指定する必要があります。

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

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

アクション

実行する一般的なアクション（view、pick など）を指定する文字列。

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

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

ACTION_VIEW

ギャラリー アプリで表示する写真やマップアプリで表示する住所など、アクティビティでユーザーに表示できる情報がある場合は、startActivity() でこのアクションを使用します。

ACTION_SEND

共有インテントとも呼ばれます。別のアプリ（メールアプリやソーシャル共有アプリなど）でユーザーが共有できるデータがある場合は、startActivity() のインテントでこれを使用する必要があります。

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

インテントのアクションは、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 システムは、これらのプロパティを読み取ることで、開始するアプリ コンポーネントを解決できます。ただし、インテントには、アプリ コンポーネントへの解決方法に影響しない追加情報を含めることができます。インテントでは次の情報も提供できます。

エクストラ

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

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

たとえば、ACTION_SEND を使用してメールを送信するインテントを作成する場合、EXTRA_EMAIL キーで to 受信者を指定し、EXTRA_SUBJECT キーで 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 アクションを持ち、「text/plain」データを運ぶインテント）を処理できるアプリを判断します。インテントを処理できるアプリが 1 つだけの場合、そのアプリはすぐに開き、インテントが提供されます。他のアプリがこれを処理できない場合、アプリは、発生した ActivityNotFoundException をキャッチできます。複数のアクティビティがインテントを受け付けている場合、図 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 違反が検出された場合は、機密に該当する可能性がある情報を保護するために、アプリの実行を停止することをおすすめします。

注: Android 12 をターゲットとするアプリが VmPolicy の定義で detectAll() メソッドを使用している場合は、detectUnsafeIntentLaunch() メソッドが自動的に呼び出されます。

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 を使用します。これにより、別のアプリが、それを含む Intent の PendingIntent をパーセル解除したときに、そのアプリの 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（scheme、host、port、path）と 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>

1 つ目のアクティビティ 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:sharedUserId を android.uid.system に設定するアプリがあります。
• ルートからのインテント。

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

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

PendingIntent オブジェクトは、Intent オブジェクトのラッパーです。PendingIntent の主な目的は、外部のアプリに、そこに含まれている Intent をあたかもアプリのプロセスから実行された場合と同様に使用する権限を付与することです。

ペンディング インテントの主なユースケースは次のとおりです。

• 通知でユーザーがアクションを実行したときに実行するインテントを宣言する（Android システムの NotificationManager が Intent を実行します）。
• ユーザーがアプリ ウィジェットでアクションを実行したときに実行するインテントを宣言する（ホーム画面アプリが Intent を実行する）。
• 指定した将来の時刻で実行するインテントを宣言する（Android システムの AlarmManager が Intent を実行します）。

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

• Activity を開始する Intent の PendingIntent.getActivity()。
• Service を開始する Intent の PendingIntent.getService()。
• BroadcastReceiver を開始する Intent の PendingIntent.getBroadcast()。

アプリが他のアプリからペンディング インテントを受け取っている場合を除き、PendingIntent を作成する上記のメソッドは、おそらく必要な PendingIntent メソッドだけです。

各メソッドは、現在のアプリの Context、ラップする Intent、インテントの使用方法（インテントが複数回使用可能かどうかなど）を指定する 1 つ以上のフラグを受け取ります。

ペンディング インテントの使用方法について詳しくは、それぞれのユースケースのドキュメントをご覧ください。たとえば、通知やアプリ ウィジェットの 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 オブジェクトのクリップデータを変更する必要があります。通常、この変更をリクエストするには、FILL_IN_CLIP_DATA をフラグとして fillIn() メソッドに渡します。
• CarAppExtender のインスタンスを使用して通知を Android Auto フレームワークに関連付ける。
• PendingIntent のインスタンスを使用して、会話をバブル内に配置する。可変の PendingIntent オブジェクトを使用すると、システムは FLAG_ACTIVITY_MULTIPLE_TASK や FLAG_ACTIVITY_NEW_DOCUMENT などの正しいフラグを適用できます。
• requestLocationUpdates() または同様の API を呼び出して、デバイスの位置情報をリクエストする。可変の PendingIntent オブジェクトを使用すると、位置情報のライフサイクル イベントを表すインテント エクストラを追加できます。これらのイベントには、ロケーションの変更やプロバイダが利用可能になることが含まれます。
• AlarmManager を使用したアラームのスケジュールの設定。可変の PendingIntent オブジェクトを使用すると、システムで EXTRA_ALARM_COUNT インテント エクストラを追加できます。このエクストラは、繰り返しアラームがトリガーされた回数を表します。このエクストラを含めると、インテントは、デバイスがスリープ状態だったときなど、繰り返しアラームが複数回トリガーされたかどうかについて、アプリに正確に通知できます。

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

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

他のアプリがアプリのペンディング インテントを使用する方法を適切に定義するには、常にペンディング インテントを明示的インテントでラップします。このベスト プラクティスに従うには、次の操作を行います。

1. ベース インテントのアクション、パッケージ、コンポーネントの各フィールドが設定されていることを確認します。

2. Android 6.0（API レベル 23）で追加された FLAG_IMMUTABLE を使用して、ペンディング インテントを作成します。このフラグは、PendingIntent を受け取ったアプリで未入力のプロパティが入力されないようにします。アプリの minSdkVersion が 22 以下の場合、次のコードを使用することで、安全性と互換性の両方を提供できます。

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

インテントの解決

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

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

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

アクションのテスト

受け入れるインテントのアクションを指定するには、次の例のように、インテント フィルタで 0 個以上の <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" のカテゴリを含める必要があります。

データテスト

受け入れるインテント データを指定するには、次の例に示すように、インテント フィルタで 0 個以上の <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 の各部分は、個別の属性（scheme、host、port、path）です。

<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 タイプの部分をパスします。URI がフィルタの URI と一致する場合、または URI が content: または file: でフィルタで URI が指定されていない場合は、テストの URI 部分が合格します。つまり、フィルタに MIME タイプのみがリストされている場合、コンポーネントは content: データと file: データをサポートすると想定されます。

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

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

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

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

もう 1 つの一般的な構成は、スキームとデータ型を持つフィルタです。たとえば、次のような <data> 要素は、コンポーネントがアクションを実行するためにネットワークから動画データを取得できることを Android に伝えます。

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

インテント マッチング

インテントをインテント フィルタと照合して、有効にするターゲット コンポーネントを検出するだけでなく、デバイス上のコンポーネントのセットに関する情報も検出します。たとえば、Google Home アプリは、ACTION_MAIN アクションと CATEGORY_LAUNCHER カテゴリを指定するインテント フィルタですべてのアクティビティを見つけることで、アプリ ランチャーにデータを入力します。IntentFilter クラスのドキュメントに記載されているように、インテントのアクションとカテゴリがフィルタと一致する場合にのみ、マッチングが成功します。

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