レスポンシブ対応のAPLドキュメントを作成する



レスポンシブ対応のAPLドキュメントを作成する

ユーザーは、さまざまな画面のサイズ、形状、アスペクト比を持つデバイスでスキルを呼び出せます。こうしたすべてのデバイスでスキルの見栄えを良くするには、レスポンシブ対応のAPLドキュメントを作成する必要があります。

レスポンシブ対応のAPLドキュメントとは

レスポンシブ対応のAlexa Presentation Language(APL)ドキュメントは、<a data-toggle="popover" title="viewport" data-placement="auto" data-html="true" data-content="画面付きのAlexa搭載デバイスでは、「viewport」はユーザーに表示される画面領域のことを指します。viewportには形状、向き、サイズ、密度があります。">viewport</a>の特性に合わせて調整できます。たとえば、大画面デバイスの場合は画面上部にスキルのタイトルとサブタイトルのテキストを表示し、Echo Spotなどの小型デバイスの場合はスキルを表すアイコンのみを表示します。

一方、Fire TV向けに作成された非レスポンシブ対応のAPLドキュメントは、小型のEcho SpotやEcho Show 5では使用できない場合もあります。結果として、ユーザーのエクスペリエンスが低下し、スキルが再び使用される可能性が低くなります。

最も効果的な方法は、特定のデバイスではなく、デバイスのviewportプロファイルに応答性を組み込む方法です。つまり、画面が特定の形状(横長など)で、かつサイズ範囲(xより大きい、yより小さい)に該当する場合に使用するレイアウトを定義できます。この方法は、正確な画面サイズを対象にするよりも柔軟性があります。新たに利用可能になったデバイスが上記と同じサイズ範囲に該当する場合、APLドキュメントは新しいデバイスで適切に機能する準備が既に整っています。

APLでレスポンシブ対応ドキュメントの作成がサポートされる仕組み

APLは、レスポンシブ対応ドキュメントの作成をサポートするように設計されています。さらに、APLでは柔軟な方法でドキュメントを作成できます。さまざまなデバイスで機能するドキュメントや、別のデバイスで使用すると完全に停止してしまう、1つのデバイスでのみ機能するドキュメントを作成できます。

APLドキュメントを作成する際は、可能な限りレスポンシブ対応機能を使用するようにしてください。レスポンシブ対応機能は次のとおりです。

  • 条件付きロジックを使用できます。特定のコンポーネントまたはレイアウトをviewportに表示するかどうかを決定する基準を定義できます。この基準では、viewportサイズなどのデバイスの特性を使用できます。

  • スタイルとリソースを使用できます。プロパティ値をハードコーディングするのではなく、一連のプロパティをグループ化して名前を付け、スタイル名とリソース名を使用できます。また、これらの項目は条件付きロジックを持つことができるので、小さなviewportと大きなviewportで別々のフォントサイズを設定してスタイルを定義できます。

  • Viewportプロパティを使用できます。viewportプロファイルは条件付きロジックの基準として使用できます。Viewportプロファイルは、viewport特性の範囲を表す名前付きリソースです。プロファイルでは形状、向き、サイズの範囲、密度の範囲を指定するため、複数の物理デバイスを表すことができます。これらのプロファイルにロジックの基盤を置くことで、新しいデバイスが利用可能になった際により堅牢なロジックを確保できます。

  • 相対ディメンションを使用できます。ほとんどのサイズは、「100%」などの相対ディメンションで表すことができます。viewportのサイズに基づいた絶対ディメンション(viewportの幅を100%とする「100vw」など)を使用することもできます。使用するディメンションの種類を適切に選択すると、デザインとコンポーネントがさまざまなサイズのviewportに合わせて確実に調整されます。

  • Alexaのレスポンシブ対応コンポーネントを使用できます。APL向けAlexaデザインシステムの一部として、すぐに使用できる一連のコンポーネントが用意されています。これらは、コンポーネント(プリミティブなUI要素)をドキュメントで使用できる構成要素に統合します。レスポンシブ対応コンポーネントを使用すると、一から作成するという手間を省いて簡単に応答性を実現できます。

  • Alexaのレスポンシブ対応テンプレートを使用できます。APL向けAlexaデザインシステムの一部として、すぐに使える一連のテンプレートが用意されています。テンプレートでは、コンポーネント(プリミティブなUI要素)とレスポンシブ対応コンポーネントを、viewport全体に表示される完全なレイアウトに統合しています。レスポンシブ対応テンプレートを使用すると、一から作成するという手間を省いて簡単に応答性を実現できます。

  • Alexa Stylesを使用できます。APL向けAlexaデザインシステムの一部として、すぐに使える一連のスタイルが用意されています。Alexa Stylesは条件付きロジックで作成されるため、さまざまなviewportに合わせて調整できます。

