このページは Cloud Translation API によって翻訳されました。

外部デバイスを操作する

Android 11 以降では、クイックアクセスデバイスコントロール機能を使用すると、デフォルトのランチャーからの 3 回の操作内で、照明、エアコン、カメラなどの外部デバイスをユーザーアフォーダンスからすばやく表示して操作できます。デバイスの OEM は、使用するランチャーを選択します。デバイスアグリゲータ（Google Home など）とサードパーティベンダーのアプリは、このスペースに表示するデバイスを指定できます。このページでは、このスペースにデバイスコントロールを表示し、コントロールアプリにリンクする方法について説明します。

図 1.Android UI のデバイスコントロールスペース

このサポートを追加するには、ControlsProviderService を作成して宣言します。事前定義されたコントロールタイプに基づいてアプリがサポートするコントロールを作成し、これらのコントロールのパブリッシャーを作成します。

ユーザーインターフェース

デバイスは、[デバイスコントロール] の下にテンプレート化されたウィジェットとして表示されます。次の図に示すように、5 つのデバイスコントロールウィジェットが使用可能です。

切り替え	スライダーで切り替え	範囲（オンとオフを切り替えることはできません）
ステートレス切り替え	温度パネル（閉じた状態）

図 2. テンプレート化されたウィジェットのコレクション。

ウィジェットを長押しするとアプリに移動し、より細かく操作できます。各ウィジェットのアイコンと色はカスタマイズできますが、最適なユーザーエクスペリエンスを実現するには、デフォルトのアイコンと色がデバイスと一致する場合は、デフォルトのアイコンと色を使用してください。

温度パネルウィジェット（開いた状態）を示す画像 — **図 3.** 温度パネルウィジェットを開きます。

サービスを作成する

このセクションでは、ControlsProviderService の作成方法について説明します。このサービスは、Android UI の [Device controls] 領域に表示する必要があるデバイスコントロールがアプリに含まれていることを Android システム UI に通知します。

ControlsProviderService API は、リアクティブストリーム GitHub プロジェクトで定義され、Java 9 フローインターフェースに実装されているリアクティブストリームに精通していることを前提としています。この API は、次のコンセプトに基づいて構築されています。

パブリッシャー: アプリがパブリッシャーです。
サブスクライバー: システム UI はサブスクライバーであり、パブリッシャーにさまざまなコントロールをリクエストできます。
サブスクリプション: ニュースメディアがシステム UI のアップデートを送信できる期間。パブリッシャーまたはサブスクライバーのいずれかが、このウィンドウを閉じることができます。

サービスを宣言する

アプリは、アプリマニフェストで MyCustomControlService などのサービスを宣言する必要があります。

サービスには ControlsProviderService のインテントフィルタが含まれている必要があります。このフィルタを使用すると、アプリがシステム UI にコントロールを提供できるようになります。

また、システム UI のコントロールに表示される label も必要です。

次の例は、サービスを宣言する方法を示しています。

<service
    android:name="MyCustomControlService"
    android:label="My Custom Controls"
    android:permission="android.permission.BIND_CONTROLS"
    android:exported="true"
    >
    <intent-filter>
      <action android:name="android.service.controls.ControlsProviderService" />
    </intent-filter>
</service>

次に、MyCustomControlService.kt という名前の新しい Kotlin ファイルを作成し、ControlsProviderService() を拡張します。

Kotlin

    class MyCustomControlService : ControlsProviderService() {
        ...
    }

Java

    public class MyCustomJavaControlService extends ControlsProviderService {
        ...
    }

正しいコントロールタイプを選択する

API には、コントロールを作成するためのビルダーメソッドが用意されています。ビルダーにデータを入力するには、制御するデバイスと、ユーザーによるデバイスの操作方法を決定します。次の手順を行います。

コントロールが表すデバイスのタイプを選択します。DeviceTypes クラスは、サポートされているすべてのデバイスを列挙したものです。タイプは、UI 内のデバイスのアイコンと色を決定するために使用されます。
コントロールに関連付けられているユーザー向けの名前、デバイスの位置（キッチンなど）などの UI テキスト要素を決定します。
ユーザーインタラクションをサポートする最適なテンプレートを選択します。コントロールには、アプリケーションから ControlTemplate が割り当てられます。このテンプレートは、コントロールの状態と使用可能な入力方法（ControlAction）をユーザーに直接表示します。次の表に、使用可能なテンプレートとサポートされるアクションの一部を示します。

