アプリケーションにマイ連絡先のサポートを追加するAdding My People support to an application

マイ連絡先の機能を使うと、ユーザーは、アプリケーションから直接、連絡先をタスク バーにピン留めすることができます。これにより、いろいろな方法で操作できる新しい連絡先オブジェクトを作成できます。The My People feature allows users to pin contacts from an application directly to their taskbar, which creates a new contact object that they can interact with in several ways. この記事では、この機能のサポートを追加して、ユーザーがアプリから直接を連絡先をピン留めできるようにする方法を説明します。This article shows how you can add support for this feature, allowing users to pin contacts directly from your app. 連絡先をピン留めすると、マイ連絡先の共有通知など、ユーザーは新しい種類の操作を利用できるようになります。When contacts are pinned, new types of user interaction become available, such as My People sharing and notifications.

マイ連絡先のチャット

必要条件Requirements

概要Overview

アプリケーションでマイ連絡先の機能を使えるようにするには、3 つの手順を行う必要があります。There are three things you need to do to enable your application to use the My People feature:

  1. アプリケーション マニフェストで shareTarget アクティブ化コントラクトのサポートを宣言します。Declare support for the shareTarget activation contract in your application manifest.
  2. ユーザーがアプリを使用して共有できる連絡先の注釈を付けます。Annotate the contacts that the users can share to using your app.
  3. アプリケーションの複数インスタンスの同時実行をサポートします。Support multiple instances of your application running at the same time. ユーザーは、連絡先パネルでアプリケーションを使いながら、アプリケーションの通常版を操作できる必要があります。Users must be able to interact with a full version of your application while using it in a contact panel. ユーザーは複数の連絡先パネルを同時に使用することもできます。They may even use it in multiple contact panels at once. これをサポートするには、アプリケーションが複数のビューを同時に実行できる必要があります。To support this, your application needs to be able to run multiple views simultaneously. これを行う方法については、「"アプリの複数のビューの表示」の記事をご覧ください。To learn how to do this, see the article "show multiple views for an app".

これを行うと、アプリケーションは、注釈付きの連絡先のための、連絡先のパネルに表示されます。When you’ve done this, your application will appear in the contact panel for annotated contacts.

コントラクトのサポートを宣言するDeclaring support for the contract

マイ連絡先のコントラクトのサポートを宣言するには、Visual Studio でアプリケーションを開きます。To declare support for the My People contract, open your application in Visual Studio. ソリューション エクスプローラーPackage.appxmanifest を右クリックして、 [プログラムから開く] を選択します。From the Solution Explorer, right click Package.appxmanifest and select Open With. メニューをから [XML (テキスト) エディター] を選び、 [OK] をクリックします。From the menu, select XML (Text) Editor) and click OK. マニフェストを次のように変更します。Make the following changes to the manifest:

変更前Before

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

    <Applications>
        <Application Id="MyApp"
          Executable="$targetnametoken$.exe"
          EntryPoint="My.App">
        </Application>
    </Applications>

変更後After

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

    <Applications>
        <Application Id="MyApp"
          Executable="$targetnametoken$.exe"
          EntryPoint="My.App">
          <Extensions>
            <uap4:Extension Category="windows.contactPanel" />
          </Extensions>
        </Application>
    </Applications>

この追加により、アプリケーションは windows.ContactPanel コントラクトから起動できるようになります。これにより、連絡先パネルで操作できるようになります。With this addition, your application can now be launched through the windows.ContactPanel contract, which allows you to interact with contact panels.

連絡先に注釈を付けるAnnotating contacts

アプリケーションの連絡先がタスク バーからマイ連絡先ウィンドウに表示されるようにするには、連絡先を Windows 連絡先ストアに書き込む必要があります。To allow contacts from your application to appear in the taskbar via the My People pane, you need to write them to the Windows contact store. 連絡先を書き込む方法については、「連絡先カードのサンプル」をご覧ください。To learn how to write contacts, see the Contact Card sample.

さらにアプリケーションは、各連絡先に注釈を書き込む必要があります。Your application must also write an annotation to each contact. 注釈は、連絡先に関連付けられた、アプリケーションからのデータの一部です。Annotations are pieces of data from your application that are associated with a contact. 注釈は、必要なビューに対応する、アクティブ化可能なクラスを、ProviderProperties メンバーに含む必要があります。また ContactProfile 操作のサポートを宣言する必要があります。The annotation must contain the activatable class corresponding to your desired view in its ProviderProperties member, and declare support for the ContactProfile operation.

アプリが実行されている任意の時点で連絡先に注釈を付けることができますが、一般には、連絡先がWindows 連絡先ストアに追加されたらすぐに連絡先に注釈を付けるようにします。You can annotate contacts at any point while your app is running, but generally you should annotate contacts as soon as they are added to the Windows contact store.

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
    // Create a new contact annotation
    ContactAnnotation annotation = new ContactAnnotation();
    annotation.ContactId = myContact.Id;

    // Add appId and contact panel support to the annotation
    String appId = "MyApp_vqvv5s4y3scbg!App";
    annotation.ProviderProperties.Add("ContactPanelAppID", appId);
    annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

    // Save annotation to contact annotation list
    // Windows.ApplicationModel.Contacts.ContactAnnotationList 
    await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

