针对定向推送通知配置应用Configure your app for targeted push notifications

你可以使用合作伙伴中心的 " 推送通知 " 页,通过向安装了通用 WINDOWS 平台 (UWP) 应用的设备发送目标推送通知,直接与客户联系。You can use the Push notifications page in Partner Center to directly engage with customers by sending targeted push notifications to the devices on which your Universal Windows Platform (UWP) app is installed. 例如,可以使用定向推送通知鼓励客户采取行动(如为应用评分或试用新功能)。For example, you can use targeted push notifications to encourage your customers to take an action, such as rating your app or trying a new feature. 可以发送多个不同类型的推送通知,包括 Toast 通知、磁贴通知和 XML 原始通知。You can send several different types of push notifications, including toast notifications, tile notifications, and raw XML notifications. 还可以跟踪由推送通知导致的应用启动的速度。You can also track the rate of app launches that resulted from your push notifications. 有关此功能的详细信息,请参阅将推送通知发送到应用客户For more information about this feature, see Send push notifications to your app's customers.

你必须在 Microsoft Store Services SDK 中使用 StoreServicesEngagementManager 类的方法来注册你的应用以接收通知,然后才能将目标推送通知发送到合作伙伴中心的客户。Before you can send targeted push notifications to your customers from Partner Center, you must use a method of the StoreServicesEngagementManager class in the Microsoft Store Services SDK to register your app to receive notifications. 你可以使用此类的其他方法,通知合作伙伴中心,你的应用程序是为响应目标推送通知而启动的 (如果你想要跟踪通过通知) 生成的应用程序启动速率,并停止接收通知。You can use additional methods of this class to notify Partner Center that your app was launched in response to a targeted push notification (if you want to track the rate of app launches that resulted from your notifications) and to stop receiving notifications.

配置项目Configure your project

在编写任何代码之前,请遵循以下步骤在你的项目中添加对 Microsoft Store Services SDK 的引用:Before you write any code, follow these steps to add a reference to the Microsoft Store Services SDK in your project:

  1. 如果先前尚未这样做,请在开发计算机上安装 Microsoft Store Services SDKIf you have not done so already, Install the Microsoft Store Services SDK on your development computer.
  2. 在 Visual Studio 中打开项目。Open your project in Visual Studio.
  3. 在解决方案资源管理器中,右键单击项目的 " 引用 " 节点,然后单击 " 添加引用"。In Solution Explorer, right-click the References node for your project and click Add Reference.
  4. 引用管理器中,展开 " 通用 Windows ",然后单击 " 扩展"。In Reference Manager, expand Universal Windows and click Extensions.
  5. 在 Sdk 列表中,单击 " Microsoft Engagement 框架 " 旁边的复选框,然后单击 "确定"In the list of SDKs, click the check box next to Microsoft Engagement Framework and click OK.

注册推送通知Register for push notifications

注册应用以接收来自合作伙伴中心的目标推送通知:To register your app to receive targeted push notifications from Partner Center:

  1. 在项目中,找到启动过程中运行的代码部分,可以在其中注册用于接收通知的应用。In your project, locate a section of code that runs during startup in which you can register your app to receive notifications.

  2. 将以下语句添加到代码文件顶部。Add the following statement to the top of the code file.

    using Microsoft.Services.Store.Engagement;
    
  3. 在之前确定的启动代码中,获取 StoreServicesEngagementManager 对象,并调用其中一个 RegisterNotificationChannelAsync 重载。Get a StoreServicesEngagementManager object and call one of the RegisterNotificationChannelAsync overloads in the startup code you identified earlier. 每次启动应用时,都应该调用此方法。This method should be called each time that your app is launched.

备注

