連絡先のアクティビティを記録する

開始する前に、連絡先を Windows に提供します。

連絡先アクティビティを記録して、アプリケーション内のユーザーと連絡先の間の意味のあるやり取りを表すことができます。 連絡先アクティビティは、軽量な対話シグナルとして機能し、Windows が、計画された段階において People ウィジェット、共有シート、Windows 検索ボックスなどのユーザー関連のエクスペリエンス全体でユーザーが連絡先をどのように活用しているかを理解するのに役立ちます。

Note

現在、ContactAnnotationOperations リファレンスには、Activity値のWindowsまたは SDK バージョンは記載されていません。また、この記事では、現在どのエクスペリエンスで連絡先アクティビティを使用しているかについては説明していません。 リファレンスのバージョン履歴には、最新の文書化された値としてShare (Windows 10 バージョン 1703、SDK 15063) が一覧表示されます。 古い SDK バージョンを対象とするアプリの Activity に依存する前に、API リファレンスで更新内容を確認してください。

各アクティビティは、次の 3 つの重要な情報を記録します。

• 対象 — 対話に関わる連絡先
• 何 — 発生した相互作用の種類
• いつ — 相互作用が発生した時刻

連絡先アクティビティを記録するには、アプリケーションで連絡先に関連付けられた ContactAnnotation を作成し、 SupportedOperations を ContactAnnotationOperations.Activity に設定する必要があります。 Windows は、この操作の種類を持つ注釈を、その連絡先に関連付けられた対話シグナルとして解釈します。

各アクティビティは 1 つの相互作用イベントを表し、個別に記録する必要があります。 複数のコンタクトアクティビティを送信する場合は、インタラクションレコードを反復処理し、各イベントに対して TrySaveAnnotationAsync を呼び出します。 ループでは、バッチ API が提供されたり、同期のオーバーヘッドが削減されたりすることはありません。

連絡先アクティビティのペイロード

連絡先アクティビティを記録するには、ContactAnnotation で ProviderProperties["ActivityPayload"] を、対話を記述する JSON 文字列に設定します。

ペイロードには、次のプロパティを含める必要があります。

Property	Description
ActivityType	相互作用の種類を識別します。
ActivityTimestampUnix	相互作用が発生した時刻 。UTC Unix 時刻 (秒単位) で表されます。

キー ActivityPayload とペイロード プロパティ名 ActivityType および ActivityTimestampUnix を、表示どおり正確に使用します。 これらの名前は、アクティビティを記述するための文字列ベースのコントラクトを形成します。

サポートされている連絡先アクティビティの種類

ActivityType フィールドは、ユーザーとコンタクトの間で発生したやり取りを識別します。 Windowsは現在、次のアクティビティの種類をサポートしています。

アクティビティの種類	Description
message	連絡先とのメッセージの送受信。
call	音声通話またはビデオ通話の開始または応答。
email	電子メールの送受信。
meeting	連絡先が関係する会議への参加またはスケジュール。
share	連絡先とコンテンツを共有する。
social	ソーシャル エクスペリエンスを通じた連絡先との対話。
profileInteraction	連絡先のプロフィールを開くこと、またはその操作。

アプリケーションでは、アプリケーション内で発生したユーザーの対話を最もよく表すアクティビティの種類を選択する飛鳥があります。

連絡先とのアクティビティの記録の例

次の例は、メッセージングのやり取りをコンタクトアクティビティとして記録する方法を示しています。

long nowUnix = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

var payload = new
{
    ActivityType = "message",
    ActivityTimestampUnix = nowUnix
};

var annotation = new ContactAnnotation
{
    ContactId = contact.Id,
    RemoteId = contact.RemoteId,
    SupportedOperations = ContactAnnotationOperations.Activity
};

annotation.ProviderProperties["ActivityPayload"] =
    JsonSerializer.Serialize(payload);

bool saved = await this.contactAnnotationList.TrySaveAnnotationAsync(annotation);
if (!saved)
{
    // The annotation wasn't saved, so Windows didn't receive this activity.
    // Log the failure or retry later. Don't treat the interaction as recorded.
    System.Diagnostics.Debug.WriteLine(
        $"Failed to save contact activity for contact {contact.RemoteId}.");
}

TrySaveAnnotationAsync は注釈を保存できない場合 false 返します。そのため、アクティビティが記録されたと見なす前に結果を確認してください。 true結果は、アノテーションが保存されたことを意味します。 Windows が後でアクティビティをどのように処理するかは示されていません。

連絡先アクティビティのアクセス モデル

連絡先アクティビティは、アプリの観点から書き込み専用です。 アプリはアクティビティ レコードを送信できますが、Windowsは現在、以前に送信されたアクティビティ レコードの取得や明示的な削除をサポートしていません。 Windowsマネージド ライフサイクルのクリーンアップは、次のセクションで説明するように個別に行われます。

アプリで対話履歴を保持または管理する必要がある場合は、独自のストレージまたはバックエンド サービスに保存してください。

連絡先アクティビティのライフサイクル

連絡先アクティビティは、アプリケーションによって提供される RemoteIdを使用して連絡先に関連付けられます。

連絡先が削除された場合、または関連付けられている RemoteId が削除された場合、その連絡先にリンクされている連絡先アクティビティは自動的に削除されます。 同様に、アプリケーションがアンインストールされるか、関連付けられている UserDataAccount が削除されると、Windows は、そのアプリケーションによって記録された連絡先と連絡先アクティビティを自動的に削除します。

コンタクトアクティビティの処理と保持

連絡先アクティビティは、対話シグナルとして Windows によって処理されます。

連絡先アクティビティの保持期間、有効期限 (TTL)、集計、評価は、Windowsによって内部的に管理されます。 アプリケーションは、アクティビティの保存期間や送信後の処理方法を制御しません。

連絡先アクティビティは、本物のユーザー操作を表す必要があり、連絡先のランク付けや可視性に影響を与えることを目的として生成されるべきではありません。 Windowsは、内部プラットフォーム ロジックを使用して、これらのシグナルが人々関連のエクスペリエンスにどのように貢献するかを決定します。

関連するコンテンツ

• ContactAnnotation
• ContactAnnotationOperations
• ContactAnnotation.ProviderProperties
• ContactAnnotationList.TrySaveAnnotationAsync