Настройка приложения для получения целевых push-уведомлений

  • Статья

Вы можете использовать страницу Push-уведомлений в Центре партнеров для прямого взаимодействия с клиентами, отправляя целевые push-уведомления на устройства, на которых установлено приложение универсальная платформа Windows (UWP). Например, можно использовать целевые push-уведомления для побуждения пользователей к определенным действиям, таким как выставление оценки вашему приложению или использование новой функции. Можно отправлять различные типы push-уведомлений, включая всплывающие уведомления, уведомления на плитках и необработанные уведомления XML. Также можно отслеживать количество запусков приложения, производимых из push-уведомлений. Дополнительные сведения об этой функции см. в разделе Отправка push-уведомлений пользователям вашего приложения.

Перед отправкой целевых push-уведомлений клиентам из Центра партнеров необходимо использовать метод класса StoreServicesEngagementManager в Microsoft Store Services SDK, чтобы зарегистрировать приложение для получения уведомлений. Вы можете использовать дополнительные методы этого класса, чтобы уведомить Центр партнеров о том, что приложение было запущено в ответ на целевое push-уведомление (если вы хотите отслеживать частоту запусков приложений, полученных из ваших уведомлений), и прекратить получение уведомлений.

Настройка проекта

Прежде чем писать код, выполните следующие действия, чтобы добавить ссылку на Microsoft Store Services SDK в свой проект.

  1. Если это еще не сделано, установите Microsoft Store Services SDK на компьютер разработки.
  2. Откройте проект в Visual Studio.
  3. В обозревателе решений щелкните правой кнопкой мыши узел Ссылки вашего проекта и выберите команду Добавить ссылку.
  4. В диалоговом окне Диспетчер ссылок разверните список Универсальная платформа Windows и выберите Расширения.
  5. В списке пакетов SDK установите флажок рядом с пунктом Microsoft Engagement Framework и нажмите кнопку ОК.

Регистрация для получения push-уведомлений

Чтобы зарегистрировать приложение для получения целевых push-уведомлений из Центра партнеров, выполните следующие действия.

  1. В своем проекте найдите раздел кода, выполняемого во время запуска, в котором можно зарегистрировать приложение для получения уведомлений.

  2. Добавьте в начало файла с кодом следующее выражение:

    using Microsoft.Services.Store.Engagement;

  3. Получите объект StoreServicesEngagementManager и вызовите один из перегруженных методов RegisterNotificationChannelAsync в коде запуска, определенном вами ранее. Этот метод следует вызывать каждый раз при запуске приложения.

  • Если вы хотите, чтобы Центр партнеров создавал собственный URI канала для уведомлений, вызовите перегрузку RegisterNotificationChannelAsync().

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

    Важно!

    Если ваше приложение также вызывает CreatePushNotificationChannelForApplicationAsync для создания канала уведомлений для WNS, убедитесь, что ваш код не вызывает CreatePushNotificationChannelForApplicationAsync и перегрузку RegisterNotificationChannelAsync() одновременно. Если необходимо вызвать оба этих метода, проследите за тем, чтобы они вызывались последовательно и дожидались возврата из одного метода перед вызовом второго.

  • Если вы хотите указать URI канала для целевых push-уведомлений из Центра партнеров, вызовите перегрузку RegisterNotificationChannelAsync(StoreServicesNotificationChannelParameters). Например, это может потребоваться, если ваше приложение уже использует службы push-уведомлений Windows (WNS) и вы хотите использовать один и тот же URI канала. Сначала необходимо создать объект StoreServicesNotificationChannelParameters и назначить свойство CustomNotificationChannelUri вашему универсальному коду ресурса (URI) канала.

    StoreServicesNotificationChannelParameters parameters =
    new StoreServicesNotificationChannelParameters();
parameters.CustomNotificationChannelUri = "Assign your channel URI here";

StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
await engagementManager.RegisterNotificationChannelAsync(parameters);

Примечание

При вызове метода RegisterNotificationChannelAsync в локальном хранилище данных приложения создается файл с именем MicrosoftStoreEngagementSDKId.txt для вашего приложения (папка, возвращенная свойством ApplicationData.LocalFolder). Этот файл содержит идентификатор, используемый инфраструктурой целевых push уведомлений. Убедитесь, что ваше приложение не изменило или не удалило этот файл. В противном случае ваши пользователи могут получать несколько экземпляров уведомлений, либо уведомления будут работать неправильно.

Передача целевых push-уведомлений пользователям