调用 RegisterNotificationChannelAsync 方法时,将会在本地应用数据存储器中为你的应用创建一个名为 MicrosoftStoreEngagementSDKId.txt 的文件(由 ApplicationData.LocalFolder 属性返回的文件夹)。When you call the RegisterNotificationChannelAsync method, a file named MicrosoftStoreEngagementSDKId.txt is created in the local app data store for your app (the folder returned by the ApplicationData.LocalFolder property). 此文件包含供定向推送通知基础结构使用的 ID。This file contains an ID that is used by the targeted push notifications infrastructure. 确保你的应用不会修改或删除此文件。Make sure that your app does not modify or delete this file. 否则,用户可能会收到多个通知实例,或者通知可能不会以其他方式正常运行。Otherwise, your users may receive multiple instances of notifications, or the notifications may not behave properly in other ways.

定向推送通知如何路由至客户How targeted push notifications are routed to customers

当你的应用调用 RegisterNotificationChannelAsync 时,此方法将会收集当前已登录到设备的客户的 Microsoft 帐户。When your app calls RegisterNotificationChannelAsync, this method collects the Microsoft account of the customer who is currently signed in to the device. 稍后,当你将目标推送通知发送到包含此客户的段时,合作伙伴中心会将通知发送到与此客户的 Microsoft 帐户关联的设备。Later, when you send a targeted push notification to a segment that includes this customer, Partner Center sends the notification to devices that are associated with this customer's Microsoft account.

请注意,如果客户已启动你的应用并在使用其 Microsoft 帐户登录到设备的状态下将设备交给其他人使用,请注意其他用户可能会看到面向最初客户的通知。If the customer who started your app gives their device to someone else to use while they are still signed in to the device with their Microsoft account, be aware that the other person may see the notification that was targeted at the original customer. 这可能会产生意外结果,尤其是对于那些提供客户可登录使用服务的应用。This can have unintended consequences, particularly for apps that offer services that customers can sign in to use. 若要在此情况下使其他用户无法看到定向通知,请在客户注销应用时调用 UnregisterNotificationChannelAsync 方法。To prevent other users from seeing your targeted notifications in this scenario, call the UnregisterNotificationChannelAsync method when customers sign out of your app. 有关详细信息,请参阅本文后面的注销推送通知For more information, see Unregister for push notifications later in this article.

应用在用户启动应用时如何响应How your app responds when the user launches your app

在注册应用以接收通知并将 推送通知发送到合作伙伴中心的应用客户后,当用户启动应用以响应推送通知时,将调用应用中的以下入口点之一。After your app is registered to receive notifications and you send a push notification to your app's customers from Partner Center, one of the following entry points in your app will be called when the user launches your app in response to your push notification. 如果有一些代码想要在用户启动应用时运行,可以将该代码添加到应用中的这些入口点之一。If you have some code that you want to run when the user launches your app, you can add the code to one of these entry points in your app.

  • 如果推送通知中含有前台激活类型,请覆盖项目中 App 类的 OnActivated 方法,然后向该方法中添加你的代码。If the push notification has a foreground activation type, override the OnActivated method of the App class in your project and add your code to this method.

  • 如果推送通知中含有后台激活类型,请将你的代码添加到后台任务Run 方法中。If the push notification has a background activation type, add your code to the Run method for your background task.

例如,你可能想要通过以下方式对在你的应用中购买过任何付费加载项的用户进行奖励:给予这些用户免费的加载项。For example, you might want to reward the users of your app that have purchased any paid add-ons in your app by granting them a free add-on. 在此情况下,可以将推送通知发送给面向这些用户的客户群In this case, you can send a push notification to a customer segment that targets these users. 然后,可以在上述所列的其中一个入口点中添加用于给予他们免费应用内购买的代码。Then, you can add code to grant them a free in-app purchase in one of the entry points listed above.

通知合作伙伴中心应用启动Notify Partner Center of your app launch

如果在合作伙伴中心为你的目标推送通知选择 " 跟踪应用启动速率 " 选项,请从应用中的相应入口点调用 ParseArgumentsAndTrackAppLaunch 方法,通知合作伙伴中心应用已启动,以响应推送通知。If you select the Track app launch rate option for your targeted push notification in Partner Center, call the ParseArgumentsAndTrackAppLaunch method from the appropriate entry point in your app to notify Partner Center that your app was launched in response to a push notification.