このドキュメントの残りのセクションでは、これらの機能と概念を使用してドキュメントをレスポンシブ対応にする方法について詳しく説明します。

APL向けAlexaデザインシステムを使用する

Alexaデザインシステムでは、スキルで使用できるプレビルドのレスポンシブ対応コンポーネント、テンプレート、スタイルが含まれたパッケージを提供しています。これらはすべて、さまざまなviewportに対応するレスポンシブ仕様になっています。以下のトピックを参照してください。

レスポンシブ対応テンプレート

APL向けAlexaデザインシステムで提供されているレスポンシブ対応テンプレートを使用すると、レスポンシブ対応ドキュメントを簡単に作成することができます。各テンプレートにはviewport全体に表示されるレイアウトが用意され、そこにはヘッダーや背景などの必要な要素がすべて含まれています。表示するコンテンツをカスタマイズするには、テンプレートのプロパティを設定します。このオプションを使用する場合、視覚階層にコンポーネントを自分で配置する必要はありません。1つの項目をドキュメントに配置するだけで、全体に適用されます。

たとえば、次のAPLドキュメントでスクロールリストを作成します。mainTemplateプロパティには、AlexaTextListタイプの項目が1つ含まれています。

一方、同様のレイアウトを一から作成するには、次のコンポーネントをmainTemplate内にすべて正確に配置する必要があります。

  • 上部にタイトルを表示するTextコンポーネント
  • 小さなviewportの上部にアイコンを表示するImageコンポーネント
  • 背景を作成するImageまたはFrame
  • スクロールリストを作成するSequence
  • 各項目の番号を表示するText
  • 各項目のテキストを表示するText
  • リスト項目を選択できるように設定するTouchWrapper

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

次のレスポンシブ対応テンプレートを使用できます。

レスポンシブ対応コンポーネント

APL向けAlexaデザインシステムに用意されているレスポンシブ対応コンポーネントは、コンポーネント(プリミティブなUI要素)をドキュメントで使用できる構成要素に統合しています。各レスポンシブ対応コンポーネントは、レスポンシブ仕様となっています。これらのコンポーネントを組み合わせて、カスタムレイアウトを作成できます。

たとえば、次のコンポーネントを組み合わせてカスタム詳細ページを作成できます。

この場合、ヘッダー、フッター、背景はすべて、さまざまなviewportに合わせて調整されます。レイアウトの本文部分をデザインするだけで、各種viewportに対応できます。次の例ではこれを行うために、TextコンポーネントにmaxLinesプロパティを設定して2行のみを表示し、小さな円形のデバイスではテキストを切り詰めるように指定しています。さらに複雑な本文のレイアウトでは、広範な条件付きロジックとテクニックが必要になります。このサンプルでは、正しいヒントテキストを作成するためにデータソースを使用しています。詳細とサンプルについては、textToHintトランスフォーマーを使用するを参照してください。

レスポンシブ対応コンポーネントを使用してカスタムレイアウトを作成する場合は、後半で説明するベストプラクティスに従って、デザインの残りの部分をレスポンシブ対応にしてください。

次のレスポンシブ対応コンポーネントを使用できます。

Alexa Styles