“appId” はパッケージ ファミリ名の最後に ‘!’ とThe “appId” is the Package Family Name, followed by ‘!’ アクティブ化可能なクラス ID を付けたものです。and the activatable class ID. パッケージ ファミリー名を見つけるには、既定のエディターを使って Package.appxmanifest を開き、“Packaging” タブを検索します。ここで、"App"は、アプリケーションのスタートアップ ビューに対応する、アクティブ化可能なクラスです。To find your Package Family Name, open Package.appxmanifest using the default editor, and look in the “Packaging” tab. Here, “App” is the activatable class corresponding to the application startup view.

連絡先が新しい潜在的なユーザーを招待できるようにするAllow contacts to invite new potential users

既定では、アプリケーションは、具体的に注釈を付けた連絡先の連絡先パネルのみに表示されます。By default, your application will only appear in the contact panel for contacts that you have specifically annotated. これはアプリから操作を行えない連絡先との混同を避けるためです。This is to avoid confusion with contacts that can’t be interacted with through your app. アプリケーションが認識していない連絡先にもアプリケーションが表示されるようにする (たとえば、アカウントに連絡先を追加するようにユーザーを招待するためなど) には、マニフェストに以下を追加することができます。If you want your application to appear for contacts that your application doesn’t know about (to invite users to add that contact to their account, for instance), you can add the following to your manifest:

変更前Before

<Applications>
    <Application Id="MyApp"
      Executable="$targetnametoken$.exe"
      EntryPoint="My.App">
      <Extensions>
        <uap4:Extension Category="windows.contactPanel" />
      </Extensions>
    </Application>
</Applications>

変更後After

<Applications>
    <Application Id="MyApp"
      Executable="$targetnametoken$.exe"
      EntryPoint="My.App">
      <Extensions>
        <uap4:Extension Category="windows.contactPanel">
            <uap4:ContactPanel SupportsUnknownContacts="true" />
        </uap4:Extension>
      </Extensions>
    </Application>
</Applications>

この変更により、ユーザーがピン留めしたすべての連絡先で、利用可能なオプションとして、連絡先パネルにアプリケーションが表示されるようになります。With this change, your application will appear as an available option in the contact panel for all contacts that the user has pinned. 連絡先パネル コントラクトを使用してアプリケーションがアクティブ化されている場合には、連絡先はアプリケーションが認識しているものであるかどうかを確認する必要があります。When your application is activated using the contact panel contract, you should check to see if the contact is one your application knows about. アプリケーションが認識していない連絡先では、アプリの新しいユーザー エクスペリエンスを表示する必要があります。If not, you should show your app’s new user experience.

マイ連絡先の連絡先パネル

メール アプリでのサポートSupport for email apps

メール アプリを作成する場合、すべての連絡先に手動で注釈を付ける必要はありません。If you are writing an email app, you don’t need to annotate every contact manually. 連絡先ウィンドウおよび mailto: プロトコルのサポートを宣言すると、メール アドレスを持つユーザーで、アプリケーションが自動的に表示されます。If you declare support for the contact pane and for the mailto: protocol, your application will automatically appear for users with an email address.

連絡先パネルで実行するRunning in the contact panel

ユーザーの一部またはすべての連絡先パネルにアプリケーションが表示されたので、連絡先パネル コントラクトのアクティブ化の処理を行う必要があります。Now that your application appears in the contact panel for some or all users, you need to handle activation with the contact panel contract.

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

コントラクトを使ってアプリケーションがアクティブ化されると、ContactPanelActivatedEventArgs オブジェクトを受け取ります。When your application is activated with this contract, it will receive a ContactPanelActivatedEventArgs object. これには、アプリケーションが起動して操作する連絡先の ID と ContactPanel オブジェクトが含まれています。This contains the ID of the Contact that your application is trying to interact with on launch, and a ContactPanel object. この ContactPanel オブジェクトへの参照を保持する必要があります。これを使ってパネルを操作できます。You should keep a reference to this ContactPanel object, which will allow you to interact with the panel.

ContactPanel オブジェクトには 2 つのイベントがあります。アプリケーションはこのイベントをリッスンする必要があります。The ContactPanel object has two events your application should listen for:

  • LaunchFullAppRequested イベントは、フル アプリケーションが独自のウィンドウで起動するように要求する UI 要素をユーザーが呼び出したときに送信されます。The LaunchFullAppRequested event is sent when the user has invoked the UI element that requests that your full application be launched in its own window. アプリケーションは、それ自体を起動して、すべての必要なコンテキストを渡す必要があります。Your application is responsible for launching itself, passing along all necessary context. これは好みの方法を使って行うことができます (たとえば、プロトコル起動など)。You are free to do this however you’d like (for example, via protocol launch).
  • Closing イベントは、アプリケーションが閉じられようとするときに送信されます。これにより、コンテキストを保存することができます。The Closing event is sent when your application is about to be closed, allowing you to save any context.

