C++ UWP アプリからのローカル トースト通知の送信

  • [アーティクル]

トースト通知は、ユーザーが現在アプリ内にいないときに、アプリで作成してユーザーに配信できるメッセージです。

トースト通知のスクリーンショット

このクイックスタートでは、リッチ コンテンツと対話型アクションを使用して、Windows 10またはWindows 11トースト通知を作成、配信、表示する手順について説明します。 このクイックスタートでは、実装する最もシンプルな通知であるローカル通知を使用します。 すべての種類のアプリ (WPF、UWP、WinForms、コンソール) で通知を送信できます。

重要

C++ の UWP ではないアプリを作成している場合は、C++ WRL のドキュメントを参照してください。 C# アプリを作成している場合は、C# のドキュメント を参照してください。

手順 1: NuGet パッケージのインストール

トースト通知は、Windows コミュニティ ツールキット (WCT) のビルダー構文または XML を使用して作成できます。 後者を使用する場合は、手順 2 にスキップし、ビルダーの構文を使用しないコード例を参照してください。

Visual Studio ソリューション内で、プロジェクトを右クリックし、[NuGet パッケージの管理] をクリックして、Microsoft.Toolkit.Uwp.NotificationsNuGet パッケージ バージョン 7.0 以上を検索してインストールします。

ビルダーの構文のコード例では、このパッケージを使用します。 このパッケージを使用すると、XML を使用せずにトースト通知を作成できます。

手順 2: 名前空間宣言を追加する

using namespace Microsoft::Toolkit::Uwp::Notifications;

手順 3: トーストを送信する

Windows 10とWindows 11では、トースト通知コンテンツはアダプティブ言語を使用して記述され、通知の外観を柔軟に変更できます。 詳細については、トースト コンテンツのドキュメントを参照してください。

まず、シンプルなテキストベースの通知から始めます。 (通知ライブラリを使用して) 通知のコンテンツを作成し、通知を表示します。 名前空間が Microsoft.Toolkit.Uwp.Notifications である点に注意してください。

単純なテキスト通知

WCT 通知ライブラリのビルダー構文を使用していない場合は、代わりに XML トースト テンプレートを作成してテキストと値を設定し、通知を作成して表示します。

// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)
    ->AddText("Andrew sent you a picture")
    ->AddText("Check this out, The Enchantments in Washington!")
    ->Show();

手順 4: アクティブ化を処理する

ユーザーが通知 (またはフォアグラウンド アクティブ化を使用した通知のボタン) をクリックすると、アプリの App.xaml.cppOnActivated が呼び出されます。

App.xaml.cpp

void App::OnActivated(IActivatedEventArgs^ e)
{
    // Handle notification activation
    if (e->Kind == ActivationKind::ToastNotification)
    {
        ToastNotificationActivatedEventArgs^ toastActivationArgs = (ToastNotificationActivatedEventArgs^)e;

        // Obtain the arguments from the notification
        ToastArguments^ args = ToastArguments::Parse(toastActivationArgs->Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        auto userInput = toastActivationArgs->UserInput;
 
        // TODO: Show the corresponding content
    }
}

重要

OnLaunched コードと同様に、フレームを初期化してウィンドウをアクティブ化する必要があります。 OnLaunched は、ユーザーがトーストをクリックしても呼び出されません。アプリが閉じられてから初めて起動している場合も同様です。 通常は、OnLaunched と OnActivated を組み合わせて独自の OnLaunchedOrActivated メソッドにまとめることをお勧めします。これは、両方で同じ初期化を実行する必要があるためです。

アクティブ化の詳細

通知をアクション可能にする最初の手順は、ユーザーが通知をクリックしたときに、アプリで起動する対象を認識できるように、いくつかの起動引数を通知に追加することです (この場合は、会話を開く必要があることを後で伝える情報を含めます。どの会話を開くかはわかっています)。

// Construct the content and show the toast!
(ref new ToastContentBuilder())

    // Arguments returned when user taps body of notification
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)

    ->AddText("Andrew sent you a picture")
    ->Show();

イメージの追加

通知には、リッチ コンテンツを追加できます。 ここでは、インライン画像とプロフィール (アプリ ロゴのオーバーライド) 画像を追加します。

注意

画像は、アプリのパッケージ、アプリのローカル ストレージ、または Web から使用できます。 Fall Creators Update の時点で、Web 画像の上限は通常の接続で 3 MB、従量制課金接続で 1 MB です。 まだ Fall Creators Update を実行していないデバイスでは、Web イメージは 200 KB を上限とします。

