追加機能をウォッチフェイスに追加する

ウォッチフェイスの追加機能（以下、「追加機能」と表記）は、データ プロバイダからのデータを表示します。 ウォッチフェイスは、Complications API を介して、使いたいデータ プロバイダを選び、基となるデータを取得することができます。これにより、データを取得するコードを作成せずに、日付や時刻にとどまらない多くの情報をウォッチフェイスに表示できます。

Complications API により、ユーザーがデータ プロバイダを選べるようにすることもできます。 また、Wear OS by Google では、データソースを選択するユーザー インターフェースも提供されています。

ウォッチフェイスに追加機能を追加するには、以下の手順に従います。

• 設定する追加機能スロットの数と、各スロットでサポートする追加機能タイプを決定します。
• スロットごとにデフォルトのデータ プロバイダを設定します。
• ユーザーがデータ プロバイダを選択できるようにします。
• 追加機能データの受信権限を設定します。
• データ受信を開始するために、追加機能を有効にします。
• ウォッチフェイスを描画する際に、追加機能をレンダリングします。
• 追加機能データが正しくレンダリングされているかをテストします。

ウォッチフェイスのデフォルト プロバイダを設定する

ウォッチフェイスでは、デフォルト プロバイダを指定できます。ユーザーがプロバイダを選択するまでは、デフォルト プロバイダが使用されます。デフォルト プロバイダを設定するには、WatchFaceService.Engine の setDefaultComplicationProvider() メソッドを使用します。このメソッドはいつでも呼び出すことができますが、指定された追加機能に対してユーザーがすでにプロバイダを選択している場合は、このメソッドを呼び出しても何も起こりません。

ほとんどのプロバイダについては、ウォッチフェイスにデータが届くようにするため、ウォッチフェイスに RECEIVE_COMPLICATION_DATA 権限を付与する必要があります。ただし、一部のシステム プロバイダは、ウォッチフェイスが自力で得ることができる情報のみを提供するため、安全だと見なされています。安全なプロバイダは、権限が付与されていないウォッチフェイスにデータを送信できます（システム プロバイダをご覧ください）。このようなプロバイダは、すぐにデータを提供できるので、デフォルト プロバイダとして使用するのに適しています。

また、あるプロバイダにウォッチフェイスが関連付けられていて、そのプロバイダをデフォルトとして使用したいときは、関連付けられているウォッチフェイスを安全なウォッチフェイスとして登録するようプロバイダにリクエストできます。

システム プロバイダ

システムには、デフォルトとして使用できるプロバイダが含まれています。 WatchFaceService.Engine クラスの setDefaultSystemComplicationProvider() メソッドは、追加機能のデフォルト システム プロバイダを設定します。このメソッドは、システム プロバイダを表す ID（整数値）を受け取ります。利用できる ID の一覧は、SystemProviders クラスから取得できます。

サポートされているシステム プロバイダの一部について、次の表に詳細を示します。

ユーザーがデータ プロバイダを選択できるようにする

Wear OS は、ユーザーが特定の追加機能のプロバイダを選択するためのユーザー インターフェースを（アクティビティを通じて）提供します。ウォッチフェイスは、createProviderChooserHelperIntent メソッドを呼び出して、選択用のインターフェースを表示するインテントを取得できます。

ウォッチフェイスは、createProviderChooserHelperIntent を呼び出したときに、ウォッチフェイス追加機能 ID と、サポートされているタイプの一覧を提供します。タイプは、希望する順番に並べる必要があります。通常は、範囲値などの多くの情報を提供できるタイプを上位にします。

ユーザーがデータ プロバイダを選択すると、その設定は自動的に保存されます。ウォッチフェイスからそれ以上の操作を求められることはありません。

設定ユーザー インターフェース用の完全な機能を含む推奨コードについては、ウォッチフェイス サンプルアプリをご覧ください。

このコードは以下の機能を備えています。

• 追加機能を設定する標準インターフェース
• 他の設定への簡単なアクセス

コードを確認する場合は、AnalogComplicationConfigActivity クラスから始めてください。このクラスには、UI で使用できる設定エントリのリストを返す getDataToPopulateAdapter() メソッドが含まれています。

プロバイダ選択画面を開く

追加機能データを受信してプロバイダ選択画面を開くには、ウォッチフェイスに次の権限が必要です。

    com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
    

この権限が付与されていないウォッチフェイスでは、プロバイダ選択画面を開くことができません。

