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

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 クラスのメソッドを使用してサービスを開始できます。IntentstartService() に渡すことで、1 回限りのオペレーション(ファイルのダウンロードなど)を実行するサービスを開始できます。Intent は、開始するサービスを記述し、必要なデータを格納します。

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

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

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

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

インテントのタイプ

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

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

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

図 1. 暗黙的インテントがシステムを通じて配信される仕組み: [1] アクティビティ AIntent を作成し、アクションの説明を 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 コンストラクタで設定できます。

アクション
実行する一般的なアクション(表示選択など)を指定する文字列。

ブロードキャスト インテントの場合、実行され、報告されるアクションです。アクションは主に、インテントの残りの部分の構造、特にデータとエクストラに含まれる情報を決定します。

アプリ内のインテントで使用する(または、他のアプリがアプリ内のコンポーネントを呼び出すために)独自のアクションを指定できますが、通常は、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 システムがインテントを受信する最適なコンポーネントを見つけることができます。ただし、MIME タイプは URI から推測できることがあります。特に、データが content: URI の場合は、この URI から推定できます。content: URI は、データがデバイスに配置され、ContentProvider によって制御されていることを示します。これにより、データの MIME タイプがシステムに表示されます。

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

注意: URI と MIME タイプの両方を設定する場合は、setData()setType()呼び出さないでください。これらはそれぞれもう一方の値を null になるためです。URI と MIME タイプの両方を設定する場合は、常に setDataAndType() を使用してください。

カテゴリ
インテントを処理するコンポーネントの種類に関する追加情報を含む文字列。1 つのインテントには任意の数のカテゴリの説明を含めることができますが、ほとんどのインテントではカテゴリは必要ありません。一般的なカテゴリは次のとおりです。
CATEGORY_BROWSABLE
ターゲット アクティビティは、ウェブブラウザで自身を起動して、画像やメール メッセージなど、リンクで参照されるデータを表示できます。
CATEGORY_LAUNCHER
アクティビティはタスクの初期アクティビティであり、システムのアプリ ランチャーにリストされます。

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

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

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

エクストラ
リクエストされたアクションの実行に必要な追加情報を伝達する Key-Value ペア。アクションによっては、特定の種類のデータ URI を使用するのと同様に、特定のエクストラを使用するものもあります。

さまざまな putExtra() メソッドでデータを追加できます。各メソッドにはキー名と値の 2 つのパラメータを指定できます。また、すべての追加データを含む Bundle オブジェクトを作成し、putExtras() を使用して BundleIntent に挿入することもできます。

たとえば、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 オブジェクト内のデータにアクセスしようとしたときに、パーセル化されたクラスまたはシリアル化されたクラスにアクセスできない場合、システムは 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 違反が検出された場合は、機密に該当する可能性がある情報を保護するために、アプリの実行を停止することをおすすめします。

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 メソッドだけです。

各メソッドは、現在のアプリの 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_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 とデータ型の両方)。
  • カテゴリ。

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

アクションのテスト

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

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

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

フィルタにアクションのリストがない場合は、一致するインテントがないため、すべてのインテントがテストに失敗します。ただし、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 の各部分は、個別の属性 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 と一致する場合、または content: URI または file: URI があり、フィルタが URI を指定していない場合、テストの 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() という同様のメソッドがあります。