ContactPanel オブジェクトを使うと、連絡先パネル ヘッダーの背景色を設定することもできます (設定されない場合、既定はシステムのテーマです)。またプログラムを使って連絡先パネルを閉じることもできます。The ContactPanel object also allows you to set the background color of the contact panel header (if not set, it will default to the system theme) and to programmatically close the contact panel.

通知バッジをサポートするSupporting notification badging

ユーザーに関連する新しい通知がアプリから届いたときに、タスク バーにピン留めされた連絡先にバッジを表示する場合は、トースト通知と表現力豊かなマイ連絡先の通知hint-people パラメーターを含める必要があります。If you want contacts pinned to the taskbar to be badged when new notifications arrive from your app that are related to that person, then you must include the hint-people parameter in your toast notifications and expressive My People notifications.

連絡先の通知でのバッジの表示

連絡先にバッジを表示するには、トップ レベルのトースト ノードに hint-people パラメーターを含めて、送信連絡先を指定する必要があります。To badge a contact, the top-level toast node must include the hint-people parameter to indicate the sending or related contact. このパラメーターには次の値を指定できます。This parameter can have any of the following values:

  • 電子メール アドレスEmail address
  • 電話番号Telephone number
    • 例:E.g. tel:888-888-8888tel:888-888-8888
  • リモート IDRemote ID
    • 例:E.g. remoteid:1234remoteid:1234

特定のユーザーに関連するトースト通知を識別する方法の例を次に示します。Here is an example of how to identify a toast notification is related to a specific person:

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

注意

ContactStore APIs を使ったアプリで StoredContact.RemoteId プロパティを使い、PC に保存されている連絡先とリモートに保存されている連絡先とを関連付ける場合、RemoteId プロパティの値は不変かつ一意であることが不可欠です。If your app uses the ContactStore APIs and uses the StoredContact.RemoteId property to link contacts stored on the PC with contacts stored remotely, it is essential that the value for the RemoteId property is both stable and unique. つまり、リモート ID は、PC にある他の連絡先 (他のアプリが所有する連絡先も含む) のリモート ID と決して競合しないよう、常に同じユーザー アカウントを一意に識別し、固有のタグを保持している必要があります。This means that the remote ID must consistently identify a single user account and should contain a unique tag to guarantee that it does not conflict with the remote IDs of other contacts on the PC, including contacts that are owned by other apps. アプリで使われるリモート ID の不変性と一意性に確証がない場合、このトピックの中で後述する RemoteIdHelper クラスを使うと、システムに追加するすべてのリモート ID にあらかじめ一意のタグを追加することができます。If the remote IDs used by your app are not guaranteed to be stable and unique, you can use the RemoteIdHelper class shown later in this topic in order to add a unique tag to all of your remote IDs before you add them to the system. または、RemoteId プロパティを一切使わない代わりに、カスタムの拡張プロパティを作成し、そこに連絡先のリモート ID を格納する方法もあります。Or you can choose to not use the RemoteId property at all and instead you create a custom extended property in which to store remote IDs for your contacts.

PinnedContactManager クラスThe PinnedContactManager class

PinnedContactManager は、タスク バーにピン留めされる連絡先を管理するために使用します。The PinnedContactManager is used to manage which contacts are pinned to the taskbar. このクラスを使うと、連絡先をピン留めしたり、連絡先のピン留めを外したり、連絡先がピン留めされているかどうかを判別したり、アプリケーションが実行されているシステムで特定のサーフェスへのピン留めがサポートされているかどうかを判別したりすることができます。This class lets you pin and unpin contacts, determine whether a contact is pinned, and determine if pinning on a particular surface is supported by the system your application is currently running on.

GetDefault メソッドを使って PinnedContactManager オブジェクトを取得できます。You can retrieve the PinnedContactManager object using the GetDefault method:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

連絡先をピン留めする、またはピン留めを外すPinning and unpinning contacts

作成した PinnedContactManager を使って、連絡先をピン留めしたり、ピン留めを外したりすることができます。You can now pin and unpin contacts using the PinnedContactManager you just created. RequestPinContactAsync および RequestUnpinContactAsync メソッドは、ユーザーに確認ダイアログを提供します。これらのメソッドは、アプリケーション シングルスレッド アパートメント (ASTA、または UI) から呼び出される必要があります。The RequestPinContactAsync and RequestUnpinContactAsync methods provide the user with confirmation dialogs, so they must be called from your Application Single-Threaded Apartment (ASTA, or UI) thread.

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

また、同時に複数の連絡先をピン留めすることもできます。You can also pin multiple contacts at the same time:

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

注意

現時点では、連絡先のピン留めを外すバッチ操作はありません。There is currently no batch operation for unpinning contacts.

注:Note:

関連項目See also