Поделиться через


Пакет SDK центров уведомлений Azure для JavaScript

Центры уведомлений Azure предоставляют масштабируемую подсистему push-уведомлений, которая позволяет отправлять уведомления на любую платформу (Apple, Amazon Kindle, Firebase, Baidu, Xiaomi, Web, Windows и т. д.) из любой серверной части (облачной или локальной). Центры уведомлений хорошо подходят как для корпоративных, так и для потребительских сценариев. Ниже приведено несколько примеров сценариев:

  • отправка (с низкой задержкой) уведомлений об экстренных новостях миллионам пользователей;
  • отправка купонов целевым сегментам пользователей с учетом их местоположения;
  • отправка уведомлений о событиях пользователям или группам пользователей в информационных, спортивных, финансовых и игровых приложениях;
  • передача в приложения рекламного содержимого, которое помогает привлекать клиентов и продавать товары;
  • уведомление пользователей о корпоративных событиях, новостях и рабочих задачах;
  • отправка кодов для многофакторной идентификации.

Основные ссылки:

ПРИМЕЧАНИЕ. Если вы используете azure-sb пакет, см. раздел migration guide to move from azure-sb to @azure/notification-hubs

Начало работы

Поддерживаемые в настоящее время среды

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

Установка пакета

npm install @azure/notification-hubs

Предварительные требования

Create ресурса Центров уведомлений Azure

Центр уведомлений Azure можно создать с помощью следующих методов:

  1. Портал Azure
  2. Azure CLI
  3. Bicep
  4. Шаблон ARM

После создания центр уведомлений можно настроить с помощью портала Azure или Azure CLI.

Импорт клиента

Этот пакет SDK для JavaScript предлагает два способа взаимодействия с Центрами уведомлений Azure: с помощью подхода на основе классов или с помощью модульного проектирования. Подход на основе классов согласован во всех пакетах для создания клиента и последующего взаимодействия с методами на клиенте.