スタイルは、ドキュメントのコンポーネントに適用できる一連の視覚的特性を表します。APL向けAlexaデザインシステムで提供されているAlexaスタイルパッケージalexa-styles)には、ドキュメントで使用できる一連のスタイルが含まれています。これらのスタイルは、さまざまなviewportや状況に対応できるように条件付きロジックを使用して作られています。

たとえば、fontSizeLargeスタイルは大きなフォントサイズを定義します。実際のサイズはデバイスのviewportによって変わるため、横長のデバイスではフォントが大きくなり、円形のデバイスではフォントが小さくなります。

スタイルを使用することで、スキルの外観と操作感の一貫性を保つことができます。

スタイルの詳細については、Alexa Stylesを参照してください。

スタイルを設定することができるコンポーネントプロパティについて詳しくは、スタイル設定可能プロパティを参照してください。

レスポンシブ対応ドキュメントに関するベストプラクティス

APLコンポーネントとレスポンシブ対応コンポーネントを組み合わせてAPLドキュメントを作成する場合は、次のベストプラクティスに従って、ドキュメントがすべての異なるviewportで機能するようにしてください。

適切にディメンションを設定する

コンポーネントの高さと幅は、絶対ディメンションと相対ディメンションのどちらでも指定できます。

  • 絶対ディメンションとは、「20dp」のように特定の画面非依存ピクセル数を指します。viewportの高さまたは幅に基づいて、vhvwの単位で絶対ディメンションを指定できます。たとえば、"100vw"はviewportの幅全体を表します。Echo Showなどの大きなデバイスの場合、 "100vw"を指定すると1280dp、"50vh"を指定すると640dpになります。この方法でディメンションを指定すると、ディメンションは使用されている実際のviewportと常に相対的になるため、レスポンシブ対応が実現します。
  • 相対ディメンションとは、コンポーネントの親のサイズに対する相対的な割合(「80%」など)のことです。

これらの方法を組み合わせて、さまざまな方法でディメンションを表してレイアウトを完成させます。たとえば、次の単純な階層構造を考えてみましょう。

mainTemplate
    Container
        Text
        Text

この例では、最上位のContainerheightwidthをそれぞれ100vh100vwに設定して、viewport全体を使用します。次に、Textコンポーネントのディメンションに割合を使用します。この方法では、viewportではなくContainerに応じてTextブロックのサイズが変更されます。

レスポンシブ対応ドキュメントでは、次のようにします。

  • viewportに応じてコンポーネントのサイズを指定するには、vh単位とvw単位を使用します。
  • 親Containerに応じてコンポーネントのサイズを指定するには、相対ディメンションを使用します。
  • ハードコーディングされた絶対ディメンション(「60dp」など)の使用は避けてください。

条件付きロジックでviewportプロファイルを使用する

条件付きロジックはレスポンシブ対応のAPLドキュメントにおける主要な概念ですが、最も柔軟に対応できる方法でロジックを定義することが重要です。デバイス特性を評価するデータバインディングの式を作成する際は、viewport特性で細かく設定するのではなく、viewportプロファイルパッケージに含まれているviewportプロファイルを使用します。

たとえば、各APLコンポーネントにはブール値を取るwhenプロパティがあります。これは、Alexaがコンポーネントをviewportに表示するかどうかを決定します。コンポーネントを大きなデバイスに表示する場合は、次のようなステートメントを作成します。

"when": "${@viewportProfile == @hubLandscapeLarge}"

次のように幅を指定しないでください。

"when": ${viewport.width == "1280dp"}

2番目のステートメントは非常に狭い範囲のデバイスを対象としているため、レスポンシブ対応ではありません。別の同様のデバイスが1030dpのワイドスクリーンで利用できるようになると、このviewport.width条件のコンポーネントは表示されなくなります。対照的に、hubLandscapeLargeには幅1280~1920の画面を含むため、この条件は新しいデバイスでも機能します。viewportプロファイル向けのロジックを作成すると、一度で複数の類似デバイスに対応できるようになります。特定のデバイスやviewport特性に応じて細かく設定する必要はありません。

