歩数計API概要

【APIの説明】
【パッケージ一覧/クラス一覧】
【APIの使い方】
【その他の特記事項】

【APIの説明】

歩数計APIについて

このAPIは、歩数計アプリ用の拡張IFです。歩数計APIを用いることで歩数計で測定したデータの取得や、測定データの種類のサポート有無の取得を行えます。
また、歩数計設定Activity（設定アプリ）を起動させ、その設定メニューから歩数計の起動や停止を行うことができます。
なお、全てのメソッド、定数はAPIが搭載されていない機種では利用することができません。

歩数計設定Activity

歩数計設定Activityでは、歩数計の起動/停止、ユーザー情報の設定/変更などが行えます。
Intent通知を開始するPedometer.startBroadcastIntent()は、歩数計が起動していなければエラーを返すため歩数計設定Activityから歩数計を起動しておく必要があります。

Pedometerクラス

アプリケーションから、歩数計への要求等を行うクラスです。
要求に利用するメソッドおよび、メソッドのキー値になる定数を定義しています。
API利用時にはPedometerクラスのインスタンスを生成する必要があります。

Pedometerクラスのインスタンス生成
Pedometer.createInstance(Context context)：Pedometerクラスのインスタンスを生成する

歩数計が測定しているデータを取得する方法は、以下の2種類があります。

Pedometerクラスのgetメソッドの呼び出し
getFloatParameter(String key)：Float型データを取得する
getIntParameter(String key)：Int型データを取得する
getParameters(String[] keys)：複数データを一度に取得する
Intentの受信
BroadcastReceiverを利用したIntentの受信
startBroadcastIntent()：測定データのIntent通知を開始する
stopBroadcastIntent()：測定データのIntent通知を停止する

歩数計がサポートする測定データの種類は機種によって異なるため、確認が必要な場合があります。

測定データのサポート状態取得
isSupported(String key)：測定データのサポート状態取得する

Pedometerクラスのインスタンス生成

歩数計から測定データの取得を行うために、Pedometer.createInstance()にてPedometerクラスのインスタンスを生成します。
Pedometerクラス自体は存在するが歩数計機能が非対応機種ではインスタンスは生成されず、nullが返却されることに注意してください。

Pedometerクラスのgetメソッドを用いての値の取得

○測定データの取得
Pedometerクラスには、測定データの取得インターフェースとして、単一データの取得メソッド（Int用、Float用）と、複数データの取得メソッドが用意されています。

○単一データの取得
Float用 getFloatParameter(String key)
Int用 getIntParameter(String key)

○複数データの取得
getParameters(String[] keys)

○取得方法
Pedometer.createInstance()にてインスタンスを生成し、このgetメソッドを利用します。
getメソッドは呼び出された時点の、歩数計が持っている最新の測定データを取得することができます。
歩数計が起動していない場合でも値が取得できることがあります。
これは歩数計停止直前に最後に記録された値が残っているためです。

○取得できるデータについて
取得できるデータの種類については○Pedometerクラスで取得できるデータ一覧を参照してください。

Intent通知について

歩数計APIに関連して通知されるBroadcast Intentは大きく分けて2種類あります。

歩数計起動・停止・データクリアされたこと（起動、停止はその成功/失敗）を通知するIntent
歩数計で測定したデータを通知するIntent

○歩数計起動・停止・データクリアを通知するIntent
歩数計設定Activity（設定アプリ）にて、歩数計を起動・停止・データクリアされた際に通知されるIntentです。
起動、停止の通知は、それぞれの処理結果（成功/失敗）をIntent通知で知ることができます。

No	通知の種類	定数名	備考
1	歩数計起動のIntent通知	ACTION_START	歩数計が起動されたときに歩数計起動処理結果を通知する成功：Pedometer.STATUS_OK 失敗：Pedometer.STATUS_NG
2	歩数計停止のIntent通知	ACTION_STOP	歩数計が停止されたときに歩数計停止処理結果を通知する成功：Pedometer.STATUS_OK 失敗：Pedometer.STATUS_NG
3	測定データクリアのIntent通知	ACTION_MEASURE_CLEAR	歩数計の測定データがシステム側からクリアされたときにIntent通知を行う。

