Пакет 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
Начало работы
Поддерживаемые в настоящее время среды
- LTS версии Node.js
- Последние версии Safari, Chrome, Edge и Firefox.
Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.
Установка пакета
npm install @azure/notification-hubs
Предварительные требования
Create ресурса Центров уведомлений Azure
Центр уведомлений Azure можно создать с помощью следующих методов:
После создания центр уведомлений можно настроить с помощью портала 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.
Управление устройствами:
- API установки
- API регистрации
Операции отправки:
- Широковещательная отправка
- Прямая отправка
- Отправка аудитории с помощью списка тегов
- Выражение "Отправка аудитории с тегом"
- Запланированная широковещательная отправка
- Запланированная отправка
Операции управления:
Участие
Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.
Тесты этого модуля представляют собой сочетание динамических и модульных тестов, для которых требуется экземпляр Центров уведомлений Azure. Чтобы выполнить тесты, необходимо выполнить следующее:
rush update
rush build -t @azure/notification-hubs
- Create ENV-файл со следующим содержимым в папке
sdk\notificationhubs\notification-hubs
:NOTIFICATIONHUBS_CONNECTION_STRING=connection string for your Notification Hubs instance
NOTIFICATION_HUB_NAME=Notification Hub name
cd sdk\notificationhubs\notification-hubs
rushx test
.
Дополнительные сведения см. в папке тестов .
Связанные проекты
Azure SDK for JavaScript