[ この記事は、Windows ランタイム アプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]
注 JavaScript を使わない場合は、「クイック スタート: タイルの更新の送信 (XAML)」をご覧ください。
タイルは当初、既定のタイルの状態です。既定のタイルはマニフェストに定義されていて、アプリを初めてインストールしたときに表示されます。アプリをインストールした後は、通知によってタイルのコンテンツを変更できます。このクイック スタートでは、新しいタイル コンテンツを定義し、タイルに送って、必要がなくなったらそのコンテンツを削除する手順について説明します。 これらの操作をローカル通知を使って説明します。これは、最も簡単に実装できる通知です。次の手順について説明します。
- 通知のテンプレートを指定する
- テンプレートの空の XML コンテンツを取得する
- テキストを通知に追加する
- 画像を通知に追加する
- 単一のペイロードでさまざまなタイル サイズのさまざまな通知バージョンをパッケージ化する
- 通知に有効期限を設定する
- ローカル通知としてタイルに更新を送信する
この機能の実際の使い方については「アプリの機能の概要」シリーズの次のトピックをご覧ください: Windows ストア アプリ UI の概要
注 このクイック スタートでは、XML ドキュメント オブジェクト モデル (DOM) を使って通知コンテンツを直接操作します。XML コンテンツを Intellisense などのオブジェクト プロパティとして表示する、NotificationsExtensions ライブラリを使ったオプションのアプローチも利用できます。詳しくは、「クイックスタート: コードでの NotificationsExtensions ライブラリの使用」をご覧ください。NotificationsExtensions を使って表されるこのクイック スタートのコードを確認するには、アプリのタイルとバッジのサンプルをご覧ください。
必要条件
このトピックを理解するための要件:
- タイルと通知に関する用語と概念についての実用的知識。詳しくは、「タイル、バッジ、通知」をご覧ください。
- タイルの XML スキーマに関する知識。詳しくは、「タイルのスキーマ」をご覧ください。
- Windows ランタイム API を使って JavaScript で基本的な Windows ストア アプリを作成できること。詳しくは、「JavaScript を使った初めての Windows ストア アプリの作成」をご覧ください。
- アプリのマニフェストに定義されている、既にあるアプリの既定のタイル。詳しくは、「クイック スタート: Microsoft Visual Studio マニフェスト エディターを使用した既定のタイルの作成」をご覧ください。
- XML と、ドキュメント オブジェクト モデル (DOM) API を使った XML の操作に関する知識。
手順
1. 名前空間変数を宣言する (省略可能)
この手順では、名前空間の完全な名前の代わりに使う短い名前を用意します。C# の "using" ステートメント、または Visual Basic の "Imports" ステートメントと同等であり、コードを簡素化できます。
注 このクイック スタートの残りのコードでは、この変数が宣言されていることを前提としています。
var notifications = Windows.UI.Notifications;
2. タイルのテンプレートを選び、その XML コンテンツを取得する
システムによって提供されるテンプレート カタログから、コンテンツのレイアウトのニーズに合ったテンプレートを選びます。テンプレートの全一覧については、TileTemplateType 列挙型をご覧ください。送信する個別の各通知では異なるテンプレートを使うことができることに注意してください。
この例では、TileWide310x150ImageAndText01 テンプレートを使います。このテンプレートは、1 つの画像と 1 つのテキスト文字列を必要とします。次に例を示します。
.png "TileWide310x150ImageAndText01")
var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);
GetTemplateContent メソッドは XmlDocument を返します。上のコードは、次の XML スケルトンを取得します。この XML スケルトンには、この後の手順で標準のドキュメント オブジェクト モデル (DOM) 機能を使って詳細を指定します。
注 Windows 8 システムで getTemplateContent が呼び出された場合、バージョン 1 テンプレートが返されます。Windows 8.1 システムでこのメソッドが呼び出されると、バージョン 2 テンプレートまたはバージョン 3 テンプレート (Windows Phone 専用テンプレート) を返します。アプリがマニフェストで Windows 8 の互換性を指定している場合、このメソッドは Windows のバージョンに関係なく、バージョン 1 テンプレートを返します。このトピックでは、バージョン 2 テンプレートを使います。
<tile>
<visual version="2">
<binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
<image id="1" src=""/>
<text id="1"></text>
</binding>
</visual>
</tile>
3. 通知のテキスト コンテンツを指定する
このコードでは、まず、"text" のタグ名があるテンプレート内のすべての要素を取得します。TileWide310x150ImageAndText01 テンプレートには、1 つのテキスト文字列だけが格納されます。これは、コードによって割り当てられます。この文字列は最大で 2 行に折り返される可能性があり、文字列の長さは切り詰められないように設定する必要があります。
var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));
4. 通知の画像を指定する
このコードでは、まず、"image" のタグ名があるテンプレート内のすべての要素を取得します。TileWide310x150ImageAndText01 テンプレートには単一の画像が格納されます。すべてのタイル テンプレートに画像が格納されるわけではなく、テキストのみの場合もあることに注意してください。
重要 ここで使われる画像 "redWide.png" はただの例であり、Microsoft Visual Studio プロジェクトには含まれていません。この通知を送信する前に、プロジェクトに追加した独自の実際のイメージの名前で "redWide.png" を置き換える必要があります。そうしないと、通知は配信されません。
var tileImageAttributes = tileXml.getElementsByTagName("image");
画像は、アプリのパッケージ、アプリのローカル ストレージ、または Web から使うことができます。この手順のバージョンは、イメージ ソースごとに表示されます。複数の画像が含まれるタイル通知では、画像要素で、これらのタイプのイメージ ソースの任意の組み合わせを使うことができます。テンプレートに使う画像は、サイズが 200 KB 未満かつ 1024 x 1024 ピクセル未満である必要があります。詳しくは、「タイルとトーストの画像サイズ」をご覧ください。
次のコードでは、アプリのパッケージからのローカル画像が使われています。このタイプの画像は Visual Studio ソリューション ファイルに含まれており、アプリの一部としてパッケージ化されています。これらの画像には、"ms-appx:///" プレフィックスを使ってアクセスします。また、スクリーン リーダーなどのアクセシビリティのため、オプションの代替テキストを割り当てることをお勧めします。
tileImageAttributes[0].setAttribute("src", "ms-appx:///images/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");
次のコードでは、アプリのローカル ストレージからのローカル画像が使われています。このタイプの画像は、アプリによってそのローカル ストレージに保存されています。この場所は、Windows.Storage.ApplicationData.current.localFolder によって返されます。これらの画像には、"ms-appdata:///local/" プレフィックスを使ってアクセスします。ここでも、スクリーン リーダーなどのアクセシビリティのためにオプションの代替テキストを割り当てています。
tileImageAttributes[0].setAttribute("src", "ms-appdata:///local/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");
次のコードでは、Web 画像が使われています。これらの画像にアクセスするには、"http://" または "https://" プロトコルを使って画像のパスを指定します。Web 画像を使うには、アプリのマニフェストで internetClient 機能を宣言する必要があります。
tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");
オプションの baseUri 属性を使って "https://www.microsoft.com/" などのルート パスを指定することもできます。これは、画像の src 属性に指定された相対 Uniform Resource Identifier (URI) と結合されます。この属性は、visual 要素 (通知全体に適用する場合) または binding 要素 (そのバインドに適用する場合) に設定できます。baseUri が両方に設定されている場合は、binding の値が visual の値より優先されます。
baseUri が "https://www.contoso.com/" に設定されている場合、サンプル コード内の以下の行は
tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");
次のように短縮できます。
tileImageAttributes[0].setAttribute("src", "redWide.png");
5. ペイロードに複数のタイル サイズの通知バインドを含める
スタート画面では、ユーザーがいつでもタイルのサイズを変えられます。通知を送るときにタイルがどの状態 (小、普通、ワイド、大) かを把握する方法はありません。タイル サイズが一致するテンプレート バインディングが通知にない場合、通知は表示されません。そのため、マニフェストでロゴ イメージを指定するすべてのライブ タイル サイズ (普通、ワイド、大) 用の通知のバージョンを常にペイロードに含めることお勧めします。
注 Windows Phone 8.1 以降では、大きいタイルは電話でサポートされていません。
この例では、ワイド通知に使ったテキスト文字列と同じ文字列を使って、テキストのみの普通サイズの通知を定義しています。
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));
次に、普通サイズ タイルをワイド タイルのペイロードに追加します。普通サイズ タイルを squareTileXml ペイロードで定義する binding 要素を取得します。この binding 要素をワイド タイルの兄弟として追加します。
var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);
前の手順の結果として、次に示すように、XML ペイロードの 1 つの visual 要素の下に 2 つの binding 要素がある状態になります。
<tile>
<visual visual="2">
<binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
<image id="1" src="ms-appx:///images/redWide.png"/>
<text id="1">Hello World! My very own tile notification</text>
</binding>
<binding template="TileSquare150x150Text04" fallback="TileSquareText04">
<text id="1">Hello World! My very own tile notification</text>
</binding>
</visual>
</tile>
6. 指定した XML コンテンツに基づいて通知を作成する
var tileNotification = new notifications.TileNotification(tileXml);
7. 通知の有効期限を設定する
既定では、ローカル タイル通知とローカル バッジ通知には有効期限がなく、プッシュ通知、定期的な通知、スケジュールされた通知の有効期限は 3 日です。特にローカル タイル通知とローカル バッジ通知には、アプリにとって適切な有効期限を設定することをお勧めします。タイルのコンテンツは、意味がなくなっても保持されることがないようにする必要があります。この場合、通知は 10 分後に有効期限切れになり、タイルから削除されます。
var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);
8. 通知をアプリのタイルに送信する
notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
9. タイル通知を消去する (省略可能)
この例は、ローカル呼び出しを使ってタイル通知を消去する方法を示しています。コンテンツに期限がある場合は、タイル通知を明示的に消去するのではなく、通知に有効期限を設定することをお勧めします。以下のコード行は、アプリのタイルから現在の通知を消去します。
notifications.TileUpdateManager.createTileUpdaterForApplication().clear();
タイルの通知キューが有効になっており、キューに通知がある場合は、clear メソッドを呼び出すことでキューが空になります。
クラウドから通知を消去することはできません。clear メソッドのローカル呼び出しにより、通知のソースに関係なくタイルは消去されますが、定期的な通知とプッシュ通知に限り、タイルを新しいコンテンツに更新することができます。
要約と次のステップ
このクイック スタートでは、新しいコンテンツを定義し、通知を通じてアプリのタイルに送って、10 分後に削除しました。上記の手順 (テンプレートを選んで通知を送るまで) を次のコードにまとめました。ここでは、アプリのパッケージからの画像を使っています。
独自のサンプルでこのコードをテストするには、サンプルの UI のボタンによってトリガーされる関数内にこのコードを記述します。たとえば、default.html ファイル内にボタンを配置できます。必ず実際の画像の名前に置き換えてください。
var notifications = Windows.UI.Notifications;
var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);
var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));
var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));
var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);
var tileNotification = new notifications.TileNotification(tileXml);
var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);
notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
最初のタイルの更新を実行したので、通知キューを有効にしてタイルの機能を拡張できます。
このクイック スタートでは、ローカル通知としてタイルの更新を送りました。その他の通知配信の方法 (スケジュール、定期的、プッシュ) を調べることもできます。詳しくは、「通知の配信」をご覧ください。