PebbleKit JS

PebbleKit JS を使用すると、JavaScript コンポーネント（スマートフォンのコンパニオンアプリ内のサンドボックスで実行）を任意のウォッチアプリまたはウォッチフェイスに追加して、ウォッチ自体で実現できる範囲を超えてアプリの機能を拡張できます。

PebbleKit JS を使用するアプリで利用可能な追加機能には以下が含まれます：

localStorage による拡張ストレージへのアクセス。
XMLHttpRequest を使用したインターネットアクセス。
geolocation を使用した位置データ。
ユーザーがアプリの動作をカスタマイズできるように構成ページを表示する機能。これについては、App Configuration で詳しく説明されています。

セットアップ

PebbleKit JS は、プロジェクトの src/pkjs/ ディレクトリに index.js ファイルを作成することでセットアップできます。このファイルのコードは、関連するウォッチアプリが起動されたときに実行され、そのアプリが終了すると停止します。

PebbleKit JS の使用を開始するために必要な基本的な JS コードを以下に示します。イベントリスナーが作成され、ready イベントをリッスンします。これは、ウォッチアプリが起動され、JS 環境がメッセージを受信する準備ができたときに発火されます。このコールバックは短時間（数秒）以内に戻る必要があります。そうでない場合、タイムアウトして電話によって強制終了されます。

Pebble.addEventListener("ready", function () {
  // PebbleKit JS is ready!
  console.log("PebbleKit JS ready!");
});

重要

ウォッチアプリまたはウォッチフェイスは、接続された電話にメッセージを送信しようとする前に、ready イベントを待たなければなりません。これを行う方法については、Advanced Communication を参照してください。

キーの定義

メッセージを送受信する前に、辞書にデータ項目を保存するために使用されるキーを宣言する必要があります。ウォッチアプリ側は排他的に整数キーを使用しますが、JavaScript 側は同じ整数または package.json で宣言された名前付き文字列キーを使用できます。事前に宣言されていない文字列キーは、Pebble との間で送受信されません。

注意: この要件は PebbleKit JS のみに当てはまり、PebbleKit Android または iOS には当てはまりません。

キーは、プロジェクトの package.json ファイルの pebble オブジェクト内の messageKeys オブジェクトで宣言されます。例のキーは、Sending and Receiving Data の仮想的な天気アプリの例で使用されているものと同等として示されています。

"messageKeys": [
  "Temperature",
  "WindSpeed",
  "WindDirection",
  "RequestData",
  "LocationName"
]

ここで選択された名前は、MESSAGE_KEY_ プレフィックス付きで C コードに注入されます（例：MESSAGE_KEY_Temperature）。したがって、これらは有効な C 識別子である必要があります。

名前に複数の「キー」を付けて配列をエミュレートする場合は、角括弧内にサイズを指定して配列のサイズを指定できます。たとえば、"LapTimes[10]" は LapTimes というキーを作成し、その後に 9 つの空のキーを残します。これらは算術演算でアクセスできます（例：MESSAGE_KEY_LapTimes + 3）。

JS からのメッセージ送信

メッセージは、Pebble.sendAppMessage() を使用して C ウォッチアプリまたはウォッチフェイスに送信されます。これは、送信されるキーと値を含む標準 JavaScript オブジェクトを受け入れます。使用されるキーは、以前に宣言されたものと同一である必要があります。

以下に例を示します：

// Assemble data object
var dict = {
  Temperature: 29,
  LocationName: "London, UK",
};

// Send the object
Pebble.sendAppMessage(
  dict,
  function () {
    console.log("Message sent successfully: " + JSON.stringify(dict));
  },
  function (e) {
    console.log("Message failed: " + JSON.stringify(e));
  }
);

message_keys を require することで、キーの数値を読み取ることもできます。これは配列機能を使用するために必要です。たとえば：

// Require the keys' numeric values.
var keys = require("message_keys");

// Build a dictionary.
var dict = {};
dict[keys.LapTimes] = 42;
dict[keys.LapTimes + 1] = 51;

// Send the object
Pebble.sendAppMessage(
  dict,
  function () {
    console.log("Message sent successfully: " + JSON.stringify(dict));
  },
  function (e) {
    console.log("Message failed: " + JSON.stringify(e));
  }
);

型変換

送信されるオブジェクト内の項目のタイプに応じて、C アプリは、以下の表に従って（Tuple.value union から）値を読み取ることができます：

JS Type	Union member
String	cstring
Number	int32
Array	data
Boolean	int16

JS でのメッセージ受信

