設定您的應用程式以接收目標式推播通知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. 例如,您可以使用目標式推播通知來促使客戶採取行動,像是為您的 App 評分或嘗試新功能。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. 您可以傳送數種不同類型的推播通知,包括快顯通知、磚通知及原始 XML 通知。You can send several different types of push notifications, including toast notifications, tile notifications, and raw XML notifications. 您也可以追蹤從您的推播通知產生的 App 啟動率。You can also track the rate of app launches that resulted from your push notifications. 如需有關此功能的詳細資訊,請參閱傳送推播通知給您 App 的客戶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. 在您的專案中,找出在啟動時執行的程式碼區段,您可以在其中登錄您的 App 以接收通知。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. 每次啟動您的 App 時,都應該呼叫此方法。This method should be called each time that your app is launched.

注意

在您呼叫 RegisterNotificationChannelAsync 方法時,會在 App 的本機應用程式資料存放區中建立名為 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). 此檔案包含目標式推播通知基礎結構所使用的識別碼。This file contains an ID that is used by the targeted push notifications infrastructure. 請確定您的 App 不會修改或刪除此檔案。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

當您的 app 呼叫 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.

如果啟動您的 App 的客戶在仍登入其 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. 這可能會產生非預期的結果,尤其是針對需要客戶登入才能使用服務的 App。This can have unintended consequences, particularly for apps that offer services that customers can sign in to use. 若要在本案例中防止其他使用者查看您的目標式通知,請在登出您的 app 時呼叫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.

當使用者啟動您的 App 時,App 會如何回應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. 如果您想要在使用者啟動您 App 時執行某個程式碼,您可以將該程式碼新增到您 App 中的這些進入點其中之一。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.

例如,您可能會想要針對已在您 App 中購買任何付費附加元件的 App 使用者提供免費的附加元件,來獎勵這些使用者。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. 接著,您可以在上面所列的其中一個進入點中,新增程式碼來給予他們免費的 App 內購買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.

此方法也會傳回您 App 的原始啟動引數。This method also returns the original launch arguments for your app. 當您選擇追蹤推播通知的應用程式啟動率時,不透明的追蹤識別碼會新增至啟動引數,以協助追蹤合作夥伴中心中的應用程式啟動。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 方法,這個方法會將追蹤識別碼傳送給合作夥伴中心、從啟動引數移除追蹤識別碼,然後將原始啟動引數傳回給您的程式碼。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:

  • 如果推播通知具有前景啟用類型,請從您 App 中的 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. 若要繼續將推播通知傳送給此 App,此 App 必須要求新通道。To resume sending push notifications to this app, the app must request a new channel.