该方法还会返回应用的原始启动参数。This method also returns the original launch arguments for your app. 选择跟踪推送通知的应用启动速率时,会将不透明的跟踪 ID 添加到启动参数,以帮助跟踪合作伙伴中心的应用启动。When you choose to track the app launch rate for your push notification, an opaque tracking ID is added to the launch arguments to help track the app launch in Partner Center. 您必须将您的应用程序的启动自变量传递给 ParseArgumentsAndTrackAppLaunch 方法,此方法将跟踪 id 发送到合作伙伴中心,从启动参数中删除跟踪 id,并将原始启动参数返回到您的代码。You must pass the launch arguments for your app to the ParseArgumentsAndTrackAppLaunch method, and this method sends the tracking ID to Partner Center, removes the tracking ID from the launch arguments, and returns the original launch arguments to your code.

调用此方法的方式取决于推送通知的激活类型:The way you call this method depends on the activation type of the push notification:

  • 如果推送通知中含有前台激活类型,请从应用的 OnActivated 方法重写中调用此方法,然后传递在向此方法传递的 ToastNotificationActivatedEventArgs 对象中可用的参数。If the push notification has a foreground activation type, call this method from the OnActivated method override in your app and pass the arguments that are available in the ToastNotificationActivatedEventArgs object that is passed to this method. 以下代码示例假设你的代码文件中 Microsoft.Services.Store.EngagementWindows.ApplicationModel.Activation 命名空间具有 using 语句。The following code example assumes that your code file has using statements for the Microsoft.Services.Store.Engagement and Windows.ApplicationModel.Activation namespaces.

    protected override void OnActivated(IActivatedEventArgs args)
    {
        base.OnActivated(args);
    
        if (args is ToastNotificationActivatedEventArgs)
        {
            var toastActivationArgs = args as ToastNotificationActivatedEventArgs;
    
            StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
            string originalArgs = engagementManager.ParseArgumentsAndTrackAppLaunch(
                toastActivationArgs.Argument);
    
            // Use the originalArgs variable to access the original arguments
            // that were passed to the app.
        }
    }
    
  • 如果推送通知中含有后台激活类型,请从后台任务Run 方法中调用此方法,然后传递在向此方法传递的 ToastNotificationActionTriggerDetail 对象中可用的参数。If the push notification has a background activation type, call this method from the Run method for your background task and pass the arguments that are available in the ToastNotificationActionTriggerDetail object that is passed to this method. 以下代码示例假设你的代码文件中已有 Microsoft.Services.Store.EngagementWindows.ApplicationModel.BackgroundWindows.UI.Notifications 命名空间的 using 语句。The following code example assumes that your code file has using statements for the Microsoft.Services.Store.Engagement, Windows.ApplicationModel.Background, and Windows.UI.Notifications namespaces.

    public void Run(IBackgroundTaskInstance taskInstance)
    {
        var details = taskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
    
        if (details != null)
        {
            StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
            string originalArgs = engagementManager.ParseArgumentsAndTrackAppLaunch(details.Argument);
    
            // Use the originalArgs variable to access the original arguments
            // that were passed to the app.
        }
    }
    

注销推送通知Unregister for push notifications

如果希望应用停止接收来自合作伙伴中心的目标推送通知,请调用 UnregisterNotificationChannelAsync 方法。If you want your app to stop receiving targeted push notifications from Partner Center, call the UnregisterNotificationChannelAsync method.

StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
await engagementManager.UnregisterNotificationChannelAsync();

请注意,此方法会使用于通知的通道失效,因此该应用不再从任何服务接收推送通知。Note that this method invalidates the channel that is being used for notifications so the app no longer receives push notifications from any services. 关闭后,不能再对任何服务使用该通道,包括合作伙伴中心提供的目标推送通知以及使用 WNS 的其他通知。After it has been closed, the channel cannot be used again for any services, including targeted push notifications from Partner Center and other notifications using WNS. 若要恢复向此应用发送推送通知,该应用必须请求新的通道。To resume sending push notifications to this app, the app must request a new channel.