Dela via


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

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:

  1. Azure Portal
  2. Azure CLI
  3. Bicep
  4. ARM-mall

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 via createClientContext och klientmetoder som getInstallation eller sendNotification
  • @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 och installationId 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 listRegistrationsmetoden , 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:

Skicka åtgärder:

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:

  1. rush update
  2. rush build -t @azure/notification-hubs
  3. Skapa en .env-fil med följande innehåll i sdk\notificationhubs\notification-hubs mappen:NOTIFICATIONHUBS_CONNECTION_STRING=connection string for your Notification Hubs instanceNOTIFICATION_HUB_NAME=Notification Hub name
  4. cd sdk\notificationhubs\notification-hubs
  5. rushx test.

Mer information finns i testmappen .

Visningar