テンプレート	アクション	Description
`ControlTemplate.getNoTemplateObject()`	`None`	アプリはこれを使用してコントロールに関する情報を伝えることはできますが、ユーザーがコントロールを操作することはできません。
`ToggleTemplate`	`BooleanAction`	有効状態と無効状態を切り替えられるコントロールを表します。`BooleanAction` オブジェクトには、ユーザーがコントロールをタップしたときに、リクエストされた新しい状態を表すように変化するフィールドが含まれます。
`RangeTemplate`	`FloatAction`	指定された最小値、最大値、ステップ値を持つスライダーウィジェットを表します。ユーザーがスライダーを操作したら、更新された値で新しい `FloatAction` オブジェクトをアプリケーションに返送します。
`ToggleRangeTemplate`	`BooleanAction, FloatAction`	このテンプレートは `ToggleTemplate` と `RangeTemplate` を組み合わせたものです。調光可能なライトの制御など、タッチイベントやスライダーもサポートされます。
`TemperatureControlTemplate`	`ModeAction, BooleanAction, FloatAction`	このテンプレートでは、前述のアクションをカプセル化するだけでなく、ユーザーが暖房、冷房、暖房・冷房、エコ、オフなどのモードを設定することもできます。
`StatelessTemplate`	`CommandAction`	赤外線テレビのリモコンなど、タップ機能は備えているが状態を判断できないコントロールを示すために使用されます。このテンプレートを使用して、コントロールと状態の変化を集約したルーティンやマクロを定義できます。

この情報を使用して、コントロールを作成できます。

コントロールの状態が不明な場合は Control.StatelessBuilder ビルダークラスを使用します。
コントロールの状態がわかっている場合は Control.StatefulBuilder ビルダークラスを使用します。

たとえば、スマート電球とサーモスタットを制御するには、次の定数を MyCustomControlService に追加します。

Kotlin

    private const val LIGHT_ID = 1234
    private const val LIGHT_TITLE = "My fancy light"
    private const val LIGHT_TYPE = DeviceTypes.TYPE_LIGHT
    private const val THERMOSTAT_ID = 5678
    private const val THERMOSTAT_TITLE = "My fancy thermostat"
    private const val THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT
 
    class MyCustomControlService : ControlsProviderService() {
      ...
    }

Java

    public class MyCustomJavaControlService extends ControlsProviderService {
 
    private final int LIGHT_ID = 1337;
    private final String LIGHT_TITLE = "My fancy light";
    private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT;
    private final int THERMOSTAT_ID = 1338;
    private final String THERMOSTAT_TITLE = "My fancy thermostat";
    private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT;
 
    ...
    }

コントロール用のパブリッシャーを作成する

作成したコントロールにはパブリッシャーが必要です。パブリッシャーは、システム UI にコントロールの存在を通知します。ControlsProviderService クラスには、アプリケーションコードでオーバーライドする必要がある 2 つのパブリッシャーメソッドがあります。

createPublisherForAllAvailable(): アプリで使用可能なすべてのコントロールの Publisher を作成します。Control.StatelessBuilder() を使用して、このパブリッシャーの Control オブジェクトを作成します。
createPublisherFor(): 指定されたコントロールのリストに対し、文字列識別子で識別される Publisher を作成します。これらの Control オブジェクトを作成するには、Control.StatefulBuilder を使用します。これは、パブリッシャーが各コントロールに状態を割り当てる必要があるためです。

パブリッシャーを作成する

アプリが初めてシステム UI にコントロールを公開したとき、アプリは各コントロールの状態を認識できません。状態の取得には、デバイスプロバイダのネットワーク内で多くのホップが必要となり、処理に時間がかかる可能性があります。createPublisherForAllAvailable() メソッドを使用して、使用可能なコントロールをシステムにアドバタイズします。各コントロールの状態が不明であるため、このメソッドでは Control.StatelessBuilder ビルダークラスを使用します。

Android UI にコントロールが表示されたら、ユーザーはお気に入りのコントロールを選択できます。

Kotlin コルーチンを使用して ControlsProviderService を作成するには、build.gradle に新しい依存関係を追加します。

Groovy

dependencies {
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4"
}

Kotlin

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4")
}

Gradle ファイルを同期したら、次のスニペットを Service に追加して createPublisherForAllAvailable() を実装します。

Kotlin

    class MyCustomControlService : ControlsProviderService() {
 
      override fun createPublisherForAllAvailable(): Flow.Publisher =
          flowPublish {
              send(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE))
              send(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE))
          }
 
      private fun createStatelessControl(id: Int, title: String, type: Int): Control {
          val intent = Intent(this, MainActivity::class.java)
              .putExtra(EXTRA_MESSAGE, title)
              .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
          val action = PendingIntent.getActivity(
              this,
              id,
              intent,
              PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
          )
 
          return Control.StatelessBuilder(id.toString(), action)
              .setTitle(title)
              .setDeviceType(type)
              .build()
      }
 
          override fun createPublisherFor(controlIds: List): Flow.Publisher {
           TODO()
        }
 
        override fun performControlAction(
            controlId: String,
            action: ControlAction,
            consumer: Consumer
        ) {
            TODO()
        }
    }

