スマートフォンには、「向き」を調べるためのセンサーが組み込まれています。いわゆる「コンパス」に相当するものです。これをPhoneGapから利用するには、「Compass」というオブジェクトを利用します。これは、navigator.compassという名前で用意されています。

このnavigator.compassには、コンパスの値を取得するためのメソッドが用意されています。「getCurrentHeading」というもので、以下のように呼び出します。

navigator.compass.getCurrentHeading( 成功時の処理 , 例外時の処理 );

引数には、コンパスの値の取得に成功した場合と失敗した場合に呼び出されるコールバック関数をそれぞれ用意します。コールバック関数を使うということからもわかるように、この処理は非同期で実行されます。呼び出してすぐにぱっと値が偉えるわけではありません。

成功した際に呼び出されるコールバック関数では、引数を１つだけ用意します。この引数には、CompassHeadingオブジェクトというものが用意され、そこからコンパスの情報が取得できます。オブジェクトに用意されている主なプロパティを整理すると以下のようになります。

trueHeading――これが、どっちを向いているかという「向き（角度）」の値です。０～359.99の間の実数（北極点がゼロになる）で設定されます。
magneticHeading――これは磁極からの向きを示す値です。地球は、磁極と北極点は必ずしも同じではありませんので、こちらで磁極からの向き（角度）を取得します。０～359.99の間の実数です。
headingAccuracy――北極点と磁極間の精度を返します。
timestamp――値が取得できた時刻のタイムスタンプです。

これらのプロパティの値を取得し、どちらを向いているか調べれば、コンパス利用のプログラムが簡単に作れる、というわけです。