簡単に権限をリクエストして選択画面を開くことができるように、ウェアラブル サポート ライブラリには ComplicationHelperActivity クラスが用意されています。このクラスを ProviderChooserIntent クラスの代わりに使用すると、ほぼすべてのケースで選択画面を起動できます。

必要な権限をリクエストする

ComplicationHelperActivity を使用するには、マニフェスト ファイルでこのアクティビティをウォッチフェイスに追加します。

    <activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>
    

プロバイダ選択画面を起動するには、インテントを取得する ComplicationHelperActivity.createProviderChooserHelperIntent メソッドを呼び出します。

startActivity または startActivityForResult に新しいインテントを指定すると、選択画面を起動できます。

startActivityForResult に新しいインテントを指定する例を次に示します。

    startActivityForResult(
            ComplicationHelperActivity.createProviderChooserHelperIntent(
                    activity,
                    watchFace,
                    complicationId,
                    ComplicationData.TYPE_LARGE_IMAGE
            ),
            PROVIDER_CHOOSER_REQUEST_CODE
    )
    

    startActivityForResult(
      ComplicationHelperActivity.createProviderChooserHelperIntent(
         getActivity(),
         watchFace,
         complicationId,
         ComplicationData.TYPE_LARGE_IMAGE),
      PROVIDER_CHOOSER_REQUEST_CODE);
    

ヘルパー アクティビティが開始されると、このアクティビティは権限が付与されているかどうかをチェックします。権限が付与されていない場合、ヘルパー アクティビティはランタイム権限リクエストを送信します。権限リクエストが承認された場合（または権限が不要な場合）、プロバイダ選択画面が表示されます。

startActivityForResult にインテントを指定した場合、プロバイダが正常に設定されたときは結果コード RESULT_OK が呼び出し元のアクティビティに返され、プロバイダが設定されなかったときは結果コード RESULT_CANCELLED が返されます。

プロバイダが設定された場合、選択されたプロバイダの ComplicationProviderInfo クラスは、キー ProviderChooserIntent#EXTRA_PROVIDER_INFO を持つエクストラとして結果のデータ インテントに挿入されます。

追加機能データを受信する

追加機能データの受信を開始する際、ウォッチフェイスは追加機能 ID のリストを指定して、WatchFaceService.Engine クラスの setActiveComplications() を呼び出します。ウォッチフェイスは、追加機能を表示するスロットを一意に識別するためにこれらの ID を作成し、createProviderChooserIntent() メソッドに渡して、どの追加機能をどのスロットに割り当てるかをユーザーが決められるようにします。追加機能データは onComplicationDataUpdate() コールバックを通じて送信されます。

一般的に、ウォッチフェイスが追加機能データを受信するには上記の権限が必要ですが、例外もいくつかあります。厳密には、ウォッチフェイスは以下の条件のいずれかが成立する場合にのみ、プロバイダからデータを受信できます。

• プロバイダが「安全」なシステム プロバイダである
• プロバイダとウォッチフェイスのアプリが同じである
• ウォッチフェイスがプロバイダのホワイトリストに「安全」なウォッチフェイスとして登録されている
• ウォッチフェイスに権限が付与されている

上記のいずれの条件も成立しない場合、通常であればプロバイダからウォッチフェイスに ComplicationData が送信されるタイミングで、代わりに TYPE_NO_PERMISSION タイプのデータが送信されます。このタイプには、アイコン（感嘆符）と短いテキスト（「--」）が含まれています。これは、便宜上、短いテキストタイプまたはアイコンタイプと同様にレンダリングできるようにするためです。

ウォッチフェイスは TYPE_NO_PERMISSION のデータを受信した場合、追加機能を動作させるために操作が必要であることがユーザーに伝わるように、このデータを適切にレンダリングする必要があります。可能であれば、この状態の追加機能をタップすることにより権限リクエストが起動されるようにします。ウォッチフェイス アプリにヘルパー アクティビティが追加されていれば、ComplicationHelperActivity.createPermissionRequestHelperIntent() を使用してこの動作を実現できます。

ヘルパー アクティビティによる権限リクエストをユーザーが承認すると、ウォッチフェイス上のすべてのアクティブな追加機能に対して自動的に更新がリクエストされます。これにより、TYPE_NO_PERMISSION データが実際のデータに置き換えられます。

追加機能をレンダリングする

ウォッチフェイスは、想定される項目が含まれていさえすれば、自由にデータをレンダリングできます。必須項目は必ず含める必要があります。 タイプによっては、一部の省略可能項目を含めなければならない場合もあります（下の表の「注記」列をご覧ください）。