Java

    public class MyCustomJavaControlService extends ControlsProviderService {
 
        private final int LIGHT_ID = 1337;
        private final String LIGHT_TITLE = "My fancy light";
        private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT;
        private final int THERMOSTAT_ID = 1338;
        private final String THERMOSTAT_TITLE = "My fancy thermostat";
        private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT;
 
        private boolean toggleState = false;
        private float rangeState = 18f;
        private final Map> controlFlows = new HashMap<>();
 
        @NonNull
        @Override
        public Flow.Publisher createPublisherForAllAvailable() {
            List controls = new ArrayList<>();
            controls.add(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE));
            controls.add(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE));
            return FlowAdapters.toFlowPublisher(Flowable.fromIterable(controls));
        }
 
        @NonNull
        @Override
        public Flow.Publisher createPublisherFor(@NonNull List controlIds) {
            ReplayProcessor updatePublisher = ReplayProcessor.create();
 
            controlIds.forEach(control -> {
                controlFlows.put(control, updatePublisher);
                updatePublisher.onNext(createLight());
                updatePublisher.onNext(createThermostat());
            });
 
            return FlowAdapters.toFlowPublisher(updatePublisher);
        }
    }

システムメニューを下にスワイプして、[デバイスコントロール] ボタン（図 4 を参照）を見つけます。

デバイスコントロールのシステム UI を示す画像 — **図 4.** システムメニューのデバイスコントロール

[デバイスコントロール] をタップすると、アプリを選択できる 2 つ目の画面に移動します。アプリを選択すると、図 5 に示すように、前のスニペットによって、新しいコントロールを表示するカスタムシステムメニューが作成されます。

ライトとサーモスタットのコントロールを含むシステムメニューを示す画像 — **図 5.**追加する照明とエアコンのコントロール。

次に、createPublisherFor() メソッドを実装して、次のコードを Service に追加します。

Kotlin

    private val job = SupervisorJob()
    private val scope = CoroutineScope(Dispatchers.IO + job)
    private val controlFlows = mutableMapOf>()
 
    private var toggleState = false
    private var rangeState = 18f
 
    override fun createPublisherFor(controlIds: List): Flow.Publisher {
        val flow = MutableSharedFlow(replay = 2, extraBufferCapacity = 2)
 
        controlIds.forEach { controlFlows[it] = flow }
 
        scope.launch {
            delay(1000) // Retrieving the toggle state.
            flow.tryEmit(createLight())
 
            delay(1000) // Retrieving the range state.
            flow.tryEmit(createThermostat())
 
        }
        return flow.asPublisher()
    }
 
    private fun createLight() = createStatefulControl(
        LIGHT_ID,
        LIGHT_TITLE,
        LIGHT_TYPE,
        toggleState,
        ToggleTemplate(
            LIGHT_ID.toString(),
            ControlButton(
                toggleState,
                toggleState.toString().uppercase(Locale.getDefault())
            )
        )
    )
 
    private fun createThermostat() = createStatefulControl(
        THERMOSTAT_ID,
        THERMOSTAT_TITLE,
        THERMOSTAT_TYPE,
        rangeState,
        RangeTemplate(
            THERMOSTAT_ID.toString(),
            15f,
            25f,
            rangeState,
            0.1f,
            "%1.1f"
        )
    )
 
    private fun  createStatefulControl(id: Int, title: String, type: Int, state: T, template: ControlTemplate): Control {
        val intent = Intent(this, MainActivity::class.java)
            .putExtra(EXTRA_MESSAGE, "$title $state")
            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        val action = PendingIntent.getActivity(
            this,
            id,
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )
 
        return Control.StatefulBuilder(id.toString(), action)
            .setTitle(title)
            .setDeviceType(type)
            .setStatus(Control.STATUS_OK)
            .setControlTemplate(template)
            .build()
    }
 
    override fun onDestroy() {
        super.onDestroy()
        job.cancel()
    }