歩数計の起動、停止、データクリアを行ったタイミングで処理を行いたい場合は、このIntentを受信することでタイミングを知ることができます。
Intent通知の受け取りには上記表の定数名をIntent-filterのActionに登録することが必要です。
Intent-FilterはAndroidManifestもしくは動的にBroadcastReceiverにて登録してください。

○歩数計で測定したデータを通知するIntent
歩数計の測定結果が定期的に通知されるIntentを用いて、一定間隔ごとに測定データを取得することができます。
通知されるIntentのActionは以下があり、Intent-filterへ登録することが必要です。
Intent-Filterの登録は、AndroidManifestファイルへの定義、もしくは、動的にBroadcastReceiverにて登録します。
歩数計APIを用いたアプリでは、アプリ起動時のみ値の取得が必要な場合、起動中にのみIntent通知を取得するよう、Intent-filterをAndroidManifestに定義せず、動的にBroadcastReceiverにて登録することを推奨します。

No	通知の種類	定数名	備考
1	500msecごとのIntent通知	ACTION_MEASURE	startBroadcastIntent()をコールしてから500msec毎に、測定データをIntent通知を行う。 ScreenOff時には通知されなくなる。 ※このActionを用いたIntent-filterは動的にBroadcastReceiverにて登録した場合のみ有効
2	1時間ごとのIntent通知	ACTION_MEASURE_HOURLY	歩数計が起動している場合、1時間毎(毎時00分)に測定データをIntent通知する。 ScreenOff時でも通知される。

500msecごとのIntent通知の開始および停止を行う為には、以下のメソッドの呼び出しが必要です。
Intent通知開始：Pedometer.startBroadcastIntent()
Intent通知終了：Pedometer.stopBroadcastIntent()

Intent通知の開始/終了の実装方法は、APIの使い方のIntent通知開始／終了処理を参照してください。

測定データのサポート情報確認

○歩数計でサポートしている測定データの種類の確認：isSupported(String key)
歩数計デバイスの違いにより、測定データの種類のサポート有無に違いがあります。
このisSupportedメソッドを使用することでは測定データのサポート有無を取得することができます。
測定データの種類(key)として渡す値はPedometerクラスで取得できるデータ一覧の定数名を参照してください。

○Pedometerクラスで取得できるデータ一覧
必須の項が「●」のデータは、歩数計を搭載している機種であれば必ずサポートしているデータです。

No	通知データ項目	定数名（Pedometerクラスで定義）	データ型	必須	備考
1	有酸素運動時の歩数	AEROBICS_STEPS	int
2	消費カロリー(kcal)	CALORIE	float	●
3	移動距離(km)	DISTANCE	float	●
4	エクササイズ(EX)	EXERCISE	float
5	エクササイズ歩行距離(km)	EXERCISE_DISTANCE	float
6	エクササイズ歩数	EXERCISE_STEPS	int
7	脂肪燃焼量(g)	FAT_COMBUSTION	float
8	ジョギング歩数	JOG_STEPS	int
9	ジョギング時間(分)	JOG_TIME	int
10	歩数計起動状態	MEASURE_STATUS	int	●	各値は下図参照
11	METS値	METS	float
12	エクササイズ歩行時間(分)	EXERCISE_TIME	int
13	歩数	STEPS	int	●
14	歩行時間(秒)	TIME	int
15	歩行状態	WALK_STATUS	int		0:歩数計Off 1:しばらく歩いていない 2:停止中 3:歩行中 4:しっかり歩行中
16	しっかり歩数	WALK_STEPS	int
17	しっかり歩行時間(分)	WALK_TIME	int

○歩数計起動状態