viewport.shapeなど、個別のデバイス特性についても同様の問題が発生する可能性があります。${viewport.shape == 'round'}の式を例に挙げてみましょう。サイズに関係なく円形の画面を搭載するデバイスで、この式はtrueと評価されます。この式を使用して小さな円形のデバイス(Echo Spotなど)のコンテンツを扱う場合、大型の円形画面を備えた新しいデバイスが利用可能になると、スキルが機能しなくなるおそれがあります。${viewport.shape == 'round'}などの式を使用するのは、任意のサイズの円形の画面でのみコンポーネントを表示する場合にとどめてください。

最後に、viewportプロファイル全体ではなくサイズに基づいて条件を作成する必要がある場合は、viewportプロファイルパッケージでも定義されているサイズリソースを使用します。次に例を示します:

"when": "${viewport.width == @viewportSizeMedium}"

高さと幅をグループ化するサイズクラスを使用することもできます。

"when": "${@viewportSizeClass == @viewportClassMediumLarge}"

viewportプロファイルと同様に、サイズリソースも指定の範囲内で機能するため、複数の異なるデバイスが同じviewportSizeMediumサイズに該当する可能性があります。

条件付きロジックをドキュメントに組み込む

実行時にスキルコードに機能を分岐させるのではなく、条件付きロジックをAPLドキュメントに組み込みます。前述のviewportプロファイルと、データバインディングコンテキストViewportオブジェクトのプロパティを使用して、条件付きロジックを作成します。

viewportに関する情報は、スキルリクエストのViewportオブジェクトのスキルコードでも使用できます。ただし、ドキュメントではなくロジックをコードに配置する場合は、デメリットがあります。

  • リクエストのViewportオブジェクトには、幅や高さなどのviewport特性のみが含まれます。前述のviewportプロファイルと同等に機能させるには、いずれかのASK SDKをヘルパー関数と併用するか、独自のヘルパー関数を作成して個別のデータからプロファイルを算出する必要があります。
  • オーサリングツールでのテストと実験が難しくなります。ロジックをドキュメントに組み込むと、ドキュメントをオーサリングツールにアップロードしてそれぞれのviewportをクリックすることで、表示方法を確認したり変更を試したりできます。しかし、ロジックをコードに組み込むと(別々のドキュメントを全体的に管理し、実行時に適切なものを選択するなど)、オーサリングツールでドキュメント全体を切り替えて、さまざまなviewportでの表示方法を確認する必要があります。

ドキュメントをモジュール化する

APLは、モジュール化したドキュメントをサポートするように設計されています。alexa-layoutsパッケージで提供されているレスポンシブ対応コンポーネントは、その一例です。レスポンシブ対応コンポーネントは、APLコンポーネントと条件付きロジックを1つの構成要素に統合しています。これをドキュメントに配置することで、いろいろなデバイスや状況への対応が可能になります。

提供されているコンポーネントがニーズに合わない場合は、独自のレスポンシブ対応コンポーネントを作成することで、同じアプローチを取ることができます。カスタムコンポーネントをAPLドキュメントのlayoutsプロパティに追加します。次に、APLコンポーネントとレスポンシブ対応コンポーネントを使用する場合と同様に、mainTemplateでカスタムコンポーネントを使用します。

これにより、コンポーネントの外観、機能、レスポンシブ対応を1か所にカプセル化して、簡単に把握したり管理したりできるようになります。

たとえば、単純な「豆知識スキル」では、関連する背景画像やキャプションと共に、関連する豆知識を表示するドキュメントをレンダリングします。豆知識のテキストは長いため、小さな円形のデバイスでは非表示にして、画像のキャプションのみを表示することをお勧めします。これを設定するFactTextAndCaptionBlockレイアウトを作成して、そのレイアウトをAlexaBackgroundレスポンシブ対応コンポーネントと共に配置します。

以下の例では、このカスタムレイアウトの定義が設定されたlayoutsプロパティと、キャプションテキストの書式を設定するカスタムスタイルを示しています。

クリップボードにコピーされました。

