APL 1.4の新機能



APL 1.4の新機能

Alexa Presentation Language 1.4では、APLに新機能が追加されました。

APL for Audio（ベータ）

APL for Audioでは、オーディオクリップを作成するための新しいAPLドキュメント形式が導入されました。これにより、音声と効果音をミックスするAPLドキュメントを定義できます。APL for Audioは、APLと同じフレームワークを使用して、データソース、データバインディング、コンポーネントのセットを使ったオーディオの作成をサポートします。

APL for Audioは、画面のないデバイスを含む、すべてのAlexaデバイスで使用できます。スキルの応答でオーディオを使用するには、RenderDocumentでAPLA for Audioドキュメントを返してオーディオを再生します。

APL for Audioドキュメント形式のリファレンスについては、APL for Audioリファレンスを参照してください。

また、APL for AudioをビジュアルのAPLドキュメントと統合することもできます。APL for Audioを使うと、SpeakItemまたはSpeakList APLコマンドでオーディオを再生できます。たとえば、ユーザーが画面上のボタンをタップしたときに、天気予報を読み上げます。

APL for AudioドキュメントをビジュアルのAPLドキュメントと統合するには、新しいaplaAudioToSpeechトランスフォーマーを使用します。オーサリングツールのプレビューモードで、この統合をプレビューできます。詳細については、APL for Audioトランスフォーマーをテストするを参照してください。

APLレスポンシブ対応コンポーネントとテンプレート

新たなレスポンシブ対応コンポーネントとテンプレートを使用して、APLレスポンシブ対応ドキュメントを作成します。この新しいコンポーネントとテンプレートを使用するには、alexa-layoutsパッケージをドキュメントに読み込みます。versionには、必ず1.2.0を指定してください。

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ]
}

コンポーネントとテンプレートの概要については、レスポンシブ対応コンポーネントとテンプレートを参照してください。

新しいレスポンシブ対応コンポーネントとテンプレート

新しいレスポンシブ対応コンポーネントについて詳しくは、以下を参照してください。

新しいレスポンシブ対応テンプレートについて詳しくは、以下を参照してください。

アップデートされたレスポンシブ対応コンポーネントとテンプレート

APL 1.4は、既存のレスポンシブ対応コンポーネントとテンプレートに新しいプロパティを追加します。

AlexaTextListItemコンポーネントに次の新しいプロパティが追加されました。

  • emptyRatingGraphic
  • entities
  • fullRatingGraphic
  • halfRatingGraphic
  • hideHorizontalMargin
  • imageThumbnailSource
  • ratingGraphicType
  • ratingNumber
  • ratingSlotMode
  • ratingText
  • secondaryText
  • secondaryTextPosition
  • singleRatingGraphic
  • singleRatingGraphicWidth
  • tertiaryText
  • tertiaryTextPosition
  • touchForward

オブジェクトで渡されたこれらの新しいプロパティをAlexaTextListのlistItemsプロパティに含めると、テキストリストに追加の情報が表示されます。

AlexaImageListItemコンポーネントに次の新しいプロパティが追加されました。

  • emptyRatingGraphic
  • entities
  • fullRatingGraphic
  • halfRatingGraphic
  • hasPlayIcon
  • ratingGraphicType
  • ratingNumber
  • ratingSlotMode
  • ratingText
  • singleRatingGraphic
  • singleRatingGraphicWidth

オブジェクトで渡されたこれらの新しいプロパティをAlexaImageListのlistItemsプロパティに含めると、画像リストに追加の情報が表示されます。

AlexaTransportControlsコンポーネントに次の新しいプロパティが追加されました。

  • entities
  • primaryControlPauseAction
  • primaryControlPlayAction
  • secondaryControls
  • secondaryControlsAVGLeft
  • SecondaryControlsAVGRight
  • secondaryControlsLeftAction
  • secondaryControlsRightAction
  • theme

すべてのコンポーネントとテンプレートにentitiesプロパティが新規追加