Java

    @NonNull
    @Override
    public Flow.Publisher createPublisherFor(@NonNull List controlIds) {
        ReplayProcessor updatePublisher = ReplayProcessor.create();
 
        controlIds.forEach(control -> {
            controlFlows.put(control, updatePublisher);
            updatePublisher.onNext(createLight());
            updatePublisher.onNext(createThermostat());
        });
 
        return FlowAdapters.toFlowPublisher(updatePublisher);
    }
 
    private Control createStatelessControl(int id, String title, int type) {
        Intent intent = new Intent(this, MainActivity.class)
                .putExtra(EXTRA_MESSAGE, title)
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        PendingIntent action = PendingIntent.getActivity(
                this,
                id,
                intent,
                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
        );
 
        return new Control.StatelessBuilder(id + "", action)
                .setTitle(title)
                .setDeviceType(type)
                .build();
    }
 
    private Control createLight() {
        return createStatefulControl(
                LIGHT_ID,
                LIGHT_TITLE,
                LIGHT_TYPE,
                toggleState,
                new ToggleTemplate(
                        LIGHT_ID + "",
                        new ControlButton(
                                toggleState,
                                String.valueOf(toggleState).toUpperCase(Locale.getDefault())
                        )
                )
        );
    }
 
    private Control createThermostat() {
        return createStatefulControl(
                THERMOSTAT_ID,
                THERMOSTAT_TITLE,
                THERMOSTAT_TYPE,
                rangeState,
                new RangeTemplate(
                        THERMOSTAT_ID + "",
                        15f,
                        25f,
                        rangeState,
                        0.1f,
                        "%1.1f"
                )
        );
    }
 
    private  Control createStatefulControl(int id, String title, int type, T state, ControlTemplate template) {
        Intent intent = new Intent(this, MainActivity.class)
                .putExtra(EXTRA_MESSAGE, "$title $state")
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        PendingIntent action = PendingIntent.getActivity(
                this,
                id,
                intent,
                PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
        );
 
        return new Control.StatefulBuilder(id + "", action)
                .setTitle(title)
                .setDeviceType(type)
                .setStatus(Control.STATUS_OK)
                .setControlTemplate(template)
                .build();
    }

この例では、createPublisherFor() メソッドに、アプリが行う必要のある偽の実装が含まれています。具体的には、デバイスと通信してステータスを取得し、そのステータスをシステムに出力します。

createPublisherFor() メソッドは、Kotlin のコルーチンとフローを使用して、以下の処理を行い、必要な Reactive Streams API を満たします。

Flow を作成します。
1 秒待ちます。
スマートライトの状態を作成して出力します。
さらに 1 秒待ちます。
サーモスタットの状態を作成して出力します。

アクションを処理する

performControlAction() メソッドは、ユーザーが公開されているコントロールを操作したときにシグナル状態になります。送信される ControlAction のタイプによってアクションが決まります。指定されたコントロールに対して適切なアクションを実行し、Android UI でデバイスの状態を更新します。

サンプルを完了するには、Service に次の行を追加します。

Kotlin

    override fun performControlAction(
        controlId: String,
        action: ControlAction,
        consumer: Consumer
    ) {
        controlFlows[controlId]?.let { flow ->
            when (controlId) {
                LIGHT_ID.toString() -> {
                    consumer.accept(ControlAction.RESPONSE_OK)
                    if (action is BooleanAction) toggleState = action.newState
                    flow.tryEmit(createLight())
                }
                THERMOSTAT_ID.toString() -> {
                    consumer.accept(ControlAction.RESPONSE_OK)
                    if (action is FloatAction) rangeState = action.newValue
                    flow.tryEmit(createThermostat())
                }
                else -> consumer.accept(ControlAction.RESPONSE_FAIL)
            }
        } ?: consumer.accept(ControlAction.RESPONSE_FAIL)
    }

Java

    @Override
    public void performControlAction(@NonNull String controlId, @NonNull ControlAction action, @NonNull Consumer consumer) {
        ReplayProcessor processor = controlFlows.get(controlId);
        if (processor == null) return;
 
        if (controlId.equals(LIGHT_ID + "")) {
            consumer.accept(ControlAction.RESPONSE_OK);
            if (action instanceof BooleanAction) toggleState = ((BooleanAction) action).getNewState();
            processor.onNext(createLight());
        }
        if (controlId.equals(THERMOSTAT_ID + "")) {
            consumer.accept(ControlAction.RESPONSE_OK);
            if (action instanceof FloatAction) rangeState = ((FloatAction) action).getNewValue()
            processor.onNext(createThermostat());
        }
    }

アプリを実行し、[Device controls] メニューにアクセスして、ライトとサーモスタットのコントロールを確認します。

照明とエアコンのコントロールを示す画像 — **図 6.**照明とサーモスタットの操作

外部デバイスを操作する

ユーザー インターフェース

サービスを作成する

サービスを宣言する

Kotlin

Java

正しいコントロール タイプを選択する

Kotlin

Java

コントロール用のパブリッシャーを作成する

パブリッシャーを作成する

Groovy

Kotlin

Kotlin

Java

Kotlin

Java

アクションを処理する

Kotlin

Java

ユーザーインターフェース

正しいコントロールタイプを選択する