オーサリングツールを使用したAPLドキュメントの作成



オーサリングツールを使用したAPLドキュメントの作成

APLオーサリングツールを使用すると、APLドキュメントを作成し、それをプレビューで確認することができます。ドキュメントを最初から作成することも、サンプルテンプレートから始めて、自分のスキルに合うように変更を加えることもできます。

APLの概要も参照してください。

APLオーサリングツールを開く

オーサリングツールを直接開くには、https://developer.amazon.com/alexa/console/ask/displays/?をクリックします。

開発者コンソールでスキルの作成や編集を行っている場合は、左にある画面表示リンクをクリックすることもできます。この場合、別タブにオーサリングツールのページが開きます。

オーサリングツールで作成したコンテンツは、ユーザーが作成したどのスキルにもリンクされていません。作成したドキュメントを使用するには、ドキュメントを書き出して、スキルサービスで開発するスキル応答で使用します。

テンプレートから作成する

サンプルテンプレートから作成して、スキルに合わせて変更することができます。

オーサリングツールに含まれているサンプルのベースはDisplayテンプレートです。このテンプレートは、画面にコンテンツを表示するAlexaスキルを開発した方は使用したことがあるかもしれません。たとえば、詳細テキストサンプルは、BodyTemplate1に似ています。

APLオーサリングツール:詳細テキストサンプル
APLオーサリングツール: 詳細テキストサンプル
  1. オーサリングツールを開きます(https://developer.amazon.com/alexa/console/ask/displays/?をクリックします)。
  2. メインのマルチモーダルディスプレイページで、いずれかのテンプレートをクリックします。

各テンプレートはデータソースを使用して、レイアウトで表示されるコンテンツを提供します。JSONデータをクリックしてデータソースを確認します。次に、BodyTemplate1の場合、背景画像、テキストコンテンツ、ロゴURL画像の参照が含まれます。このJSONデータのコンテンツを変更して、テンプレートが別のコンテンツでどのように表示されるか確認できます。

APLオーサリングツール:JSONデータ
APLオーサリングツール: JSONデータ

各テンプレートは、ドキュメントのmainTemplateで使用されるリソースとスタイルを定義します。ドキュメントをすべて確認する場合はJSONを見ます。または右下のパネルのリソースまたはスタイルセクションを開きます。

これらのサンプルを使用して、コンポーネント、上部のレンダリング表示、JSONデータコンテンツを確認することで、APLの構造を把握します。オーサリングツールのインターフェースの操作について詳しくは、コンポーネントとデータを使用するを参照してください。

既存のコードを読み込む

既存のAPLドキュメントをツールにアップロードして、別のデバイスでプレビューすることができます。その後そのドキュメントを編集して、変更をプレビューすることもできます。完成したら、変更を反映した新しいAPLドキュメントを書き出します。

APLドキュメントをオーサリングツールにアップロードする

  1. オーサリングツールを開きます(https://developer.amazon.com/alexa/console/ask/displays/?をクリックします)。
  2. メインのマルチモーダルディスプレイページで、コードをアップロードをクリックします。
  3. 確認するAPLドキュメントを定義するJSONファイルを選択します。

シミュレートされた画面が表示されたら、別のデバイスを選択して、異なるサイズでスキルがどのように表示されるか確認します。

ドキュメントは正常に読み込まれるが、コンテンツが表示されない場合、ドキュメントが別のデータソースのデータを参照している可能性があります。次に説明しているとおりにデータをアップロードします。

エラーが発生してツールがドキュメントを読み込めない場合は、JSONの形式を確認してください。オーサリングツールは、ドキュメントが単一のトップレベルの「document」プロパティ内に存在することを前提としています。たとえば、以下のようになります(詳細は省略しています)。

{
  "document": {
    "type": "APL",
    "version": "1.0",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

別のデータソースを使用してドキュメントをプレビューする

多くの場合、APLドキュメントは、デザインと表示されるデータを切り離すために、別のデータソースを使用します。この場合、コンテンツを確認するには、データを表すJSONをオーサリングツールにアップロードする必要もあります。これにはいくつかの方法があります。

  • ドキュメントとデータの両方を使用して1個のJSONファイルを作成してアップロードします。
  • ドキュメントをアップロードし、次にオーサリングツールのデータにJSONを貼り付けます。

1個のファイルをアップロードするには、ユーザーのドキュメントのJSONとデータを2つのトップレベルプロパティ、documentdatasourcesを持つ1個のJSONファイルと結合します。これは、オーサリングツールからテンプレートのコードをダウンロードしたときに取得する出力に似ています。

この例では、アップロードするファイルの全体の構造を示します(詳細は省略しています)。

{
  "document": {
    "type": "APL",
    "version": "1.0",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": []
    }
  },
  "datasources": {
    "bodyTemplate7Data": {
      "type": "object",
      "objectId": "bt7Sample",
      "title": "今日のチーズの写真",
      "backgroundImage": {},
      "image": {},
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
      "hintText": "試してください\"アレクサ、ブルーチーズについて調べて\""
    }
  }
}

このJSONをAPLドキュメントをオーサリングツールにアップロードするで説明したとおりにアップロードします。

または、ドキュメントをアップロードしてから、データをオーサリングツールに別々にコピーします。この場合、単一のトップレベルのdocumentプロパティを持つJSONファイルをアップロードします。

{
  "document": {
    "type": "APL",
    "version": "1.0",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

ドキュメントを読み込んだ後、データにコピーする必要があります。

  1. JSONデータタブをクリックします。
  2. JSONをデータソースの波括弧{}の中に貼り付けます。トップレベルのプロパティは、datasourcesなどの他のプロパティ名ではなく、データソースの名前である必要があります。 たとえば、JSONデータタブのコンテンツはこのようになります。
{
  "bodyTemplate7Data": {
    "type": "object",
    "objectId": "bt7Sample",
    "title": "今日のチーズの写真",
    "backgroundImage": {},
    "image": {},
    "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
    "hintText": "試してください\"アレクサ、ブルーチーズについて調べて\""
  }
}

最初から作成する

メインページで「最初から作成」を選択した場合は、すべてのコンポーネントとデータソースを最初から作成する必要があります。ユーザー定義のコンポーネントの作成方法については、APLの概要を参照してください。

  1. オーサリングツールを開きます(https://developer.amazon.com/alexa/console/ask/displays/?をクリックします)。
  2. メインのマルチモーダルディスプレイページで、最初から作成をクリックします。

コンポーネントとデータを使用する

APLドキュメントとデータソースをツールに読み込むと、画面の中央上部にドキュメントのおおよそのレンダリング結果が表示されます。レイアウトに含まれるコンポーネントは、画面左下のセクションに階層形式で表示されます。

コンポーネントをクリックすると、画面上部のレンダリング表示で、対応するコンポーネントが強調表示されます。

コンポーネントのコンテンツは中央下部に書式で表示され、パラメーターがある場合は、選択されたコンポーネントのパラメーターのリストが表示されます。コンポーネントの各フィールドに値を入力できます。必要に応じてオプションのフィールドを空白のままにします。フォームを使うと、各コンポーネントに有効なJSONが含まれていることを確認しやすくなります。

APLオーサリングツール:コンポーネントフォーム
APLオーサリングツール: Containerフォーム

コンポーネントを追加、編集、削除する

コンポーネントを追加するには:

  1. 追加するコンポーネントの親になる既存のコンポーネントをクリックします。Containerなど、子コンポーネントを含むことのできるコンポーネントを選択する必要があります。
  2. +をクリックし、コンポーネントを追加ウィンドウにコンポーネントの情報を入力します。

コンポーネントを削除するには、選択した状態でゴミ箱アイコンをクリックします。

コンポーネントの編集時に、別のコンポーネントをクリックしてから変更したコンポーネントに戻っても、以前に行った変更内容は保持されています。作業バージョンの保存について詳しくは、作業の書き出しと保存を参照してください。

ドキュメントのJSONコードを表示する

右下にあるスイッチをクリックすると、コンポーネントを表示するか、作成中のコードを表示するかを切り替えられます。このコードビューでは、コンポーネントすべてを含むJSONファイルのドキュメント全体を確認して、直接編集することができます。編集後もJSONが有効なことを確認します。

APLオーサリングツール--コンポーネントビューをコードビューに切り替える

このドキュメントに関連付けられたドキュメントリーススタイルのコンテンツは、右下のセクションで確認できます。表示するJSONコンテンツをクリックすると、そのコンテンツが表示されます。これらのコンテンツは、レイアウトのコンポーネントと同様に編集できます。コンテンツの表示と非表示はクリックで切り替えられ、変更内容は自動で保存されます。以下の図は、詳細テキストサンプルドキュメントコンテンツです。

APLオーサリングツール:ドキュメントコンテンツ
APLオーサリングツール: ドキュメントコンテンツ

異なるviewportでドキュメントを表示する

ドキュメントの作業中に、画面上部にある別のviewportのアイコンをクリックして、別のデバイスでどのように表示されるか確認します。viewportプロファイルパッケージで使用できるviewportパッケージに対応する、5つのviewportを使用してプレビューできます。

  • 小型デバイス(円形)
  • ハブ(横長)
  • 中型デバイス
  • 大型デバイス
  • 超大型TV

viewportのプロパティについて詳しくは、Alexa Viewportプロファイルパッケージを参照してください。

後述のように、カスタムviewportを作成することもできます。

別のviewportでプレビューするためのアイコン
別のviewportでプレビューするためのアイコン

カスタムviewportを作成する

カスタムviewportを作成して、作成したデザインが5つの定義済みプロファイルとは異なるデバイスではどのように表示されるのか、確認することができます。

  1. プラス記号のアイコンをクリックします。
  2. 表示するviewportのプロパティを変更します。形状ピクセル幅ピクセル高さピクセル密度を設定できます。デバイスがビデオをサポートするかどうかも指定することができます。
  3. 適用をクリックします。

カスタムviewportは、現在のブラウザのセッション中は引き続き使用できます。ブラウザを閉じて、後でオーサリングツールを再度開くと、カスタムviewportを再作成する必要があります。

ビデオ再生をサポートしないデバイスをシミュレートする

ビデオ再生をサポートしない画面付きデバイスを処理できるようなデザインにしなければなりません。ビデオをサポートしないデバイスをシミュレートする、カスタムviewportプロファイルを作成できます。

  1. 新しいカスタムインテントを作成します。
  2. ビデオを許可しないチェックボックスを選択します。

作成したコードを書き出す

後で作業するために保存したり、スキルコードで使用したりするには、JSONファイル形式でコードを書き出す必要があります。コードを書き出しボタン(コードを書き出しボタン)をクリックしてJSONを保存します。

これにより、ドキュメントとデータがトップレベルにdocumentdatasourcesプロパティを持つ1個のJSONファイルに結合されます。後でこのファイルを再読み込みすると、作業を続行できます。