App を Windows Timeline に対応させる 2/2

UWP App のTimeline 対応、実践編です。拙作のApp F10 image bbs browser で行った作業に即して説明してみます。

この記事は
App を Windows Timeline に対応させる 1/2
の続きです。

Windows Timeline 表示例

前準備

Fall Creators Update レベルのAPIを使うため、App のプロジェクト プロパティ→アプリケーションでMinVersionを 10.0.16299 にします。

必須では無いですが、このNuGetパッケージも追加します。後述するAdaptive Cards のJson 生成はこれが無いとやってられないです。

AdaptiveCards - NuGet Gallery

https://www.nuget.org/packages/AdaptiveCards/

※注意！！！ (Added 7 March 2018)
NuGet には上のものとは別に、"Microsoft.AdaptiveCards" が存在します。こちらは既に更新が終了しており、もう使われていません。ただ困ったことにGoogleで"NuGet AdaptiveCards" で検索するとこちらが表示されてしまうようです。気を付けてくださいね。

Microsoft.AdaptiveCards (Deprecated)
https://www.nuget.org/packages/Microsoft.AdaptiveCards/


UserActivity を生成するClassには以下二つのusingを追加します。

using Windows.ApplicationModel.UserActivities;
using AdaptiveCards;

User Activity の作成とOS への登録

前の記事でも触れましたが、App 上の作業の節目…ドキュメントを開いた時など…のタイミングでUserActivity を生成し、OSに登録します。OS はTimeline 上にこのUserActivity をタイルとして表示します。

UserActivity の作成と登録

	private async Task<bool> GenerateActivityAsync(FutaThreadView.PostsLoadFinishedEventArgs e)
	{
	UserActivityChannel channel = UserActivityChannel.GetDefault();
	UserActivity userActivity = await channel.GetOrCreateUserActivityAsync(e.Url);
	userActivity.ActivationUri = new Uri(e.Url.Replace("http://", "ddlgf10://") + "?View=Post");
	userActivity.VisualElements.DisplayText = e.Title + " " + GenerateCardSubTitle(e);
	var cardstring = GenerateCardJsonString(e);
	// To use the adaptive card, enable this line.
	// userActivity.VisualElements.Content = Windows.UI.Shell.AdaptiveCardBuilder.CreateAdaptiveCardFromJson(cardstring);
	await userActivity.SaveAsync();
	activitySession?.Dispose();
	activitySession = userActivity.CreateSession();
	return true;
	}

view raw Futalocation.xaml.cs hosted with ❤ by GitHub

基本、これだけでUserActivityの登録が可能です。ただこの例では Adaptive Cards を使っていないため、Timeline 上の表示は以下のように大変シンプルなものになります。実際には殆どの場合、これから説明するAdaptive Cards を使ってタイルの中身を組み立てていくことになるでしょう。

Adaptive Cards を使わない表示例

Adaptive Cards

詳しい説明は省きますが、Microsoft が考える通知カードの標準形といったところです。カードの中身…データのJSONスキームと、コンテナ…カードを表示するデバイスの能力を記述するスキームが分離してあるのが特徴でしょうか。
Microsoft のAdaptive Cards 紹介ページを見て頂くと感じが判るかと思います。

Weather Compact - AdaptiveCards Sample

画面の右ペインにコンボボックスがあり、ここから表示するコンテナを選択できます。共通のJSONデータに対して、各デバイス…Windows の通知トースト、タイル、Teams, FacebookにKik、そしておそらくは他プラットフォーム…で「大体」意味が伝わるように表示しますよ、という。

その各デバイスの中にWindows Timeline も並んでいます。触っていると、表現力は他のデバイスと比べてそれほど高くはないようです。また、入力系のようにそもそもTimeline の使用方法にそぐわないものもあります。

さて、F10 ではこのようなJSONを渡しています。以下のような背景画像付きのTileになります。

Adaptive Cards を使った例

	{
	"type": "AdaptiveCard",
	"version": "1.0",
	"backgroundImage": "http://i.4cdn.org/c/1515200423386.jpg",
	"body": [
	{
	"type": "TextBlock",
	"size": "large",
	"weight": "bolder",
	"text": "Megumin Thread #12",
	"wrap": true,
	"maxLines": 3
	},
	{
	"type": "TextBlock",
	"text": "Anime/Cute - 4chan",
	"wrap": true,
	"maxLines": 3
	}
	]
	}

view raw AdaptiveCard Sample hosted with ❤ by GitHub

このJSON文字列、素から文字列を足し合わせて気合で作っても良いのですが…上品に行うために 、「前準備」で触れた AdaptiveCards NuGet パッケージがあります。このパッケージ、別にUWP App用というわけでも無いので…Xamarin、その他 Desktop App等でも、.NET 環境でAdaptive Cards を作る場合は全部これでいけるはずです。

	private string GenerateCardJsonString(FutaThreadView.PostsLoadFinishedEventArgs e)
	{
	string retVal = "";
	string title = e.Title;
	string subTitle = GenerateCardSubTitle(e);
	AdaptiveCard card = new AdaptiveCard(new AdaptiveSchemaVersion(1, 0));
	card.BackgroundImage = new Uri(e.ThumbUrl);
	card.Type = "AdaptiveCard";
	card.Body.Add(new AdaptiveTextBlock() { Text = title, Size = AdaptiveTextSize.Large, Weight = AdaptiveTextWeight.Bolder, Wrap = true, MaxLines = 3 });
	card.Body.Add(new AdaptiveTextBlock() { Text = subTitle, Size = AdaptiveTextSize.Default, Weight = AdaptiveTextWeight.Default, Wrap = true, MaxLines = 3 });
	retVal = card.ToJson();
	return retVal;
	}

view raw Futalocation.xaml.cs hosted with ❤ by GitHub

これで、この一つ上で貼ったJSON文字列が生成されます。

Protocol Activation によるAppの起動・アクティベーション対応

ここは特にTimeline ユニークな話でもないので省略しますが、このような作業になります。

• Package.AppxManifest で自アプリのプロトコル名を登録する
• Appx.Xaml.cs にOnActivate を追加し、args.Kind == ActivationKind.Protocol だったらばパラメータを拾ってページを作る・または渡す

URI のアクティブ化の処理

注意など

• たまに、Timeline 上の表示が正しく行われない場合があります。特にこちらでAppのUserActivity 生成コードを弄った場合等に多いようです。この場合、一旦ログオフ→ログオンで元に戻る場合が多いです。
• 良くあるのは、作成したAdaptive Cards JSON文字列が不正で登録に失敗する場合です。この場合 userActivity.SaveAsync() で黙って落ち、特に例外が発生しないため大変分かりにくいです。 はまりがち。
• 上でも触れましたが、Timeline 上のAdaptive Card ではあまり凝った表現は出来ないようです。先にAdaptiveCards.io のテストサイトで表現が実現可能かどうか確認すると良いでしょう。
• Windows Timeline 上の画面からインクリメンタルサーチが可能ですが、ここで検索対象となるのはuserActivity.VisualElements.DisplayText と、Applicationの名前です。Adaptive Cards の中身は使われないようです。逆にAdaptive Cards を使用する場合 DisplayText は表示されませんので、ここに検索で拾ってほしいキーワードを追加しておくと良いです。