import {
  NotificationHubsClient,
  createAppleInstallation
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installation = createAppleInstallation({
  installationId: "<installation-id>",
  pushChannel: "<push-channel>",
  tags: ["likes_javascript"],
});

const result = await client.createOrUpdateInstallation(installation);

Модульный подход позволяет разработчику выбрать функции для импорта, так как каждый метод предоставляется по отдельности. Этот подход использует экспорт вложенных путей с ES-Modules для предоставления методов через прямой импорт. При использовании отдельных экспортов это повышает эффективность встряхивание деревьев и небольшие размеры пакетов, которыми разработчик может воспользоваться.

Обратите внимание, что создание клиента предоставляется через "@azure/notification-hubs/api" подпуть, а все методы клиента предоставляются через "@azure/notification-hubs/api" подпуть. Каждая экспортируемая функция принимает в client качестве первого параметра, а остальные параметры остаются без изменений.

Доступны следующие подпутьи:

  • @azure/notification-hubs/api— точка входа main для клиента с помощью createClientContext и клиентских методов, таких как getInstallation илиsendNotification
  • @azure/notification-hubs/models — Модели и фабричные методы Центров уведомлений.

Затем приведенный выше фрагмент кода будет следующим:

import { createClientContext, createOrUpdateInstallation } from "@azure/notification-hubs/api";
import { createAppleInstallation } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const installation = createAppleInstallation({
  installationId: "<installation-id>",
  pushChannel: "<push-channel>",
  tags: ["likes_javascript"],
});

const result = await createOrUpdateInstallation(context, installation);

Аутентификация клиента

Взаимодействие с Центром уведомлений Azure начинается с NotificationHubsClient , который поддерживает строки подключения подписанного URL-адреса. Сюда входят следующие уровни разрешений: Прослушивание, Управление, Отправка.

Прослушивание позволяет клиенту зарегистрировать себя через API регистрации и установки. Функция Send позволяет клиенту отправлять уведомления на устройства с помощью API отправки. Наконец, управление позволяет пользователю управлять регистрацией и установкой, например запросами.

NotificationHubsClient Новый клиент можно создать с помощью конструктора с строка подключения и именем центра уведомлений.

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

При использовании модульного подхода createClientContext можно импортировать через "@azure/notification-hubs/api" подпуть.

import { createClientContext } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

Основные понятия

После инициализации NotificationHubClient можно изучить следующие понятия.

  • Управление устройствами с помощью установок и описаний регистрации
  • Отправка уведомлений на устройства

Управление устройствами

Управление устройствами — это основная концепция Центров уведомлений, которая позволяет хранить уникальный идентификатор из собственной службы уведомлений платформы (PNS), такой как APN или Firebase, и связанные метаданные, такие как теги, используемые для отправки push-уведомлений аудитории. Это делается с помощью двух API: API установки, который является более новым и предпочтительным механизмом, и регистраций.

API установки

Установки — это более новый и собственный подход JSON к управлению устройствами, который содержит дополнительные свойства, такие как идентификатор установки и идентификатор пользователя, которые можно использовать для отправки аудитории. API установки имеет ряд преимуществ по сравнению с существующими API регистрации следующими способами:

  • Полностью идемпотентный API, который вызывает create при установке, поэтому операция может быть повторна, не беспокоясь о дублировании.
  • userId Поддержка свойств и installationId , которые затем можно использовать в выражениях тегов, таких как $InstallationId:{myInstallId} и $UserId:{bob@contoso.com}.
  • Шаблоны теперь являются частью установки, а не отдельной регистрации и могут ссылаться по имени в качестве тега для отправки.
  • Частичные обновления поддерживаются стандартом исправлений JSON, который позволяет добавлять теги и изменять другие данные без предварительного запроса установки.

Установки можно создать с createOrUpdateInstallation помощью следующего метода:

import { NotificationHubsClient, createAppleInstallation } from "@azure/notification-hubs";
import { v4 as uuid } from "uuid";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

// Create an installation for APNs
let installation = createAppleInstallation({
  installationId: uuid(), // Must be unique
  pushChannel: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0", // PNS specific handle
  tags: ["likes_hockey", "likes_football"],
});

installation = await client.createOrUpdateInstallation(installation);

При использовании модульного подхода код будет следующим:

import { createClientContext, createOrUpdateInstallation } from "@azure/notification-hubs/api";
import { createAppleInstallation } from "@azure/notification-hubs/models";
import { v4 as uuid } from "uuid";

const context = createClientContext("<connection string>", "<hub name>");

// Create an installation for APNs
let installation = createAppleInstallation({
  installationId: uuid(), // Must be unique
  pushChannel: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0", // PNS specific handle
  tags: ["likes_hockey", "likes_football"],
});

installation = await createOrUpdateInstallation(context, installation);

Обновление установки можно выполнить с помощью схемы исправления JSON, например путем добавления тега и идентификатора пользователя с помощью updateInstallation метода .

import { NotificationHubsClient, JsonPatch } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const updates: JsonPatch[] = [
  { op: "add", path: "/tags", value: "likes_baseball" },
  { op: "add", path: "/userId", value: "bob@contoso.com" },
];

const installation = await client.updateInstallation(installationId, updates);

При использовании модульного подхода код будет следующим:

import { createClientContext, updateInstallation } from "@azure/notification-hubs/api";
import { JsonPatch } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const updates: JsonPatch[] = [
  { op: "add", path: "/tags", value: "likes_baseball" },
  { op: "add", path: "/userId", value: "bob@contoso.com" },
];

const installation = await updateInstallation(context, installationId, updates);

Чтобы получить существующую установку getInstallation , используйте метод с существующим уникальным идентификатором установки.

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const installation = client.getInstallation(installationId);

При использовании модульного подхода код будет следующим:

import { createClientContext, getInstallation } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const installationId = "<unique installation ID>";

const installation = getInstallation(context, installationId);

API регистраций

Регистрация связана с PNS так же, как и при установке выше, с уникальным идентификатором устройства из PNS и связанными тегами. Регистрация шаблонов — это способ создания предварительно определенных шаблонов текста, которые затем можно настроить во время отправки с помощью свойств для заполнения сообщения. Дополнительные сведения о шаблонах см. в документации по шаблонам.

Установка может быть создана одним из двух способов: сначала путем получения идентификатора регистрации с сервера с помощью getInstallationId , а затем createOrUpdateRegistration или с помощью createRegistration метода .

import {
  NotificationHubsClient,
  createAppleRegistrationDescription,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

let registration = createAppleRegistrationDescription({
  deviceToken: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0",
  tags: ["likes_hockey", "likes_football"],
});

registration = await client.createRegistration(registration);

console.log(`New Registration ID: ${registration.registrationId}`);

При использовании модульного подхода код будет следующим:

import { createClientContext, createRegistration } from "@azure/notification-hubs/api";
import { createAppleRegistrationDescription } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

let registration = createAppleRegistrationDescription({
  deviceToken: "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0",
  tags: ["likes_hockey", "likes_football"],
});

registration = await createRegistration(context, registration);

console.log(`New Registration ID: ${registration.registrationId}`);

Обновления можно выполнить с помощью updateRegistration метода , но, в отличие от установок, не поддерживает добавочные обновления. Запрос существующей регистрации можно выполнить с помощью getRegistration метода .

import { NotificationHubsClient } from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const registrationId = "<unique Registration ID>";

let registration = await client.getRegistration(registrationId);

registration.tags.push("likes_sports");

registration = await client.updateRegistration(registration);

При использовании модульного подхода код будет следующим:

import {
  createClientContext,
  getRegistration,
  updateRegistration
} from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const registrationId = "<unique Registration ID>";

let registration = await getRegistration(context, registrationId);

registration.tags.push("likes_sports");

registration = await updateRegistration(context, registration);

Регистрации, в отличие от установок, можно запрашивать для получения всех регистраций, сопоставления регистраций с условием или по тегам. Регистрации можно запрашивать с помощью listRegistrationsметода , listRegistrationsByChannel и listRegistrationsByTag . Все методы поддерживают ограничение с помощью top параметра и поддерживают асинхронное разбиение по страницам.

import { NotificationHubsClient } from "@azure/notification-hubs/api";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const registrations = await client.listRegistrationsByTag("likes_hockey");

let page = 0;
for await (const pages of registrations.byPage()) {
  console.log(`Page number ${page++}`);
  for (const item of pages) {
    console.log(JSON.stringify(item, null, 2));
  }
}

При использовании модульного подхода код будет следующим:

import { createClientContext, listRegistrationsByTag } from "@azure/notification-hubs/api";

const context = createClientContext("<connection string>", "<hub name>");

const registrations = await listRegistrationsByTag(context, "likes_hockey");

let page = 0;
for await (const pages of registrations.byPage()) {
  console.log(`Page number ${page++}`);
  for (const item of pages) {
    console.log(JSON.stringify(item, null, 2));
  }
}

Операции отправки

Центры уведомлений поддерживают отправку уведомлений на устройства напрямую с помощью уникального предоставленного идентификатора PNS, использования тегов для отправки аудитории или общей трансляции на все устройства. С помощью номера SKU "Стандартный" и более поздних версий запланированная отправка позволяет пользователю планировать уведомления за семь дней до начала. Все операции отправки возвращают идентификатор отслеживания и идентификатор корреляции, которые можно использовать для обращений в службу поддержки Центров уведомлений. При использовании номера SKU "Стандартный" и выше также возвращается идентификатор уведомления, который можно использовать для получения данных телеметрии уведомлений с помощью getNotificationOutcomeDetails метода .

Для целей отладки можно задать true для параметра значение , enableTestSend которое получает немедленную обратную связь от PNS о sendNotification методе, однако не поддерживается в рабочих сценариях. Это не поддерживается в методах запланированной отправки.

Необработанные строки JSON или XML можно отправлять в методы отправки или запланированной отправки, а также использовать построители уведомлений, которые помогают создавать сообщения для каждой PNS, например APNs, Firebase, Baidu, ADM и WNS. Эти построители будут создавать собственный формат сообщений, поэтому невозможно угадать, какие поля доступны для каждой PNS.

// Using the class-based approach
import { createAppleNotificationBody } from "@azure/notification-hubs";

// Using the modular approach
import { createAppleNotification, createAppleNotificationBody } from "@azure/notification-hubs/models";

const apnsBody = createAppleNotificationBody({
  alert: {
    title: "Notification Title",
    subtitle: "Notification Subtitle",
    body: "Notification body goes here",
  },
  sound: "default",
  interruptionLevel: "time-sensitive",
});

// Send the message using the modular approach
const notification = createAppleNotification({
  body: apnsBody
})

const result = await sendNotification(context, notification);

Широковещательная отправка

Центры уведомлений можно использовать для отправки уведомлений на все зарегистрированные устройства для каждой платформы с помощью широковещательной отправки sendNotification с помощью метода .

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs/api";

const context = createClientContext(connectionString, hubName);

const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(message);

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

При использовании модульного подхода код будет следующим:

import { createClientContext, sendNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext(connectionString, hubName);

const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, message);

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

Прямая отправка

Чтобы отправить устройство напрямую, пользователь может выполнить отправку с помощью предоставленного платформой уникального идентификатора, например токена устройства APNs, вызвав sendNotification метод с параметром deviceHandle .

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient(connectionString, hubName);

const deviceHandle = "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(message, { deviceHandle });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

При использовании модульного подхода код будет следующим:

import { createClientContext, sendDirectNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext(connectionString, hubName);

const deviceHandle = "00fc13adff785122b4ad28809a3420982341241421348097878e577c991de8f0";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, message, { deviceHandle });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

Отправка аудитории

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

Если вы хотите создать выражение тега из массива тегов, существует построитель выражений тегов, доступный с createTagExpression методом , который предоставляется на верхнем уровне импорта или @azure/notification-hubs/models/tagExpressionBuilder модульного импорта, который создает выражение тега из тегов.

// Top level import
import { createTagExpression } from "@azure/notification-hubs";

// Modular import
import { createTagExpression } from "@azure/notification-hubs/models";

const tags = ["likes_football", "likes_hockey"];
const tagExpression = createTagExpression(tags);

console.log(tagExpression);
// likes_football||likes_hockey

Сообщения выражений тегов можно отправить с помощью следующего кода:

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const notification = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.sendNotification(notification, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

При использовании модульного подхода код будет следующим:

import { createClientContext, sendNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

const notification = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await sendNotification(context, notification, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Only available in Standard SKU and above
if (result.notificationId) {
  console.log(`Notification ID: ${result.notificationId}`);
}

Запланированная отправка

Push-уведомления можно запланировать за семь дней до пространств имен SKU "Стандартный" и более поздних версий с помощью scheduleBroadcastNotification метода для отправки на устройства с тегами или общей широковещательной рассылки. При этом возвращается идентификатор уведомления, который можно использовать для отмены при необходимости с помощью cancelScheduledNotification метода .

import {
  NotificationHubsClient,
  createAppleNotification,
} from "@azure/notification-hubs";

const client = new NotificationHubsClient("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

// Schedule 8 hours from now
const scheduledTime = new Date(Date.now() + (8 * 60 * 60 * 1000));

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await client.scheduleNotification(scheduledTime, message, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Can be used to cancel via the cancelScheduledSend method
console.log(`Notification ID: ${result.notificationId}`);

При использовании модульного подхода код будет следующим:

import { createClientContext, scheduleNotification } from "@azure/notification-hubs/api";
import { createAppleNotification } from "@azure/notification-hubs/models";

const context = createClientContext("<connection string>", "<hub name>");

const tagExpression = "likes_hockey && likes_football";
const messageBody = `{ "aps" : { "alert" : "Hello" } }`;

// Schedule 8 hours from now
const scheduledTime = new Date(Date.now() + (8 * 60 * 60 * 1000));

const message = createAppleNotification({
  body: messageBody,
  headers: {
    "apns-priority": "10",
    "apns-push-type": "alert",
  },
});

const result = await scheduleNotification(context, scheduledTime, message, { tagExpression });

console.log(`Tracking ID: ${result.trackingId}`);
console.log(`Correlation ID: ${result.correlationId}`);

// Can be used to cancel via the cancelScheduledSend method
console.log(`Notification ID: ${result.notificationId}`);

Устранение неполадок

Поддержка React Native

React Native в настоящее время не поддерживает [URLSearchParams], который используется пакетом SDK центров уведомлений Azure. Чтобы использовать пакет SDK в React Native, необходимо установить url-search-params-polyfill пакет и импортировать его перед использованием пакета SDK.

import 'url-search-params-polyfill';

Также необходимо предоставить polyfill для TextEncoder API и API асинхронного итератора. Дополнительные сведения см. в нашем примере React Native с expo.

Диагностика удаленных уведомлений

В Центрах уведомлений Azure содержится полное руководство по устранению неполадок с удаленными уведомлениями в руководстве По диагностике оповещений в Центрах уведомлений Azure.

Тестовая отправка поддерживается в методе sendNotification с параметром enableTestSend :

// Using the client
const result = await client.sendNotification(notification, { tags, enableTestSend: true });

// Using the modular approach
const result = await sendNotification(context, notification, { tags, enableTestSend: true });

Ведение журнала

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средству ведения журнала.

Дальнейшие действия

В следующих примерах показаны различные способы взаимодействия с Центрами уведомлений Azure.

Управление устройствами:

Операции отправки:

Операции управления:

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.

Тесты этого модуля представляют собой сочетание динамических и модульных тестов, для которых требуется экземпляр Центров уведомлений Azure. Чтобы выполнить тесты, необходимо выполнить следующее:

  1. rush update
  2. rush build -t @azure/notification-hubs
  3. Create ENV-файл со следующим содержимым в папке sdk\notificationhubs\notification-hubs :NOTIFICATIONHUBS_CONNECTION_STRING=connection string for your Notification Hubs instanceNOTIFICATION_HUB_NAME=Notification Hub name
  4. cd sdk\notificationhubs\notification-hubs
  5. rushx test.

Дополнительные сведения см. в папке тестов .

Просмотры