Когда ваше приложение вызывает метод RegisterNotificationChannelAsync, этот метод получает информацию об учетной записи Майкрософт того пользователя, который в данный момент вошел на устройство. Позже при отправке целевого push-уведомления сегменту, включающего этого клиента, Центр партнеров отправляет уведомление на устройства, связанные с учетной записью Майкрософт этого клиента.

Помните, что если пользователь, запустивший ваше приложение, передает свое устройство в пользование другому пользователю, то другой пользователь может увидеть уведомление, предназначенное первому пользователю, пока они находятся в системе под своими учетными записями Майкрософт. Это может привести к непредвиденным последствиям, особенно для приложений, предоставляющих услуги, которыми пользователь может воспользоваться, выполнив вход. В этом случае, чтобы запретить другим пользователям просматривать целевые уведомления, вызовите метод UnregisterNotificationChannelAsync, когда пользователи выйдут из вашего приложения. Дополнительные сведения см. далее в разделе Отмена регистрации для получения push-уведомлений этой статьи.

Реакция вашего приложения, когда его запускает пользователь

После регистрации приложения для получения уведомлений и отправки push-уведомлений клиентам приложения из Центра партнеров при запуске приложения в ответ на push-уведомление будет вызвана одна из следующих точек входа в приложении. Если у вас есть какой-либо код, который требуется выполнять, когда пользователь запускает ваше приложение, можно добавить этот код в одну из этих точек входа в приложении.

  • Если push-уведомление имеет тип активации переднего плана, переопределите метод OnActivated класса App в вашем проекте и добавьте свой код в этот метод.

  • Если push-уведомление имеет фоновый тип активации, добавьте свой код в метод Run для фоновой задачи.

Например, вы решите вознаграждать пользователей вашего приложения, которые приобрели какие-либо платные надстройки в приложении, путем предоставления им бесплатной надстройки. В этом случае можно отправлять push-уведомление определенному сегменту пользователей, нацеленное на этих пользователей. Затем можно добавить код, чтобы предоставить им право бесплатной покупки из приложения, в одну из перечисленных выше точек входа.

Уведомление Центра партнеров о запуске приложения

Если вы выбрали параметр Отслеживать частоту запуска приложения для целевого push-уведомления в Центре партнеров, вызовите метод ParseArgumentsAndTrackAppLaunch из соответствующей точки входа в приложении, чтобы уведомить Центр партнеров о том, что приложение было запущено в ответ на push-уведомление.

Этот метод также возвращает исходные аргументы запуска для приложения. При отслеживании частоты запуска приложения для push-уведомления к аргументам запуска добавляется непрозрачный идентификатор отслеживания, который помогает отслеживать запуск приложения в Центре партнеров. Аргументы запуска приложения необходимо передать методу ParseArgumentsAndTrackAppLaunch , и этот метод отправляет идентификатор отслеживания в Центр партнеров, удаляет идентификатор отслеживания из аргументов запуска и возвращает исходные аргументы запуска в код.

Способ вызова этого метода зависит от типа активации push-уведомления:

  • Если push-уведомление имеет тип активации переднего плана, вызовите этот метод из переопределения метода OnActivated в своем приложении и передайте аргументы, доступные в объекте ToastNotificationActivatedEventArgs, передаваемом этому методу. В следующем примере кода предполагается, что файл кода содержит инструкции using для пространств имен Microsoft.Services.Store.Engagement и Windows.ApplicationModel.Activation .

    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.
    }
}

  • Если push-уведомление имеет фоновый тип активации, вызовите этот метод из метода Run вашей фоновой задачи и передайте аргументы, доступные в объекте ToastNotificationActionTriggerDetail, передаваемом этому методу. В следующем примере кода предполагается, что ваш файл кода содержит операторы using для пространств имен Microsoft.Services.Store.Engagement, Windows.ApplicationModel.Background и Windows.UI.Notifications.

    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.
    }
}

Отмена регистрации для получения push-уведомлений

Если вы хотите, чтобы приложение перестало получать целевые push-уведомления из Центра партнеров, вызовите метод UnregisterNotificationChannelAsync .

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

Обратите внимание, что этот метод делает недействительным канал, который используется для уведомлений, поэтому приложение больше не будет получать push-уведомления ни от каких служб. После закрытия канала нельзя снова использовать для каких-либо служб, включая целевые push-уведомления из Центра партнеров и другие уведомления с помощью WNS. Чтобы возобновить отправку push-уведомлений для этого приложения, приложение должно будет запросить новый канал.