すべてのレスポンシブ対応コンポーネントとテンプレートに、entitiesプロパティが含まれるようになりました。このプロパティは、基本コンポーネントのentityまたはentitiesプロパティへのアクセスを提供します。

定義したデータの配列をentitiesに渡すことができます。ドキュメントが画面に表示され、スキルがリクエストを受け取ると、リクエストのコンポーネントのcontextに、このentityデータが含まれます。

ユーザージェスチャーのサポート

APLは、新しいユーザーインタラクションとジェスチャーをサポートするようになりました。たとえば、コンポーネントをドラッグしたり、スワイプしてアイテムを削除したり、画面を長押ししたりできます。イベントハンドラーを定義して、これらのイベントを取得してコマンドを実行できます。

すべてのタッチ可能なコンポーネントは、新しいイベントハンドラーonDown、onMove、onUpをサポートします。タッチ可能なコンポーネントには、TouchWrapperとVectorGraphicが含まれます。

TouchWrapperコンポーネントは、長押しやスワイプなどの追加のユーザーイベントを取得するジェスチャーハンドラーのセットもサポートします。

AlexaSliderとAlexaSliderRadialのレスポンシブ対応コンポーネントは、これらの新しいハンドラーを使って、ユーザーがドラッグしてコンテンツをスクラブしたり、設定を変更したりできる対話型の進捗バーを作成します。

Alexa Vector Graphic（AVG）形式の機能強化

新しいAVG 1.1形式には、いくつかの機能強化が含まれています。

  • ベクターグラフィック内でスタイル、リソース、パターンを定義できます。
  • グラデーションなど、ストロークと塗りつぶしのオプションが追加されました。
  • ベクターグラフィックスはテキスト項目を描画できます。

詳細については、Alexa Vector Graphic形式を参照してください。

オーサリングツールで作成したドキュメントへのリンクをRenderDocumentディレクティブで使用できるようになりました。つまり、APLドキュメントのJSONを書き出して、コードにコピーする必要はありません。

オーサリングツールのドキュメントへのリンクには、次の構文があります。

  • APL – doc://alexa/apl/documents/<document-name>
  • APL for Audio – doc://alexa/apla/documents/<document-name>

たとえば、「helloworld-by-link」というドキュメントに「doc://alexa/apl/documents/helloworld-by-link」でリンクできます。

RenderDocumentのリンクを参照するには、documentプロパティをtypeとLinkのプロパティを持つオブジェクトに設定します。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.RenderDocument",
      "token": "helloworld-by-link",
      "document": {
        "src": "doc://alexa/apl/documents/helloworld-by-link",
        "type": "Link"
      },
      "datasources": {},
      "packages": []
    }
  ]
}

RenderDocumentの構造に変更はありません。既存のスキルは変更しなくても、引き続き機能します。

APLのRenderDocumentについては、Alexa.Presentation.APLインターフェースのリファレンスを参照してください。

APL for AudioのRenderDocumentについては、Alexa.Presentation.APLAインターフェースのリファレンスを参照してください。

時間に基づいてコマンドを実行する

ティックイベントハンドラーを定義できるようになりました。時間が経過すると、システムはティックハンドラーを呼び出します。たとえば、ティックハンドラーを使用して、プログレスバーをアニメーション化します。

すべてのコンポーネントおよびドキュメントで新しいhandleTickプロパティを使用して、ティックハンドラーを定義することができます。

ティックハンドラーの詳細については、ティックイベントハンドラーを参照してください。

コンポーネントおよびドキュメントの新しいhandleTickプロパティの詳細については、以下を参照してください。

AlexaProgressBarレスポンシブ対応コンポーネントで機能するティックイベントハンドラーの例については、正確な進捗バーを進めるを参照してください。

APL Extensionsとbackstack

APLに、extensionsが追加されました。extensionsはAPLに追加機能を提供しますが、APLをサポートしていても、一部のデバイスでは利用できない場合があります。

extensionsのしくみとドキュメントでの使い方については、extensionsを参照してください。