No	通知データ項目	定数名（Pedometerクラスで定義）	データ型	備考
1	起動中	DEVICE_READY	int	1
2	稼働中	DEVICE_STARTED	int	2
3	停止中	DEVICE_STOPED	int	0

このAPIを使用するには

SDKへAddOnの追加と、Manifestファイルへlibrary定義を追加する必要があります。

【パッケージ/クラス一覧】

パッケージ名	クラス名	備考
jp.co.sharp.android.hardware.Pedometer	Pedometer	歩数計APIのメインクラス
com.android.settings	jp.co.sharp.android.settings.pedometersetting.PedometerSettingActivity	歩数計設定Activity

【APIの使い方】

歩数計設定Activityの起動

歩数計設定Activityを起動するには、Intent.ACTION_MAINを使用し、Intentに以下のクラス名を指定し起動します。

パッケージ名：com.android.settings
クラス名：jp.co.sharp.android.settings.pedometersetting.PedometerSettingActivity

// 歩数計設定アプリを起動
String className = "jp.co.sharp.android.settings.pedometersetting.PedometerSettingActivity";
String packageName = "com.android.settings";
Intent i = new Intent(Intent.ACTION_MAIN);
i.setClassName(packageName, className);
startActivity(i);

Manifestファイルの記述

Manifestファイルへ、アプリケーションが参照するライブラリの参照設定を行います。
Manifestファイルの<manifest>要素の子要素に<uses-feature>と、<application>要素の子要素に<uses-library>を追加します。
<uses-library>のandroid:name属性にjp.co.sharp.android.hardwareを設定します。
<uses-feature>のandroid:name属性にjp.co.sharp.android.pedometerを設定します。
<uses-feature>のandroid:required属性にtrueを設定します。
<uses-feature>を設定することにより、弊社歩数計対応端末以外でGoogle Playにアクセスした場合に表示されないようになります。

<uses-library>宣言がなければ、歩数計を使用することができないため、注意してください。

歩数計APIの使用方法

○Pedometerクラスのインスタンス生成

import jp.co.sharp.android.hardware.Pedometer;

/* メイン */
Pedometer mPedometer = Pedometer.createInstance(context);

Pedometer.createInstance()で、Pedometerクラスのインスタンスを生成し、Pedometerのメソッドを使用します。
歩数計サービスとの接続に失敗した場合は、Pedometer.createInstance()でnullが返ってきます。

○Intent通知開始／終了処理

1)Intent通知の開始メソッドの利用

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;

//BroadcastReceiverの準備
private BroadcastReceiver mReceiver = new BroadcastReceiver(){
    @Override
    public void onReceive(Context context, Intent intent) {
         super.onReceive(context, intent);

             ～Intent受信時の処理を記述する～

     }
};

～Intent通知開始をしたい個所で～
        // マネージャーの取得
        mPedometer = Pedometer.createInstance(context);
        //サービスからのインテントを受けるように設定
        IntentFilter filter = new IntentFilter();
        filter.addAction(Pedometer.ACTION_MEASURE);
        registerReceiver(mReceiver,filter);
        //インテント通知要求
        mPedometer.startBroadcastIntent();

★使用推奨箇所
Activityの場合
Activity#onResume()内で使用すると、画面が操作可能になる際に自動でIntent通知が開始されます。
※サンプルアプリでは、任意の操作で通知を開始して頂くために、Startボタンの押下で処理を実行するよう実装しています。
1度でも開始ししていて、画面がバックグラウンドに追いやられるなどでIntent通知が停止されてしまった場合は、onResume()内でIntent通知を再開するようにしています。

AppWidgetの場合
AppWidget#onEnabled()で使用すると、AppWidgetが作成される際に自動でIntent通知を開始します。

2)Intent通知の終了メソッドの利用

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;
～Intent通知を終了させたい個所で～
        // Intent通知終了要求を行う
        mPedometer.stopBroadcastIntent();
        // Intentを受けなくする
        unregisterReceiver(mReceiver);

