クイック スタート: トースト通知の送信 (HTML)
[ この記事は、Windows ランタイム アプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]
注 JavaScript を使わない場合は、「クイック スタート: トースト通知の送信 (XAML)」をご覧ください。
トースト通知は、ユーザーが別のアプリ内、スタート画面、またはデスクトップ上 (Windows の場合) にいるときに、アプリがユーザーと対話できるようにするために画面に表示されるポップアップ UI です。このクイック スタートでは、トースト コンテンツの定義と表示の手順について説明します。 これらの操作をローカル通知を使って説明します。これは、最も簡単に実装できる通知です。次の手順について説明します。
- 通知のテンプレートを指定する
- テンプレートの空の XML コンテンツを取得する
- テキストを通知に追加する
- 画像を通知に追加する
- 通知の期間を指定する
- 通知と共に送信するオーディオを指定する
- アプリが通知によってアクティブ化されるときに使われるコンテキスト情報を提供する
- トーストをローカル通知として送信する
注 このクイック スタートでは、XML ドキュメント オブジェクト モデル (DOM) を使って通知コンテンツを直接操作します。XML コンテンツを Intellisense などのオブジェクト プロパティとして表示する、NotificationsExtensions ライブラリを使ったオプションのアプローチも利用できます。詳しくは、「クイックスタート: コードでの NotificationsExtensions ライブラリの使用」をご覧ください。NotificationsExtenstions を使って表されるこのクイック スタートのコードを確認するには、トースト通知のサンプルをご覧ください。
注 Microsoft Visual Studio を使ってトースト通知コード機能をテストしている場合は、Windows x86、x64、または Windows ランタイムのコンピューターで、ローカル コンピューターとリモート コンピューターのいずれかのデバッグ設定を使う必要があります。Visual Studio シミュレーターのデバッグ機能オプションは使用できません。コードはシミュレーターでコンパイルされ、実行されますが、トーストが表示されなくなります。
必要条件
このトピックを理解するための要件:
- トースト通知に関する用語と概念についての実用的知識。詳しくは、「トースト通知の概要」をご覧ください。
- トースト通知の送受信を行うには、アプリのマニフェストで [トースト対応] オプションを "true" (Visual Studio マニフェスト エディターでは "はい") に設定する必要があります。詳しくは、「トースト通知をオプトインする方法」をご覧ください。
- XML と、ドキュメント オブジェクト モデル (DOM) API を使った XML の操作に関する知識。
- トーストの XML スキーマに関する知識。詳しくは、「トースト スキーマ」をご覧ください。
- Windows ランタイム API を使って JavaScript で基本的な Windows ストア アプリを作成できること。詳しくは、「JavaScript を使った初めての Windows ストア アプリの作成」をご覧ください。
手順
1. 名前空間変数を宣言する (省略可能)
この手順では、名前空間の完全な名前の代わりに使う短い名前を用意します。C# の "using" ステートメント、または Visual Basic の "Imports" ステートメントと同等であり、コードを簡素化できます。
注 このクイック スタートの残りのコードでは、この変数が宣言されていることを前提としています。
var notifications = Windows.UI.Notifications;
2. トーストのテンプレートを選び、その XML コンテンツを取得する
システムによって提供されるテンプレート カタログから、コンテンツのニーズに適したテンプレートを選びます。テンプレートの全一覧については、ToastTemplateType 列挙型をご覧ください。送信する個別の各通知では異なるテンプレートを使うことができることに注意してください。
注 Windows Phone 8.1 では、toastText02 テンプレートのバリエーションのみがサポートされます。2 つの文字列を受け取り、1 つ目の文字列が太字で表示されます。両方が同じ行に表示されるので、連結されないようにするには、1 つだけの短い文字列か、2 つの非常に短い文字列を使います。
Windows で使うこの例では、toastImageAndText01 テンプレートを使います。このテンプレートは、1 つの画像と 1 つのテキスト文字列を必要とします。次に例を示します。
.png "ToastImageAndText01")
var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);
getTemplateContent メソッドは XmlDocument を返します。上のコードは、次の XML スケルトンを取得します。この XML スケルトンには、この後の手順で標準のドキュメント オブジェクト モデル (DOM) 機能を使って詳細を指定します。
<toast>
<visual>
<binding template="ToastImageAndText01">
<image id="1" src=""/>
<text id="1"></text>
</binding>
</visual>
</toast>
3. 通知のテキスト コンテンツを指定する
この例では、まず、"text" のタグ名があるテンプレート内のすべての要素を取得します。toastImageAndText01 テンプレートには、1 つのテキスト文字列だけが格納されます。これは、コードによって割り当てられます。この文字列は最大で 3 行に折り返される可能性があり、文字列の長さは切り詰められないように設定する必要があります。
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));
4. 通知の画像を指定する
このコードでは、まず、"image" のタグ名があるテンプレート内のすべての要素を取得します。toastImageAndText01 などのトースト テンプレートには 1 つの画像しか格納されません。すべてのトースト テンプレートに画像が格納されるわけではなく、テキストのみの場合もあることに注意してください。
var toastImageElements = toastXml.getElementsByTagName("image");
画像は、アプリのパッケージ、アプリのローカル ストレージ、または Web から使うことができます。この手順のバージョンは、イメージ ソースごとに表示されます。画像は 200 KB 未満かつ 1024 x 1024 ピクセル未満にする必要があります。詳しくは、「タイルとトーストの画像サイズ」をご覧ください。
次のコードでは、アプリのパッケージからのローカル画像が使われています。このタイプの画像は Visual Studio ソリューション ファイルに含まれており、アプリの一部としてパッケージ化されています。これらの画像には、"ms-appx:///" プレフィックスを使ってアクセスします。また、スクリーン リーダーなどのアクセシビリティのため、オプションの代替テキストを割り当てることをお勧めします。
重要 ここで使われる画像 "redWide.png" はただの例であり、Microsoft Visual Studio プロジェクトには含まれていません。このトーストを送信する前に、プロジェクトに追加した独自の実際のイメージの名前で "redWide.png" を置き換える必要があります。
toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");
次のコードでは、アプリのローカル ストレージからのローカル画像が使われています。このタイプの画像は、アプリによってそのローカル ストレージに保存されています。この場所は、Windows.Storage.ApplicationData.current.localFolder によって返されます。これらの画像には、"ms-appdata:///local/" プレフィックスを使ってアクセスします。ここでも、スクリーン リーダーなどのアクセシビリティのためにオプションの代替テキストを割り当てています。
toastImageElements[0].setAttribute("src", "ms-appdata:///local/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");
次のコードでは、Web 画像が使われています。これらの画像には、"http://" プロトコルを使って画像のパスを指定することでアクセスします。"https://" プロトコルを使うこともできます。
toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");
オプションの baseUri 属性を使って "https://www.microsoft.com/" などのルート パスを指定することもできます。これは、画像の src 属性に指定された相対 Uniform Resource Identifier (URI) と結合されます。この属性は、visual 要素 (通知全体に適用する場合) または binding 要素 (そのバインドに適用する場合) に設定できます。baseUri が両方に設定されている場合は、binding の値が visual の値より優先されます。
baseUri が "https://www.microsoft.com/" に設定されている場合、サンプル コード内の以下の行は
toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
次のように短縮できます。
toastImageElements[0].setAttribute("src", "redWide.png");
5. トーストの期間を指定する (省略可能)
必要に応じて、トーストの表示期間を設定できます。"short" (既定) と "long" という 2 つの値があります。"long" は、通知が着信呼び出しや予定のアラームなどのシナリオの一部である場合だけ使います。詳しくは、「トースト通知の概要」をご覧ください。
注 Windows Phone 8.1 では、異なる期間はサポートされていません。すべてのトーストの期間は同じです。電話トースト通知にこの属性が含まれている場合は無視されます。
注 既定の期間は "short" であるため、通常は、期間を "long" に設定する場合にのみこの属性を追加します。
var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");
6. トーストのオーディオを指定する (省略可能)
トーストのオーディオについて詳しくは、「トーストのオーディオ オプション カタログ」をご覧ください。
既定では、トーストが表示されるときに Windows によって短いサウンドが再生されます。必要に応じて、システムに用意されているサウンドの中から別のサウンドを指定することも、サウンドを再生しないようにすることもできます。Windows Phone 8.1 では、カスタム サウンドを指定できます。詳しくは、「トーストのオーディオ オプション カタログ」をご覧ください。
getTemplateContent を通じて取得されたテンプレートには audio 要素が含まれないため、開発者自身でこの要素を定義して XML ペイロードに追加する必要があります。サウンド ファイルは、"ms winsoundevent:" プレフィックスを使って指定します。または、Windows Phone 8.1 では、"ms-appx:///" または "ms-appdata:///" プレフィックスを使うパスで指定します。この例では、audio 要素を作り、その親となる toast 要素を選びます。
var toastNode = toastXml.selectSingleNode("/toast");
var audio = toastXml.createElement("audio");
この例では、既定ではないサウンドを指定します。
audio.setAttribute("src", "ms-winsoundevent:Notification.IM");
この例では、サウンドを再生しないことを指定します。
audio.setAttribute("silent", "true");
トースト通知が長い間表示される場合、サウンドを 1 回だけ再生するのではなくループ再生させることができます。オーディオのループが有効になるのは、長期間のトーストの場合だけです。ループで使うことができるサウンドは、システム指定のサウンド セット内に含まれています。この例では、ループするサウンドを指定します。
注 Windows Phone 8.1 では長期間トーストがサポートされていないため、ループするオーディオもサポートされません。
toastNode.setAttribute("duration", "long");
var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");
オーディオ要素を定義した後、次に示すように、その要素を toast 要素の子としてトーストの XML ペイロードにアタッチする必要があります。
toastNode.appendChild(audio);
7. アプリの起動パラメーターを指定する
ユーザーがトースト通知をクリックすると、アプリが起動し、通知のコンテンツに関連するビューが表示されることが想定されます。こうするには、トースト要素の launch 属性を使います。この属性は、トーストを通じてアプリが起動されたときに、トーストからアプリに渡される文字列を指定します。この文字列には特定の形式はなく、アプリで定義されます。アプリでは、アクティブ化されるたびにこの文字列を引数としてチェックし、その表示または処理を適宜調整する必要があります。
toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');
注 Windows Phone Silverlight 8.1 では、起動文字列の値が、既定の起動ページの URI に追加されます。たとえば、起動文字列 "?conversation=71" を指定すると、URI が /MainPage.xaml?conversation=71 になります。そのため、起動文字列も、有効なクエリ文字列である必要があります。そうでない場合は、例外がスローされます。
8. 指定した XML コンテンツに基づいてトースト通知を作成する
var toast = new notifications.ToastNotification(toastXml);
9. トースト通知を送信する
var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
toastNotifier.show(toast);
注 Windows Phone Silverlight 8.1 では、現在のフォア グラウンド アプリが ToastNotifier.Show メソッドの呼び出し元である場合はトーストが表示されません。その場合、トーストは、主にバック グラウンド エージェントが使用する必要があります。
注: トースト通知に適用される背景色は、アプリ マニフェストでそのアプリのタイル用に宣言されている背景色です。詳しくは、「クイック スタート: Visual Studio マニフェスト エディターを使用した既定のタイルの作成」をご覧ください。
要約と次のステップ
このクイック スタートでは、ローカル トースト通知をユーザーに送りました。
このクイック スタートでは、トーストをローカル通知として送信しました。これは実装が最も容易な通知タイプであり、結果をすぐに確認できます。次に、その他のトースト通知配信の方法 (スケジュールとプッシュ) を調べる必要があります。詳しくは、「通知の配信」をご覧ください。
関連トピック
サンプル
概念
手順
AppUserModelID を使ってデスクトップ トースト通知を有効にする方法
ベスト プラクティス
リファレンス