backstack extensionを使うと、ドキュメント間で戻る操作が可能になります。これは、HTMLでの戻る操作に似ています。backstack extensionの詳細については、Backstack Extensionを参照してください。

新しいAPLコンポーネント

  • 新しいEditTextコンポーネントを使用して、編集可能なテキストボックスを表示します。ユーザーは、画面上のキーボードを使用して編集ボックスにテキストを入力できます。詳細については、EditTextを参照してください。
  • 新しいGridSequenceコンポーネントを使えば、行と列のあるグリッドに項目のリストを表示できます。

APLコマンドの変更

  • 新規のsequencerプロパティ – コマンドに、sequencerプロパティが追加されました。これにより、一連のコマンド実行時によりきめ細かい制御が可能になります。sequencerを使って、コマンドを高速モードではなく通常モードで強制的に実行することもできます。
  • event.sourceとevent.targetでアクセス可能なプロパティの追加 – あるコンポーネントがAPLイベントのソースまたはターゲットの場合に、より多くの情報にアクセスできるようになりました。たとえば、以前のバージョンでは、TouchWrapperのchecked状態をevent.source.valueから取得していました。新バージョンでは、event.source.checkedからそのデータを取得できます。event.source.valueプロパティは廃止されましたが、下位互換性のためにまだ使用できます。

コマンドの詳細については、APLコマンドを参照してください。各コンポーネントで報告される具体的なプロパティについては、そのコンポーネントのトピックを参照してください。

更新情報

  • タブレットモード – Fireタブレットで、Showモードだけでなく、TabletモードのAPLコンポーネントも表示できるようになりました。ユーザーがタブレットモードでスキルを呼び出すと、タブレットにはハブviewport用に縮小されたAPLコンテンツが表示され、向きが縦長に固定されます。
  • 新しい数学関数 – データバインディングコンテキストで、新しい数学関数を利用できるようになりました。詳細については、数学関数を参照してください。

コンポーネントのプロパティ

Containerコンポーネントの変更点は次のとおりです。

  • 新しいwrapプロパティ
  • directionプロパティの新たなオプション

Frameコンポーネントに新しいborderStrokeWidthプロパティが追加されました。

Sequenceコンポーネントに、Sequence子プロパティのscalingプロパティが新規追加されました。

APLドキュメントのプロパティ

ドキュメントで、次の新しいトップレベルプロパティを指定できるようになりました。

APLのバージョンを指定する

APLドキュメントで、versionを"1.4"に設定します。

APLの最新バージョンをサポートしていない古いデバイスで、スキルが呼び出される場合があります。特定のバージョンのAPLで導入された機能を使用する場合は、それ以前のバージョンのAPLを実行しているデバイス向けに代替機能を提供してください。データバインディングコンテキストのenvironment.aplVersionプロパティを使用すると、デバイスのAPLのバージョンを取得できます。このプロパティでは、APL 1.0についてはnullが、APL 1.1以降では実際のバージョン番号が返されます。このプロパティをwhenステートメントで使用すると、バージョンに基づく条件付きブロックを作成できます。

たとえば、次のようにすると、APL 1.1以降を使用しているデバイスではVectorGraphicを、APL 1.0を使用しているデバイスでは画像（Image）をレンダリングできます。

[
  {
    "type": "Image",
    "when": "${environment.aplVersion == null}",
    "width": 100,
    "height": 100,
    "source": "https://example.com/alternate/image/for/older/versions.jpg"
  },
  {
    "type": "VectorGraphic",
    "when": "${environment.aplVersion != null}",
    "source": "lightbulb",
    "width": 100,
    "height": 100,
    "scale": "best-fit"
  }
]

APLのバージョンは、スキルに送信されるリクエストにも含まれています。

context.System.device.supportedInterfaces.['Alexa.Presentation.APL'].runtime.maxVersion

次の例は、APL 1.4に対応したデバイスからのリクエストを示しています。短くするために、session、request、viewportの各プロパティは省略しています。

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.1"
      },
      "user": {
        "userId": "amzn1.ask.account.1"
      },
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "1.4"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}

以前のバージョンのAPL

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment