`sendPushSubscription` send-push-subscription

Last update: Tue Dec 02 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

开发人员

AVAILABILITY

Web SDK的推送通知当前处于 测试版 中。功能和文档可能会发生更改。

sendPushSubscription命令向Adobe Experience Platform注册推送通知订阅。此命令处理从浏览器检索推送订阅详细信息并将它们发送到您配置的数据流。它在Web SDK版本2.29.0或更高版本中可用。

先决条件 prerequisites

在使用sendPushSubscription之前，请确保您拥有：

已配置推送通知：使用您的VAPID公钥设置pushNotifications配置属性
用户权限：用户必须已授予通知权限(Notification.permission === "granted")
服务工作进程：您的网站上必须有已注册的服务工作进程
推送管理器支持：浏览器必须支持推送通知并且具有PushManager API

调用Web SDK的配置实例时运行sendPushSubscription命令。确保在调用configure命令之前配置推送通知并调用sendPushSubscription命令。

alloy("sendPushSubscription")
  .then(() => {
    console.log("Push subscription recorded successfully");
  })
  .catch((error) => {
    console.error("Failed to send push subscription:", error);
  });

建议的执行频率 recommended-execution-frequency

为获得最佳的推送通知功能，Adobe建议每天执行sendPushSubscription命令一次。此频率可确保：

Adobe Experience Platform中的订阅详细信息保持最新
捕获对推送令牌或订阅状态所做的任何更改
用户的配置文件会与最新的推送通知首选项保持更新

您可以使用与以下方法类似的方法实施此方法：

// Check if subscription data was sent today
const lastSent = localStorage.getItem("alloy_push_last_sent");
const today = new Date().toDateString();

if (lastSent !== today) {
  alloy("sendPushSubscription").then(() => {
    localStorage.setItem("alloy_push_last_sent", today);
  });
}

工作原理 how-it-works

sendPushSubscription命令执行以下操作：

验证先决条件：验证是否已配置推送通知并授予用户权限
等待标识：等待用户的ECID可用
检索订阅：使用配置的VAPID密钥从Service Worker获取活动推送订阅
检查更改：将当前的订阅详细信息与缓存的值（ECID +订阅详细信息）进行比较。如果订阅详细信息未更改，该命令将记录一条信息消息并返回，而不发出网络请求
发送到数据流：如果检测到更改，则将订阅数据传输到您配置的Adobe Experience Platform数据流
更新缓存：存储新的订阅详细信息以供将来比较

错误处理 error-handling

常见错误情况及其消息：

错误

原因

"Push notifications module is not configured. No VAPID public key was provided."

pushNotifications配置缺失或无效

"Service workers are not supported in this browser."

浏览器不支持服务工作程序

"Push notifications are not supported in this browser."

浏览器不支持推送通知或通知API

"The user has not given permission to send push notifications."

用户尚未授予通知权限(Notification.permission === "granted")

"No service worker registration was found."

没有为当前源注册服务工作程序

"No VAPID public key was provided."

配置中缺少VAPID公钥

数据有效负载 data-payload

该命令会以下列格式发送推送通知数据：

{
  pushNotificationDetails: [
    {
      appID: "example.com", // Current domain
      token: "...", // Serialized subscription details + ECID
      platform: "web", // Always "web" for Web SDK
      denylisted: false, // Always false
      identity: {
        namespace: {
          code: "ECID",
        },
        id: "12345678901234567890", // User's ECID
      },
    },
  ],
}

使用Web SDK标记扩展注册推送订阅 register-push-subscription-tag-extension

等效于此字段的Web SDK标记扩展正在使用标记规则中的Send Push Subscription操作。

recommendation-more-help

1ae86b30-e55e-49c1-ab11-9d0356a5f3e1

sendPushSubscription send-push-subscription