C ウォッチアプリまたはウォッチフェイスからメッセージを受信すると、PebbleKit JS アプリで appmessage イベントが発火されます。これらのメッセージを受信するには、適切なイベントリスナーを登録します：

// Get AppMessage events
Pebble.addEventListener("appmessage", function (e) {
  // Get the dictionary from the message
  var dict = e.payload;

  console.log("Got message: " + JSON.stringify(dict));
});

データは、値が存在する場合に辞書から値を読み取ることで辞書から読み取ることができます。推奨されるベストプラクティスには、if() ステートメントを使用してコールバック内の各キーの存在を最初に確認することが含まれます。

if (dict["RequestData"]) {
  // The RequestData key is present, read the value
  var value = dict["RequestData"];
}

LocalStorage の使用

Storage API を介してウォッチ自体で利用可能なストレージに加えて、アプリは、HTML 5 localStorage API の使用を通じて、接続された電話のより大きなストレージを利用できます。ここに保存されたデータはアプリの起動を超えて永続化されるため、最新のデータ、アプリの設定、その他のデータを永続化するために使用できます。

PebbleKit JS localStorage は：

アプリケーション UUID に関連付けられており、アプリ間で共有できません。
ユーザーがアプリをアンインストールしてから再インストールすると永続化されます。
ユーザーがアプリをアップグレードすると永続化されます。

値を保存するには：

var color = "#FF0066";

// Store some data
localStorage.setItem("backgroundColor", color);

データを読み戻すには：

var color = localStorage.getItem("backgroundColor");

注意: localStorage で使用されるキーは文字列である必要があります。

XMLHttpRequest の使用

PebbleKit JS 対応アプリは、標準の XMLHttpRequest オブジェクトを使用して、インターネットにアクセスし、ウェブサービスと通信したり、データをダウンロードしたりできます。

ウェブと通信するには、XMLHttpRequest オブジェクトを作成して送信し、使用する HTTP メソッドと URL、および正常に完了したときのコールバックを指定します：

var method = "GET";
var url = "http://example.com";

// Create the request
var request = new XMLHttpRequest();

// Specify the callback for when the request is completed
request.onload = function () {
  // The request was successfully completed!
  console.log("Got response: " + this.responseText);
};

// Send the request
request.open(method, url);
request.send();

レスポンスが JSON 形式であることが予想される場合、responseText が JSON オブジェクトに変換された後、データ項目を簡単に読み取ることができます：

request.onload = function () {
  try {
    // Transform in to JSON
    var json = JSON.parse(this.responseText);

    // Read data
    var temperature = json.main.temp;
  } catch (err) {
    console.log("Error parsing JSON response!");
  }
};

Geolocation の使用

PebbleKit JS は、navigator.geolocation オブジェクトを介して電話によって提供される位置サービスへのアクセスを提供します。

アプリが geolocation API を使用することを宣言するには、package.json の capabilities 配列に文字列 location を追加します：

"capabilities": [ "location" ]

以下は、getCurrentPosition() メソッドを使用して geolocation API から単一の位置値を取得する方法を示す例です：

function success(pos) {
  console.log("lat= " + pos.coords.latitude + " lon= " + pos.coords.longitude);
}

function error(err) {
  console.log("location error (" + err.code + "): " + err.message);
}

/* ... */

// Choose options about the data returned
var options = {
  enableHighAccuracy: true,
  maximumAge: 10000,
  timeout: 10000,
};

// Request current position
navigator.geolocation.getCurrentPosition(success, error, options);

位置情報の許可は、すべての Pebble アプリに対してユーザーから Pebble アプリケーションに与えられます。ユーザーが Pebble アプリへの位置情報アクセスを拒否した場合、アプリは PERMISSION DENIED エラーを適切に処理し、デフォルト値または手動設定にフォールバックする必要があります。

function error(err) {
  if (err.code == err.PERMISSION_DENIED) {
    console.log("Location access was denied by the user.");
  } else {
    console.log("location error (" + err.code + "): " + err.message);
  }
}

geolocation API は、定期的に手動でポーリングする必要を回避するために、ユーザーの位置が変化したときにコールバックを受け取るメカニズムも提供します。これは、以下の例と同様の方法で watchPosition() を使用することで実現されます：

// An ID to store to later clear the watch
var watchId;

function success(pos) {
  console.log("Location changed!");
  console.log("lat= " + pos.coords.latitude + " lon= " + pos.coords.longitude);
}

function error(err) {
  console.log("location error (" + err.code + "): " + err.message);
}

/* ... */