イメージを使用したトースト 
// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ...

    // Inline image
    ->AddInlineImage(ref new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    ->AddAppLogoOverride(ref new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop::Circle)
    
    ->Show();

ボタンと入力の追加

ボタンと入力を追加して通知を対話型にすることができます。 ボタンを使用すると、フォアグラウンド アプリ、プロトコル、またはバックグラウンド タスクを起動できます。 ここでは、返信テキスト ボックス、"いいね" ボタン、画像を開くための "表示" ボタンを追加します。

入力とボタンを含むトースト通知のスクリーンショット 
// Construct the content
(ref new ToastContentBuilder())
    ->AddArgument("conversationId", 9813)
    ...

    // Text box for replying
    ->AddInputTextBox("tbReply", "Type a response")

    // Buttons
    ->AddButton((ref new ToastButton())
        ->SetContent("Reply")
        ->AddArgument("action", "reply")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("Like")
        ->AddArgument("action", "like")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("View")
        ->AddArgument("action", "view"))
    
    ->Show();

フォアグラウンド ボタンのアクティブ化は、トーストの本体と同じ方法で処理されます (App.xaml.cpp OnActivated が呼び出されます)。

バックグラウンドのアクティブ化を処理する

トースト (またはトースト内のボタンで) でバックグラウンドのアクティブ化を指定すると、フォアグラウンド アプリがアクティブ化されるのではなく、バックグラウンド タスクが実行されます。

バックグラウンド タスクについて詳しくは、「バックグラウンド タスクによるアプリのサポート」をご覧ください。

ビルド 14393 以降を対象としている場合は、インプロセス バックグラウンド タスクを使用できます。これにより、処理が大幅に簡略化されます。 インプロセス バックグラウンド タスクは古いバージョンの Windows では実行できないことに注意してください。 次のコード サンプルでは、インプロセス バックグラウンド タスクを使います。

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

次に、App.xaml.cs で OnBackgroundActivated メソッドをオーバーライドします。 その後、フォアグラウンドのアクティブ化と同様に、事前定義済みの引数とユーザー入力を取得できます。

App.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();
 
    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                string arguments = details.Argument;
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }
 
    deferral.Complete();
}

有効期限を設定する

Windows 10 および 11 では、ユーザーが閉じるか無視したすべてのトースト通知はアクション センターに送られるため、ユーザーはポップアップが消えた後も通知を表示できます。

ただし、通知に含まれているメッセージが一定期間だけ関係する場合は、トースト通知に有効期限を設定して、アプリからユーザーに古い情報が表示されないようにする必要があります。 たとえば、12 時間限りのキャンペーンの場合は、有効期限を 12 時間に設定します。 以下のコードでは、有効期限が 2 日間に設定されています。

注意

ローカル トースト通知の既定の最長有効期限は 3 日間です。

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("Expires in 2 days...")
    ->Show(toast =>
    {
        toast->ExpirationTime = DateTime::Now->AddDays(2);
    });

トーストの主キーを提供する

送信した通知をプログラムで削除するか差し替える必要がある場合、Tag プロパティ (および必要に応じて Group プロパティ) を使って通知の主キーを提供する必要があります。 そうすると、今後この主キーを使って、通知の削除や差し替えができるようになります。

既に配信されたトースト通知の差し替えと削除の方法について詳しくは、「クイック スタート: アクション センターでのトースト通知の管理 (XAML)」をご覧ください。

Tag と Group を組み合わせると、復号主キーとして機能します。 Group はより汎用的な ID で、"wallPosts"、"messages"、"friendRequests" などのグループを割り当てることができます。Tag はグループ内から通知自体を一意に識別する必要があります。 汎用グループを使うことで、RemoveGroup API を使ってそのグループからすべての通知を削除できます。

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("New post on your wall!")
    ->Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

通知を消去する

独自の通知の削除と消去は、アプリで行う必要があります。 アプリを起動したときに、通知が自動的に消去されることはありません。

Windows では、ユーザーが明示的に通知をクリックした場合のみ、通知を自動的に削除します。

メッセージング アプリの処理の例を以下に示します。

  1. ユーザーが会話の中で新しいメッセージに関する複数のトーストを受け取る
  2. ユーザーがそれらのトーストのいずれかをタップして会話を開く
  3. アプリが会話を開き、その会話のすべてのトーストを消去する (その会話用にアプリが提供するグループで RemoveGroup を使う)
  4. ユーザーのアクション センターが通知の状態を正しく反映して、その会話の古い通知がアクション センターに残らないように処理する

すべての通知を消去する方法または特定の通知を削除する方法については、「クイック スタート: アクション センターでのトースト通知の管理 (XAML)」をご覧ください。

ToastNotificationManagerCompat::History->Clear();

リソース