アダプティブ カード拡張機能の位置情報機能

位置情報に関する新しいアクションの種類

次の 2 つの場所アクションがあります。

1. 場所を取得する
2. 場所を表示する

場所を取得する:

ユーザーのデバイスの現在位置を示すか、場所選択ウィンドウを開いてユーザーによって選択された場所の位置を返します。 ブラウザーでは、マッピング インターフェイスとして Bing Maps が使用されます。

[場所を取得する] の ACE アクションは、VivaAction.GetLocation です。

これは、ブール型のパラメーター ChooseLocationOnMap (省略可能) を取ります。

プロパティ ChooseLocationOnMap が true に設定されている場合は、このアクションによってマップが開き、ユーザーがマップ上の場所を選択できるようになります。それ以外の場合は、ユーザーのデバイスの現在位置が取得されます。

場所を表示する:

このアクションでは、画面にマップが表示され、ユーザーの現在位置をマップに表示するか、指定した座標をマップに表示することができます。

[場所を表示する] の ACE アクションは、VivaAction.ShowLocation です。

これは、位置パラメーター locationCoordinates (省略可能) を取ります。

特定の場所を示すには、locationCoordinates パラメーターを使用して位置座標 (緯度と経度) を渡す必要があります。

locationCoordinates オブジェクトは、次のプロパティで構成されています。

{
  /**
   * Latitude of the location.
   */
  latitude: number;

  /**
   * Longitude of the location.
   */
  longitude: number;

  /**
   * Timestamp (optional).
   */
  timestamp?: number;

  /**
   * Accuracy of the location (optional).
   */
  accuracy?: number;
}

チュートリアルと例

このチュートリアル では、位置情報アクションを含むカードの作成方法について、手順を詳しく説明します。

次の例では、位置情報アクションとその目的について説明します。

1. ユーザーの現在の場所を取得する

   テンプレート JSON に、次のアクションを含めます。

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location'
   }]
   

   このアクションが呼び出されると、ユーザーの現在の位置情報が取得され、onAction コールバックを介してサード パーティの開発者に渡されます。

   注:

   この場合、マップは表示されません。

2. マップから場所を選択する

   テンプレート JSON に、次のアクションを含めます。

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location',
     parameters: {chooseLocationOnMap: true}
   }]
   

   このアクションが呼び出されると、ユーザーの現在位置を示すマップが開き、ユーザーが任意の場所を選択して共有できるようになります。 選択した場所の座標は、onAction コールバックを介してサード パーティの開発者に渡されます。

3. ユーザーの現在位置を表示する

   テンプレート JSON に、次のアクションを含めます。

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location'
   }]
   

   このアクションが呼び出されると、マップが開き、ユーザーの現在の位置座標が表示されます。

4. 指定した場所を表示する

   テンプレート JSON に、次のアクションを含めます。

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location',
     parameters: {
       locationCoordinates: {
         latitude: 28.6132039578389,
         longitude: 77.229488240066
       }
     }
   }]
   

   このアクションが呼び出されると、マップが開き、アクションで指定された位置座標が表示されます。

カード デザイナーのカードのプロパティ ウィンドウを使用して位置情報アクションにアクセスする

コードを記述したくないが、位置情報アクションのしくみを確認したい場合は、このチュートリアルを参照してください。このチュートリアルでは、プロパティ ウィンドウを使用して位置情報アクションを含むカードを作成できます。

アクセス許可とエラー コード

位置 API を機能させるには、ユーザーが、デバイスの位置にアクセスするためのアクセス許可を付与する必要があります。

カード開発者向けのコールバック

アクション VivaAction.GetLocation が呼び出されると、onAction コールバックを介して、取得した位置座標が渡されます。

アクション VivaAction.GetLocation と VivaAction.ShowLocation では、ユーザーがエラー状態になると、onError コールバックが呼び出され、それにアクション名とエラー コードが渡されます。

位置情報アクションの可用性