var options = {
  enableHighAccuracy: true,
  maximumAge: 0,
  timeout: 5000,
};

// Get location updates
watchId = navigator.geolocation.watchPosition(success, error, options);

更新コールバックをキャンセルするには、clearWatch() メソッドでウォッチが登録されたときに受信した watchId 変数を使用します：

// Clear the watch and stop receiving updates
navigator.geolocation.clearWatch(watchId);

アカウントトークン

PebbleKit JS は、Pebble.getAccountToken() を使用してアクセス可能な、現在のユーザーの Pebble アカウントに関連付けられた一意のアカウントトークンを提供します：

// Get the account token
console.log("Pebble Account Token: " + Pebble.getAccountToken());

トークンは次のプロパティを持つ文字列です：

開発者の観点から、ユーザーのアカウントトークンは、プラットフォーム間および開発者のすべてのウォッチアプリ間で同一です。
ユーザーがログインしていない場合、トークンは空の文字列（''）になります。

ウォッチトークン

PebbleKit JS は、Pebble デバイスを識別するために使用できる一意のトークンも提供します。これは Pebble.getAccountToken() と同様の方法で機能します：

// Get the watch token
console.log("Pebble Watch Token: " + Pebble.getWatchToken());

トークンは、アプリに固有の文字列であり、アプリケーション間で Pebble デバイスを追跡するために使用できません。

重要

ウォッチトークンはウォッチのシリアル番号に依存しているため、ウォッチの所有権が変更された場合に備えて、機密性の高いユーザー情報を保存するために使用すべきではありません。アプリが特定のユーザーとウォッチを追跡したい場合は、ウォッチトークンとアカウントトークンの組み合わせを使用してください。

通知の表示

PebbleKit JS アプリは、ウォッチに通知を送信できます。これは、カスタマイズ可能な title および body フィールドを持つ標準のシステム通知レイアウトを使用します：

var title = "Update Available";
var body = "Version 1.5 of this app is now available from the appstore!";

// Show the notification
Pebble.showSimpleNotificationOnPebble(title, body);

注意: PebbleKit Android/iOS アプリケーションは通知を直接呼び出すことはできず、代わりにそれぞれのプラットフォーム通知 API を活用する必要があります。これらは、ユーザーがモバイルアプリでオフにしていない限り、Pebble に渡されます。

ウォッチ情報の取得

Pebble.getActiveWatchInfo() を使用して、接続された Pebble に関するデータのオブジェクトを返します。

この API は現在、SDK 3.0 以降でのみ利用可能です。この関数が存在することを前提としないでください。以下に示すコードを使用して、使用を試みる前に利用可能かどうかをテストしてください。

var watch = Pebble.getActiveWatchInfo ? Pebble.getActiveWatchInfo() : null;

if (watch) {
  // Information is available!
} else {
  // Not available, handle gracefully
}

注意: アクティブなウォッチが利用できない場合、null が返されます。

以下の表は、返されたオブジェクトのフィールドと利用可能な情報の詳細を示しています。

Field	Type	Description	Values
`platform`	String	ハードウェアプラットフォーム名。	`aplite`, `basalt`, `chalk`.
`model`	String	色を含むウォッチモデル名。	`pebble_black`, `pebble_grey`, `pebble_white`, `pebble_red`, `pebble_orange`, `pebble_blue`, `pebble_green`, `pebble_pink`, `pebble_steel_silver`, `pebble_steel_black`, `pebble_time_red`, `pebble_time_white`, `pebble_time_black`, `pebble_time_steel_black`, `pebble_time_steel_silver`, `pebble_time_steel_gold`, `pebble_time_round_silver_14mm`, `pebble_time_round_black_14mm`, `pebble_time_round_rose_gold_14mm`, `pebble_time_round_silver_20mm`, `pebble_time_round_black_20mm`, `qemu_platform_aplite`, `qemu_platform_basalt`, `qemu_platform_chalk`.
`language`	String	ウォッチで現在選択されている言語。	例：`en_GB`。詳細については、Internationalization を参照してください。
`firmware`	Object	ウォッチで実行されているファームウェアバージョン。	サブフィールドについては以下を参照してください。
`firmware.major`	Number	メジャーファームウェアバージョン。	例：`2`
`firmware.minor`	Number	マイナーファームウェアバージョン。	例：`8`
`firmware.patch`	Number	パッチファームウェアバージョン。	例：`1`
`firmware.suffix`	String	追加のファームウェアバージョニング。	例：`beta3`

You need JavaScript enabled to read and post comments.

Guides