★使用推奨箇所
Activityの場合
Activity#onPause()メソッド内で使用すると、Intent通知を受け取っているActivityの上に別のActivityが起動されたり操作対象から外れるたびに自動でIntent通知の受け取りを終了させます。
※サンプルアプリでは、Stopボタンが押された際に、Intent通知の受け取りを終了するよう実装しています。
また、Intent通知を停止し忘れた際も、onPause()が呼ばれた時点でIntent通知が終了されていない場合はonPause()内で自動的に終了するような実装にしています。

AppWidgetの場合
AppWidget#onDisabled()メソッドで使用すると、Widgetが削除される際に自動でIntent通知の受け取りを終了します。

○Intent受信時の処理

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;

private BroadcastReceiver mReceiver = new BroadcastReceiver(){
    @Override
    public void onReceive(Context context, Intent intent) {
         super.onReceive(context, intent);
         if (intent.getAction() == Pedometer.ACTION_MEASURE) {
             // intの値をインテントからデータ取得
             int steps = intent.getIntExtra(Pedometer.STEPS, 0);
             // floatの値をインテントからデータ取得
             float calorie = intent.getFloatExtra(Pedometer.CALORIE, 0);
             float distance = intent.getFloatExtra(Pedometer.DISTANCE, 0);
             ～必要な処理を記述～
         }
     }
};

○歩数計からデータを取得
データの取得は歩数計が停止中であっても可能です。その場合、停止する直前に測定したデータが返却されます。

1)個々にデータを取得する

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;

        // 歩数のintの値を取得
        int steps = mPedometer.getIntParameter(Pedometer.STEPS);
        // カロリーと移動距離のfloatの値を取得
        float calorie = mPedometer.getFloatParameter(Pedometer.CALORIE);
        float distance = mPedometer.getFloatParameter(Pedometer.DISTANCE);

2)一度に複数のデータを取得する

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;

    //取得したいデータの識別を配列にする。
    String[] keys = {
            Pedometer.AEROBICS_STEPS, Pedometer.CALORIE,
            Pedometer.DISTANCE, Pedometer.EXERCISE,
            Pedometer.EXERCISE_DISTANCE, Pedometer.EXERCISE_STEPS,
            Pedometer.METS, Pedometer.STEPS
    };

    //指定したデータを取得
    Bundle data = mPedometer.getParameters(keys);

    // intの値を取得
    int steps = data.getInt(Pedometer.STEPS);

    // floatの値を取得
    float distance = data.getFloat(Pedometer.DISTANCE);

○サポート情報の取得

1)サポート情報を取得する

import jp.co.sharp.android.hardware.Pedometer;

private Pedometer mPedometer;

        boolean result = mPedometer.isSupported(Pedometer.CALORIE);
        if (result) {
        //サポートしている場合の処理

        ～中略～

        } else {
        //サポートしていない場合の処理

        ～中略～

        }

【その他の特記事項】

歩数計をサポートしない端末

このAPIを搭載していてもデバイスとして歩数計をサポートしていない端末では、歩数計サービスを起動しない、もしくはPedometer.createInstance()でnullが返ります。
また、歩数計設定Activityも起動することができません。

エミュレータでの歩数計処理

歩数計対応エミュレータでは、擬似的な値が取得できるのみで、実際に動作することが出来ません。
Intent通知、値の取得といった動作確認は歩数計対応の実機にて確認する必要があります。

AppWidget作成時の注意

500msecごとの通知は端末への負担が大きいため、利用には十分注意してください。
特に、AppWidgetにて500msec毎に描画を更新するような場合、RemoteViewを使用することになると思いますがコールバックの度にRemoteViewインスタンスを再利用した場合、端末の動作が重くなる可能性があります。
その場合には、RemoteViewを使用する度に、インスタンスを生成すると解決することがあります。

※ 2011年2月22日 Android2.1用のManifestファイルの記述を修正致しました。
※ 2012年4月27日歩行時間の単位を(秒)へ修正致しました。

【リファレンスへ】
　【サンプルコードへ】
　【公開API一覧へ】