Azure Notification Hubs SDK för JavaScript
Azure Notification Hubs tillhandahåller en utskalad push-motor som gör att du kan skicka meddelanden till valfri plattform (Apple, Amazon Kindle, Firebase, Baidu, Xiaomi, Web, Windows osv.) från valfri serverdel (moln eller lokalt). Notification Hubs fungerar bra för både företags- och konsumentscenarier. Här följer några exempel:
- Skicka meddelanden med senaste nytt till miljontals användare med låg latens.
- Skicka platsbaserade kuponger till intresserade användarsegment.
- Skicka händelserelaterade meddelanden till användare eller grupper med media-/sport-/ekonomi-/spelprogram.
- Skicka innehåll med erbjudanden till program engagera och marknadsföra gentemot kunder.
- Meddela användare om företagshändelser, till exempel nya meddelanden och arbetsobjekt.
- Skicka koder för multifaktorautentisering.
Nyckellänkar:
Obs! Om du kommer från att använda azure-sb
paketet kan du läsa migration guide to move from azure-sb to @azure/notification-hubs
Komma igång
Miljöer som stöds för närvarande
- LTS-versioner av Node.js
- De senaste versionerna av Safari, Chrome, Edge och Firefox.
Mer information finns i vår supportprincip .
Installera paketet
npm install @azure/notification-hubs
Förutsättningar
Skapa en Azure Notification Hubs-resurs
Du kan skapa en Azure Notification Hub med följande metoder:
När meddelandehubben har skapats kan den konfigureras med hjälp av Azure-portalen eller Azure CLI.
Importera klienten
Detta SDK för JavaScript erbjuder två sätt att interagera med Azure Notification Hubs, antingen via den klassbaserade metoden eller med en modulär designmetod. Den klassbaserade metoden är konsekvent i alla paket för att skapa en klient och interagerar sedan med metoderna på klienten.
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);
Den modulära metoden gör att utvecklaren kan välja vilka funktioner som ska importeras eftersom varje metod exponeras individuellt. Den här metoden använder underökvägsexport med ES-Modules för att exponera metoderna via direktimport. Med de enskilda exporterna skapar detta en bättre trädskakningsupplevelse och mindre paketstorlekar som utvecklaren kan dra nytta av.
Observera att skapandet av en klient exponeras via "@azure/notification-hubs/api"
undersökvägen och att alla klientmetoder exponeras via "@azure/notification-hubs/api"
undersökvägen. Varje funktion som exporteras tar client
som den första parametern och resten av parametrarna förblir oförändrade.
Följande undersökvägar exponeras:
@azure/notification-hubs/api
– Huvudinmatningspunkten för klienten viacreateClientContext
och klientmetoder somgetInstallation
ellersendNotification
@azure/notification-hubs/models
– Notification Hubs-modeller och fabriksmetoder.
Kodfragmentet ovan blir sedan följande:
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);
Autentisera klienten
Interaktion med en Azure Notification Hub börjar med som NotificationHubsClient
stöder anslutningssträngar för signatur för delad åtkomst. Detta inkluderar följande behörighetsnivåer: Lyssna, Hantera, Skicka.
Lyssna gör att en klient kan registrera sig via API:et för registrering och installationer. Skicka tillåter att klienten skickar meddelanden till enheter med hjälp av skicka API:er. Slutligen tillåter Hantera användaren att utföra registrerings- och installationshantering, till exempel frågor.
En ny NotificationHubsClient
klient kan skapas med konstruktorn med namnet anslutningssträng och Notification Hub.
import { NotificationHubsClient } from "@azure/notification-hubs";
const client = new NotificationHubsClient("<connection string>", "<hub name>");
Med hjälp av den modulära metoden createClientContext
kan importeras via "@azure/notification-hubs/api"
undersökvägen.
import { createClientContext } from "@azure/notification-hubs/api";
const context = createClientContext("<connection string>", "<hub name>");
Viktiga begrepp
När har NotificationHubClient
initierats kan följande begrepp utforskas.
- Enhetshantering via Installationer och RegistreringDescriptions
- Skicka meddelanden till enheter
Enhetshantering
Enhetshantering är ett grundläggande begrepp för Notification Hubs för att kunna lagra den unika identifieraren från den interna PNS (Platform Notification Service), till exempel APNs eller Firebase, och tillhörande metadata, till exempel taggar som används för att skicka push-meddelanden till målgrupper. Detta görs med två API:er, installations-API:et som är den nyare och föredragna mekanismen och Registreringar.
Installations-API
Installationer är en nyare och inbyggd JSON-metod för enhetshantering som innehåller ytterligare egenskaper, till exempel ett installations-ID och användar-ID som kan användas för att skicka till målgrupper. Installations-API:et har några fördelar jämfört med befintliga registrerings-API:er på följande sätt:
- Fullständigt idempotent API så att du anropar skapa på installationen, så att en åtgärd kan göras om utan att du behöver oroa dig för dupliceringar.
- Stöd för
userId
ochinstallationId
egenskaper som sedan kan användas i tagguttryck som$InstallationId:{myInstallId}
och$UserId:{bob@contoso.com}
. - Mallar är nu en del av installationen i stället för en separat registrering och kan refereras efter namn som en tagg för att skicka.
- Partiella uppdateringar stöds via JSON Patch Standard, som gör det möjligt att lägga till taggar och ändra andra data utan att först behöva fråga installationen.
Installationer kan skapas via createOrUpdateInstallation
metoden, till exempel följande:
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);
Med hjälp av den modulära metoden skulle koden vara följande:
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);
En uppdatering av en installation kan göras via JSON Patch-schemat, till exempel genom att lägga till en tagg och ett användar-ID med hjälp av updateInstallation
metoden .
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);
Med hjälp av den modulära metoden skulle koden vara följande:
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);
Om du vill hämta en befintlig installation använder du getInstallation
metoden med ditt befintliga unika installations-ID.
import { NotificationHubsClient } from "@azure/notification-hubs";
const client = new NotificationHubsClient("<connection string>", "<hub name>");
const installationId = "<unique installation ID>";
const installation = client.getInstallation(installationId);
Med hjälp av den modulära metoden skulle koden vara följande:
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 för registreringar
En registrering är associerad med en PNS precis som installationen ovan, med den unika enhetsidentifieraren från PNS och associerade taggar. Mallregistreringar är ett sätt att skapa fördefinierade brödtextmallar som sedan kan anpassas vid sändningstid med egenskaper som ska fyllas i för meddelandet. Mer information om mallar finns i dokumentationen om mallar.
En installation kan skapas på ett av två sätt, först genom att hämta ett registrerings-ID från servern med och getInstallationId
sedan createOrUpdateRegistration
eller via createRegistration
-metoden.
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}`);
Med hjälp av den modulära metoden skulle koden vara följande:
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}`);
Uppdateringar kan göras via updateRegistration
metoden, men till skillnad från installationer stöder inte inkrementella uppdateringar. Du kan köra frågor om en befintlig registrering med getRegistration
metoden .
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);
Med hjälp av den modulära metoden skulle koden vara följande:
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);
Registreringar, till skillnad från installationer, kan efterfrågas för att hämta alla registreringar, matcha registreringar till ett villkor eller efter taggar. Registreringar kan efterfrågas med hjälp av listRegistrations
metoden , listRegistrationsByChannel
och listRegistrationsByTag
. Alla metoder stöder begränsning via top
alternativet och stöder asynkron växling.
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));
}
}
Med hjälp av den modulära metoden skulle koden vara följande:
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));
}
}
Skicka åtgärder
Notification Hubs stöder sändning av meddelanden till enheter antingen direkt med hjälp av den unika PNS-tillhandahållna identifieraren, med hjälp av taggar för målgruppssändning eller en allmän sändning till alla enheter. Med standard-SKU:n och senare tillåter schemalagd sändning att användaren schemalägger meddelanden upp till sju dagar i förväg. Alla sändningsåtgärder returnerar ett spårnings-ID och korrelations-ID som kan användas för Notification Hubs-supportärenden. Med standard-SKU:n och senare returneras också ett meddelande-ID som kan användas för att hämta meddelandetelemetri via getNotificationOutcomeDetails
metoden .
I felsökningssyfte enableTestSend
kan alternativen anges till true
vilka får omedelbar feedback från PNS om sendNotification
metoden, men stöds inte i produktionsscenarier. Detta stöds inte på de schemalagda sändningsmetoderna.
RåA JSON- eller XML-strängar kan skickas till sändningsmetoderna eller schemalagda sändningsmetoder, eller så kan meddelandeskaparna användas som hjälper till att konstruera meddelanden per PNS som APNs, Firebase, Baidu, ADM och WNS. Dessa byggare skapar det interna meddelandeformatet så det går inte att gissa vilka fält som är tillgängliga för varje 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);
Skicka sändning
Notification Hubs kan användas för att skicka meddelanden till alla registrerade enheter per plattform med hjälp av sändning sendNotification
via metoden .
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}`);
}
Med hjälp av den modulära metoden skulle koden vara följande:
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}`);
}
Skicka direkt
Om du vill skicka en enhet direkt kan användaren skicka med hjälp av den unika identifierare som tillhandahålls av plattformen, till exempel APNs-enhetstoken, genom att anropa sendNotification
metoden med en deviceHandle
parameter.
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}`);
}
Med den modulära metoden skulle koden vara följande:
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}`);
}
Skicka målgrupp
Förutom att rikta in sig på en enda enhet kan en användare rikta in sig på flera enheter med hjälp av taggar. Dessa taggar kan anges som en lista över taggar, som sedan skapar ett tagguttryck som matchar registrerade enheter, eller via ett tagguttryck som sedan kan använda boolesk logik för att rikta sig till rätt målgrupp. Mer information om taggar och taggar finns i Routning och tagguttryck.
Om du vill skapa ett tagguttryck från en matris med taggar finns det en Tag Expression Builder tillgänglig med createTagExpression
metoden som exponeras på den översta nivån för import eller @azure/notification-hubs/models/tagExpressionBuilder
modulär import som skapar ett "eller tagguttryck" från taggarna.
// 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
Tagguttrycksmeddelanden kan skickas med följande kod:
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}`);
}
Med den modulära metoden skulle koden vara följande:
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}`);
}
Schemalagd sändning
Push-meddelanden kan schemaläggas upp till sju dagar i förväg med Standard SKU-namnrymder och senare med hjälp av scheduleBroadcastNotification
metoden för att skicka till enheter med taggar eller en allmän sändning. Detta returnerar ett meddelande-ID som sedan kan användas för att avbryta vid behov via cancelScheduledNotification
metoden .
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}`);
Med den modulära metoden skulle koden vara följande:
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}`);
Felsökning
React Native support
React Native har för närvarande inte stöd för [URLSearchParams
] som används av Azure Notification Hubs SDK. För att kunna använda SDK:n i React Native måste du installera url-search-params-polyfill
paketet och importera det innan du använder SDK:n.
import 'url-search-params-polyfill';
Vi måste också tillhandahålla polyfill för API och api för TextEncoder
asynkron iterator. Mer information finns i vårt React Native exempel med Expo.
Diagnostisera borttagna meddelanden
Azure Notification Hubs har en fullständig guide för att felsöka problem med avbrutna meddelanden i guiden Diagnostisera borttagna meddelanden i Azure Notification Hubs.
Testsändning stöds i sendNotification
metoden med enableTestSend
alternativet :
// 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 });
Loggning
Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL
miljövariabeln till info
. Loggning kan också aktiveras vid körning genom att anropa setLogLevel
i @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokumentationen om @azure-/loggningspaket.
Nästa steg
Följande exempel visar de olika sätt som du kan interagera med Azure Notification Hubs:
Enhetshantering:
- Installations-API
- API för registrering
Skicka åtgärder:
- Skicka sändning
- Skicka direkt
- Målgruppssändning med tagglista
- Skicka målgrupp med tagguttryck
- Skicka schemalagd sändning
- Schemalagd sändning
Hanteringsåtgärder:
Bidra
Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.
Den här modulens tester är en blandning av live- och enhetstester som kräver att du har en Azure Notification Hubs-instans. Om du vill köra testerna måste du köra:
rush update
rush build -t @azure/notification-hubs
- Skapa en .env-fil med följande innehåll i
sdk\notificationhubs\notification-hubs
mappen:NOTIFICATIONHUBS_CONNECTION_STRING=connection string for your Notification Hubs instance
NOTIFICATION_HUB_NAME=Notification Hub name
cd sdk\notificationhubs\notification-hubs
rushx test
.
Mer information finns i testmappen .
Relaterade projekt
Azure SDK for JavaScript