標準の追加機能用のおすすめとして Google スタイルのデザイン ガイドラインが用意されていますが、デベロッパーは独自のスタイルを使用することも、別の方法でデータをウォッチフェイスに提供することもできます。

追加機能を描画する

ComplicationDrawable クラスを使用して、キャンバスに追加機能全体をレンダリングできます。

このクラスは、6 つある主要な追加機能タイプをすべてサポートしており、以下を行います。

• 追加機能のレイアウトとスタイル設定をすべて処理する。
• 境界内の背景、アイコン、テキストなどを描画する。
• さまざまなオプションを設定できるようにする。オプションには、背景色、角の形と角丸の半径、境界線（有無を含む）、テキストの色、書体などが含まれます。
• 画像のデコードとキャッシュ保存を行う。

ターゲット API レベル 24 では、リソースとして XML 形式の ComplicationDrawable オブジェクトを定義できます。または、プログラムで ComplicationDrawable オブジェクトを作成することもできます。draw() メソッドを使用すると、追加機能の描画と、インタラクティブ モードおよび常に画面表示モードでのスタイル オプションの設定を行えます。

焼き付き防止アイコンと画像が提供されていて、それらがデバイスで必要とされる場合、ComplicationDrawable はそれらを使用できます。これを実現するには、デバイス プロパティを受信したときに、ComplicationDrawable.setBurnInProtection() メソッドを呼び出します。

追加機能の描画に関する詳細な手順と例については、 ComplicationDrawable をご覧ください。これにはサンプル XML も含まれています。このクラスを利用するウォッチフェイス（サンプル XML を含む）の例については、ウォッチフェイス サンプルアプリの AnalogComplicationWatchFaceService サンプルをご覧ください。

ComplicationDrawable オブジェクトを使用しない場合は、追加機能のテキストに TextRenderer を使用します。

テキストをレンダリングする

TextRenderer は、追加機能での使用を目的とするクラスで、使用するとキャンバスへのテキスト描画が簡単になります。このクラスには、以下の機能が含まれています。

• 7 文字（短いテキスト項目の最大長）がリクエストされたテキストのサイズの境界内に収まらない場合、収まるまでテキストを短縮します。
• 指定された行数のテキストを流し込むことができます。
• 境界内に収まらない場合、テキストは省略されます。
• レンダリングは、常時オン画面（常に画面表示モード）用に調整されます。

ウォッチフェイス エンジンを初期化する際に、TextRenderer オブジェクトを作成して、TextRenderer オブジェクトが使用する必要がある TextPaint オブジェクトを渡すことができます。 TextPaint オブジェクトは、フォント、テキストサイズ、色などを定義します。TextRenderer オブジェクトは項目ごとに作成する必要があります。たとえば、テキスト項目用に 1 つ、タイトル項目用に 1 つ作成します。

レンダリングするテキストの境界を指定するコードなどのサンプルについては、 TextRenderer をご覧ください。

追加機能のタップ

ComplicationDrawable.onTap() メソッドを使用すると、ウォッチフェイスから追加機能にタップイベントを渡すことができます。このメソッドは、ウォッチフェイスのタップにより WatchFaceService.Engine.onTapCommand() メソッドをトリガーする機能がベースになっています。

onTap の呼び出しを使用して、座標を ComplicationDrawable に渡すことができます。これにより、タップ座標を含む ComplicationDrawable に関連付けられたアクションが起動されます。メソッドが呼び出されたとき、関連付けられたアクションが ComplicationDrawable によって起動されると、戻り値 true が返されます。

onTap メソッドが呼び出された後、setHighlightDuration() メソッドを使用して、追加機能のハイライト表示が継続する時間を設定できます。

追加機能に対して ComplicationDrawable を使用していない場合は、独自にタップを検出してタップ アクション PendingIntent を起動する必要があります。ユーザーのタップに応答するウォッチフェイスの作成方法については、インタラクティブなウォッチフェイスを作成するをご覧ください。

追加機能タイプ

追加機能に表示されるデータの種類は、追加機能タイプによって決まります。たとえば、主要なデータが短い文字列である場合は、SHORT_TEXT タイプを利用できます。SHORT_TEXT タイプの場合、省略可能なデータはアイコンと短いタイトルです。

データ プロバイダは、ウォッチフェイス プロバイダとは異なる方法で追加機能タイプを使用します。

• データ プロバイダは、提供する追加機能データの種類を選択します。たとえば、歩数プロバイダは RANGED_VALUE タイプと SHORT_TEXT タイプをサポートし、「次の打ち合わせ」プロバイダは SHORT_TEXT タイプと LONG_TEXT タイプをサポートします。データ プロバイダは、これらのタイプのどの省略可能項目を含めるかも選択します。
• ウォッチフェイス プロバイダは、サポートする追加機能タイプの数を選択します。 たとえば、ウォッチフェイス上にある円形の追加機能は SHORT_TEXT、ICON、RANGED_VALUE タイプをサポートし、ウォッチフェイス上のゲージは RANGED_VALUE タイプのみをサポートします。

ComplicationData オブジェクトは、常に 1 つの追加機能タイプを持ちます。追加機能タイプには、それぞれ必須項目と省略可能項目があります。一般的に、必須項目はデータの主な部分を表します。ほとんどのタイプは、必須項目から名前が付けられています。

1 つのタイプに複数の項目が含まれる場合があります。たとえば、SHORT_TEXT は、テキストのみ、タイトルとテキスト、アイコンとテキストのいずれかです。あるタイプをサポートする追加機能は、想定されるすべての項目の組み合わせを表示できる必要があります。ただし、一部の省略可能項目は、表示しなくてもよい場合があります（下の表の「注記」列をご覧ください）。たとえば、RANGED_VALUE タイプの短いタイトル項目は必須ではないので、ゲージなどはテキストなしで表示することもできます。

追加機能タイプの例

追加機能タイプの例を次に示します。

タイプと項目

次の表は、ComplicationData オブジェクトのタイプと項目についての説明を示しています。 ウォッチフェイスが特定の追加機能タイプに対して無効な項目をリクエストすると、その項目のデフォルト値が返されます。 たとえば、ウォッチフェイスが SHORT_TEXT タイプの Long text 項目にアクセスしようとした場合は、Long text 項目のデフォルト値（null）が返されます。

下記の表のタイプは空データ用であり、任意の追加機能スロットに送信される可能性があります。これらのタイプには項目がないため、サポートされるタイプのリストに含める必要はありません。ウォッチフェイスは、これらのタイプから、次の 3 つのケースを判別することができます。

• プロバイダが選択されていない場合
• ユーザーがスロットに「空」を選択している場合
• プロバイダに送信するデータがない場合

プロバイダは、更新リクエストに対して TYPE_EMPTY を送信してはなりません。代わりに TYPE_NO_DATA を送信する必要があります。

「空」のデータに対する追加機能タイプの詳細を次の表に示します。

追加機能データの項目を使用する

ComplicationData オブジェクトの項目には、さまざまな機能があります。たとえば、テキスト項目には主要データが含まれ、タイトル項目には説明データが含まれます。歩数計の追加機能では、「2,543」という値を持つテキスト項目と、「歩数」という値を持つタイトル項目があるかもしれません。

次の表は、ComplicationData オブジェクトの項目に関する説明を示しています。追加機能タイプによって、項目に値が設定されている場合と設定されていない場合があります。

追加機能タイプをテストする

追加機能タイプには、それぞれテキストやアイコンなどの項目があります。ウォッチフェイスが特定の追加機能タイプをサポートする場合、すべての有効な項目の組み合わせをサポートする必要があります。

ウォッチフェイスに追加機能データがどのように表示されるかをテストできます。 具体的には、テストスイートを使用して追加機能タイプの表示をテストします。 この方法では、ComplicationData オブジェクトの有効な項目の組み合わせをテストするためのコードの記述は不要です。

テストスイートは、サンプルとして利用できるデータ プロバイダです。特定の追加機能タイプについて有効な項目の組み合わせを 1 つずつ順番にテストできます。

テストスイートを利用するには:

1. デバイスまたはエミュレータに、テストスイート APK をインストールします。
2. ウォッチフェイスにアクセスし、メイン設定アイコンをタップします。
3. 設定 UI を使用して、テストスイート WearComplication-ProviderTestSuite を選択します。
4. テストする追加機能のデータタイプを選択します。
5. 追加機能をタップして、データタイプの組み合わせを表示します。
6. 追加機能を繰り返しタップして、テスト対象のすべての項目の組み合わせが正しく表示されることを確認します。

たとえば、追加機能が短いテキストをサポートしている場合は、追加機能をタップして、短いテキストの項目のすべての主要な組み合わせを確認します。