{
  "styles": {
    "mainFactText": {
      "description": "表示するメインテキストの視覚プロパティです。",
      "values": [
        {
          "textAlign": "center",
          "textAlignVertical": "center",
          "fontSize": "@fontSizeLarge"
        }
      ]
    },
    "captionText": {
      "description": "赤字の斜体キャプションのスタイルです。",
      "extends": "mainFactText",
      "values": [
        {
          "color": "red",
          "fontStyle": "italic",
          "fontSize": "@fontSizeMedium"
        }
      ]
    }
  },
  "layouts": {
    "FactTextAndCaptionBlock": {
      "description": "豆知識のテキストを表示し、その後に画像に関連するキャプションを付けます。小さな円形のデバイスにキャプションのみを表示します。",
      "parameters": [
        "factText",
        "imageCaption"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "justifyContent": "center",
          "grow": 1,
          "items": [
            {
              "type": "Text",
              "when": "${@viewportProfile != @hubRoundSmall}",
              "paddingLeft": "@spacingLarge",
              "paddingRight": "@spacingLarge",
              "text": "${factText}",
              "style": "mainFactText"
            },
            {
              "type": "AlexaDivider",
              "when": "${@viewportProfile != @hubRoundSmall}",
              "width": "50%",
              "alignSelf": "center",
              "paddingTop": "@spacingSmall",
              "paddingBottom": "@spacingSmall"
            },
            {
              "type": "Text",
              "paddingLeft": "@spacingSmall",
              "paddingRight": "@spacingSmall",
              "text": "Image: ${imageCaption}",
              "style": "captionText"
            }
          ]
        }
      ]
    }
  }
}

これで、mainTemplateには、AlexaBackgroundFactTextAndCaptionBlockを持つContainerを指定するだけで済みます。

クリップボードにコピーされました。

{
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100vw",
        "height": "100vh",
        "items": [
          {
            "type": "AlexaBackground",
            "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT1_Background.png",
            "colorOverlay": "true"
          },
          {
            "type": "FactTextAndCaptionBlock",
            "factText": "これは豆知識のテキストです。テキストを適切に表示できるだけの十分な大きさの画面があるデバイスに表示されるようにします。スキルでは応答でこのテキストを読み上げるので、小さすぎるデバイスには表示しなくても構いません。",
            "imageCaption": "これは、背景画像に関する簡潔なキャプションです。"
          }
        ]
      }
    ]
  }
}

レスポンシブ対応のAPLドキュメントをテストする

スキルを作成したら、さまざまなviewportで表示をテストします。実際のデバイスでテストすることをお勧めしますが、テストページオーサリングツールまたはシミュレーターを使用することもできます。

  • オーサリングツールを使用して、作成したドキュメントを確認します。アカウントを登録したデバイスをお持ちの場合は、作成したドキュメントを対象のデバイスに送信できます。
  • テストページで、スキルコード、音声入力、Alexaの応答を使用してドキュメントをテストします。ExecuteCommandsディレクティブを使用して実行したコマンドをテストするには、ランタイムコード(Lambda関数など)をテストする必要があります。

オーサリングツールとシミュレーターの両方で、さまざまなviewportを使ってテストできます。また、カスタムviewportを作成すると、使用予定のデバイスでのスキルの外観を確認できます。

ツールの使用方法の詳細については、以下を参照してください。

スキルでサポートするviewportプロファイルを選択する

ドキュメントをレスポンシブ対応にして、さまざまなデバイスで正常に表示されることを確認したら、ビルド>カスタム>インターフェースページに戻って、スキルですべてのviewportプロファイルがサポートされるように選択します。Alexaはドキュメントを表示する前にサポートの有無を確認するため、この作業は重要です。サポートされるプロファイルのいずれにもデバイスが一致しない場合、コンテンツは画面に合わせてサイズ調整されます。

このようなサイズ調整は最終手段と考えるべきであり、ドキュメントがレスポンシブ対応であればこの手段は必要ありません。

サポートされるプロファイルとサイズ調整のしくみについて詳しくは、スキルでサポートするViewportプロファイルを選択するを参照してください。