常见的上线活动故障排除方案 troubleshoot-mobile-live

在此页面上:​系统地诊断为什么您的Live活动无法显示、更新或结束,这样您就可以在单一和广播用例中解决用户档案令牌、活动配置、有效负荷和投放问题。

查找您的方案 find-your-scenario

症状或任务
从这里开始
实时活动未开始
方案1:配置文件和令牌,然后方案2:营销活动和有效负载
配置检查通过,但投放失败
场景3:投放失败
iOS单一实时活动开始,但不会更新或结束
方案4:更新令牌同步
Android实时活动开始,但不会更新或结束
方案2和方案3中的Android选项卡
检查单一请求的处理状态
方案5:执行状态API
广播未开始、更新或结束
方案6:广播配置
某些受众配置文件不会收到广播
场景7:受众成员资格和新鲜度
调查生产问题或历史投放
数据集查询

场景1:配置文件或推送令牌问题 scenario-1-profile-or-push-token-issues

[适用于单一和广播用例]{class="badge informative"}

触发器API接受请求,但不会显示实时活动。 常见原因:

  • Adobe Experience Platform中不存在配置文件。
  • 所需的推送令牌尚未同步到配置文件: iOS上的实时活动推送令牌或Android上的标准FCM注册令牌。
  • 推送令牌详细信息包含不正确的配置,例如错误的appId、平台或iOS attributeType。

对于广播:​示例几个受众配置文件以检查令牌注册。 在iOS上,配置文件令牌检查适用于远程启动事件,而不适用于基于渠道的更新或结束事件。 在Android上,同时使用方案6验证设备的FCM主题订阅。

验证配置文件是否存在

对于iOS和Android,请开始使用此检查。 对于广播,请对多个受众配置文件重复此操作。

  1. 在Journey Optimizer中,导航到​客户 > 配置文件。
  2. 使用API请求中的命名空间和身份值搜索。
  3. 如果找不到配置文件,则说明该配置文件不存在或摄取尚未完成。 在触发实时活动之前,可创建配置文件或等待摄取完成。
  4. 如果找到配置文件,请继续检查平台的令牌。

检查推送令牌

iOS

预检查

  • iOS应用程序要求:

    • iOS 16.1+
    • 在Info.plist中将NSSupportsLiveActivities设置为YES
    • ActivityAttributes已正确实施。
  • 移动SDK集成:

    • Adobe Experience Platform Mobile SDK (消息传送SDK 5.11.0+)
    • 使用Live活动推送令牌实施和调用了Messaging.registerLiveActivities。

调试步骤

accordion
​1. 检查实时活动推送令牌是否已同步

您可以使用Assurance验证令牌注册:

  1. 在Assurance中,从​ 事件 ​列表中,过滤或搜索事件eventType = "liveActivity.pushToStart"。
  2. 选择​ 事件 ​并检查有效负载。
  3. 检查token、appId和attributeType值是否存在。
  4. 确认事件已成功发送。

您还可以签入Adobe Experience Platform配置文件。

  1. 在Adobe Experience Platform中,从您的​ 配置文件 ​访问​ 事件 ​选项卡。
  2. 搜索liveActivity.pushToStart事件。
  3. 检查事件时间戳和有效负载。

如果未找到任何事件,则表示应用未正确调用Messaging.registerLiveActivities。 修复SDK集成。

accordion
​2. 验证配置文件上的令牌详细信息
  1. 从您的​配置文件,访问​ 属性 ​选项卡。

  2. 找到liveActivityPushNotificationDetails。

  3. 验证令牌配置:

    code language-json
    {
       "liveActivityPushNotificationDetails": [
       {
          "appId": "com.example.myapp",
          "token": "abc123def456...",
          "platform": "apns",
          "denylisted": false,
          "attributeType": "OrderTrackingAttributes",
          "identity": {}
       }
       ]
    }
    

验证每个字段:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
字段 要求 常见问题
appId 必须与iOS捆绑包标识符完全匹配 开发/生产捆绑包ID不匹配
attributeType 必须完全匹配Swift ActivityAttributes结构名称(区分大小写) 结构名称拼写错误或不正确
platform 必须为"apns"或"apnsSandbox" 平台值错误
denylisted 必须为false 令牌标记为无效或用户选择退出
token 有效的APN推送令牌 令牌已过期或重新安装应用程序

如果有任何字段不正确,请更新移动应用程序,使用Messaging.registerLiveActivities重新注册,等待5-10分钟,然后重新检查。

如果liveActivityPushNotificationDetails缺失,则表示该令牌尚未同步。 在Assurance中看到liveActivity.pushToStart事件后等待5-10分钟,然后重新检查。

Android

预检查

  • Android应用程序要求:

    • 在Android 16.1 (API级别36.1)或更高版本上运行应用程序,并将targetSdk设置为36。
    • 确保已授予POST_NOTIFICATIONS和POST_PROMOTED_NOTIFICATIONS权限。
    • 创建实时活动使用的通知渠道。
  • Mobile SDK集成:

    • 将Adobe Experience Platform Mobile SDK与消息传送和实时活动扩展相集成。
    • 使用MobileCore.setPushIdentifier(token)将FCM注册令牌转发到SDK。

调试步骤

accordion
​1. 验证FCM令牌注册

Android对实时活动使用标准FCM注册令牌。 没有liveActivity.pushToStart事件或单独的实时活动推送令牌。

  1. 在Assurance中,打开​ 事件 ​列表并找到标准推送令牌注册事件。
  2. 选择事件并检查其有效负载以验证FCM注册令牌是否存在。
  3. 确认注册事件已成功发送。
  4. 在Adobe Experience Platform中,打开配置文件的​ 属性 ​选项卡,并确认pushNotificationDetails中存在令牌,如步骤2中所述。

如果缺少注册事件或配置文件令牌,请验证应用程序是否使用MobileCore.setPushIdentifier(token)将FCM注册令牌转发到SDK。

accordion
​2. 验证配置文件上的令牌详细信息
  1. 从您的个人资料中,访问​ 属性 ​选项卡。

  2. 找到pushNotificationDetails。 Android使用此对象而不是liveActivityPushNotificationDetails,并且不需要attributeType字段。

  3. 验证令牌配置是否遵循此结构:

    code language-json
    {
       "pushNotificationDetails": [
          {
             "appId": "com.adobe.marketing.mobile.liveupdatessample",
             "token": "fcm-registration-token...",
             "platform": "fcm",
             "denylisted": false,
             "identity": {}
          }
       ]
    }
    

验证每个字段:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
字段 要求 常见问题
appId 必须与Android包名称完全匹配 开发和生产包名称不匹配
platform 必须为"fcm" 平台值错误
denylisted 必须为false 令牌标记为无效或用户选择退出
token 必须匹配设备的当前FCM注册令牌 令牌已过期或重新安装应用程序

如果有任何字段不正确,请根据需要更正应用程序配置,使用MobileCore.setPushIdentifier(token)再次转发FCM令牌,等待5-10分钟,然后重新检查配置文件。

如果pushNotificationDetails缺失,则表示该令牌尚未同步。 在Assurance中确认令牌注册后,等待5-10分钟,然后重新检查配置文件。

场景2:Campaign配置和有效负载问题 scenario-2-campaign-configuration-and-payload-issues

[适用于单一和广播用例]{class="badge informative"}

配置文件存在并具有有效令牌,但未显示实时活动。 可能的原因:

  • 错误的表面或渠道配置。
  • API有效负载结构不正确。
  • 有效负载字段与应用程序实现不匹配: iOS ActivityAttributes或Android样式提供程序映射。
  • timestamp过时(对于更新/结束至关重要)。

对于广播:​营销活动必须是​API触发的营销,而不是事务型营销。 有效负载使用audience,而不是recipients。 有关完整API规范,请参阅方案6和文档Adobe Developer。

iOS

预检查

  • 确认营销活动是​API触发的事务型 (单一)或​API触发的营销活动 (广播)。 保持​ 高吞吐量 ​已禁用,因为它与实时活动不兼容。
  • 在方案1中使用iOS检查验证配置文件是否存在及其令牌是否已同步。

调试步骤

accordion
​1. 验证营销活动表面配置
  1. 在Journey Optimizer中,打开您的​ 营销活动 ​并导航到​ 操作 ​菜单。
  2. 检查您的​实时活动配置。 必须为iOS应用配置表面,使其包标识符与您配置文件liveActivityPushNotificationDetails中的appId匹配。 例如,如果您的配置文件具有"appId": "com.example.myapp",则表面必须针对同一应用程序。
  3. 检查营销活动配置中的​ 活动类型 ​是否与用户档案的liveActivityPushNotificationDetails中的attributeType完全匹配。 例如,如果您的配置文件具有"attributeType": "FoodDeliveryLiveActivityAttributes",则营销活动必须指定此相同的活动类型。
accordion
​2. 验证API有效负荷结构

通过API执行活动时,请确保有效负载遵循正确结构。

单一有效负载:

code language-json
{
   "campaignId": "your-campaign-id",
   "recipients": [{
      "type": "aep",
      "userId": "user@example.com",
      "namespace": "email",
      "context": {
         "requestPayload": {
            "aps": {
               "content-available": 1,
               "timestamp": 1756984054,
               "event": "start",
               "attributes-type": "FoodDeliveryLiveActivityAttributes",
               "content-state": { ... },
               "attributes": { ... }
            }
         }
      }
   }]
}

常见有效负载问题:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3
字段 要求 常见问题
attributes-type 必须匹配促销活动类型和配置文件attributeType 不匹配或拼写错误
campaignId 必须匹配激活的营销活动ID 营销活动ID错误或缺失
content-available 必须为1 值缺失或错误
event 必须为"start"、"update"或"end" 事件类型无效
timestamp 必须始终为当前/最新Unix纪元时间(以秒为单位) 使用旧/缓存的时间戳
userId / namespace 必须匹配AEP中的现有配置文件 配置文件标识符不匹配

关键:始终使用新的时间戳

  • 在调用每个API时,将timestamp设置为当前的Unix纪元时间(以秒为单位)。 这适用于所有事件类型: start、update和end。
  • 过时或重复使用的时间戳会导致更新和结束请求失败或被设备忽略。 请​ 不 ​重复使用以前请求或缓存值中的时间戳。

可选字段(所有事件类型):

  • requestId:用于跟踪的唯一标识符(推荐)。
  • alert:通知的对象具有title和body。 对于提请注意更新非常有用。

关于dismissal-date:

  • 可选。 Unix纪元时间(秒)。 仅当event为"end"时才相关。
  • 指定何时从设备自动删除实时活动。 如果忽略此项,则实时活动将保持可见,直到用户将其取消为止。
  • 必须为晚于timestamp的未来时间戳。
accordion
​3. 将有效负载与iOS实施保持一致

确保API有效负载与iOS应用程序的ActivityAttributes实施相匹配。 Adobe SDK的LiveActivityAttributes协议扩展了iOS ActivityAttributes,并且需要liveActivityData属性。

验证映射:

  1. 您的ActivityAttributes必须实施Adobe的LiveActivityAttributes协议。 示例:

    code language-swift
    struct FoodDeliveryLiveActivityAttributes: LiveActivityAttributes {
       public struct ContentState: Codable, Hashable {
          var orderStatus: String
          var estimatedDeliveryTime: String
       }
    
       // Adobe SDK requirement
       var liveActivityData: LiveActivityData
    
       // Your custom attributes
       var restaurantName: String
    }
    

    请注意 liveActivityData字段是Adobe SDK的必需字段,必须包含在所有实现中。

  2. 您的API有效负载必须镜像iOS结构:

    code language-json
    {
       "aps": {
          "event": "start",
          "timestamp": 1756984054,
          "attributes-type": "FoodDeliveryLiveActivityAttributes",
          "content-state": {
             "orderStatus": "Preparing",
             "estimatedDeliveryTime": "20 mins"
          },
          "attributes": {
             "liveActivityData": {
                "liveActivityID": "order-12345"
             },
             "restaurantName": "Pizza Palace"
          }
       }
    }
    

验证核对清单:

  • 在content-state中包含所有ContentState字段(所有事件类型均需要该字段)。

  • 包括attributes中的所有LiveActivityAttributes字段(仅限开始事件),包括:

    • liveActivityData (必需;通常包含liveActivityID或类似的标识符)
    • 结构中的所有自定义字段
  • 完全匹配字段名称(区分大小写)。

  • 匹配数据类型(String、Int、Bool、嵌套对象)。

  • 保留嵌套的对象结构。

常见错误:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3
问题 影响 修复
属性中缺少liveActivityData 实时活动将不会启动 在开始事件中始终包含liveActivityData对象
开始事件中缺少必填字段 实时活动将不会启动 从iOS结构添加所有字段
字段名称错误(拼写错误/大小写) 字段被忽略或分析错误 完全匹配iOS字段名称
错误的数据类型 解析错误 匹配iOS数据类型
缺少嵌套对象 不完整数据 包括所有嵌套结构
更新/结束中包括attributes 不需要,但通常被忽略 在开始事件中仅包括attributes
更新/结束时的过期时间戳 设备忽略更新/结束 始终生成新的时间戳

有关更多示例,请参阅创建实时活动页面。

accordion
​4. 使用Assurance进行测试

使用Assurance验证API执行和有效负载投放:

  1. 打开Assurance会话。

  2. 执行API调用以触发实时活动。

  3. 在​ 事件列表 ​中,检查:

    • 营销活动执行事件。
    • 实时活动交付活动。
    • 有效负载验证错误事件。
  4. 查看事件负载以验证:

    • 已正确处理有效负载。
    • 未发生验证错误。
    • 实时活动已发送到APN。
Android

预检查

  • 确认营销活动是​API触发的事务型 (单一)或​API触发的营销活动 (广播)。 保持​ 高吞吐量 ​已禁用,因为它与实时活动不兼容。
  • 在方案1中使用Android检查验证配置文件是否存在以及其FCM令牌是否已同步。

调试步骤

accordion
​1. 验证营销活动表面配置
  1. 在Journey Optimizer中,打开您的​ 营销活动 ​并导航到​ 操作 ​菜单。
  2. 检查您的​实时活动配置。 该表面必须以包名称与配置文件pushNotificationDetails中的appId匹配的Android应用程序为目标。
  3. 验证表面是否为该应用程序使用FCM凭据。 配置文件的令牌平台必须为"fcm"。
  4. 确认有效负载中的notification_channel_id与应用创建的通知渠道匹配。
accordion
​2. 验证API有效负荷结构

将Android Live活动字段放置在context.requestPayload.fcm下。

单一启动有效负载:

code language-json
{
   "requestId": "your-request-id",
   "campaignId": "your-campaign-id",
   "recipients": [
      {
         "type": "aep",
         "userId": "your-device-ECID",
         "namespace": "ECID",
         "context": {
            "requestPayload": {
               "fcm": {
                  "notification_id": "flight-DL-321",
                  "timestamp": 1756984054,
                  "notification_channel_id": "live_updates_channel",
                  "priority": "PRIORITY_HIGH",
                  "event_type": "start",
                  "title": "Flight DL-321",
                  "body": "Boarding starts shortly",
                  "critical_text": "25 min",
                  "content_state": {
                     "custom_key_template_type": "progress",
                     "custom_key_journey_start": "DEL",
                     "custom_key_journey_progress": 10,
                     "custom_key_journey_end": "MUM"
                  }
               }
            }
         }
      }
   ]
}

将示例时间戳替换为当前Unix纪元时间(以秒为单位)。 content_state键是示例,必须与您应用程序的样式提供程序匹配。

对于广播,使用包含audience.id的API触发的营销活动,并将fcm对象放在context.requestPayload下。 将topic_name设置为目标设备订阅的FCM主题。 在开始、更新和结束事件中保持主题和notification_id不变。 请参阅Android广播有效负载示例。

常见有效负载问题:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3
字段 要求 常见问题
campaignId 必须匹配激活的营销活动ID 营销活动ID错误或缺失
notification_id 保留实时活动的开始、更新和结束事件的相同值 更改的ID针对其他通知
notification_channel_id 必须匹配由Android应用程序创建的渠道 缺少渠道或渠道不匹配
event_type 必须为"start"、"update"或"end" 生命周期事件无效
timestamp 纪元秒数;必须严格增加每个针对相同实例或广播主题的事件数 较旧或相等的时间戳将被忽略
content_state 使用应用程序样式提供程序支持的字段 不支持的键或不正确的值类型
userId / namespace 对于单一投放,请使用具有ECID命名空间的设备的ECID 配置文件标识符不匹配
topic_name 对于广播,请使用目标设备订阅的主题 不正确的主题或设备未订阅

时间戳和生命周期检查:

  • 对于每个开始、更新和结束事件,在epoch秒内使用新的timestamp。 请确保该值大于同一notification_id的上一个值(或者,大于广播的上一个值),即使同一秒内发出请求也是如此。topic_name
  • 较旧或相等的时间戳将被忽略。 请勿重用缓存的时间戳。
  • 可选的when字段控制通知的显示时间,而不是消息排序。 保持其合理的最新状态,并在纪元秒内将其表示。
  • 要更新或结束活动,请更改event_type,同时保留notification_id不变。 Android对所有三个生命周期事件使用相同的FCM注册令牌;无需单独的更新令牌。

结束事件解除:

对于event_type: "end",可以选择将dismiss_after设置为删除前已完成的实时活动应保持可见状态的秒数。 这是一个持续时间,而不是纪元时间戳。

accordion
​3. 将有效负载与Android实施保持一致

应用程序的样式提供程序确定content_state值在实时活动通知中的呈现方式。

  1. 确认应用程序中集成了Messaging和Live Activities扩展。
  2. 验证content_state中的每个字段是否与样式提供程序处理的键匹配,包括其预期值类型。
  3. 检查title、body和critical_text是否包含预期的显示文本。 critical_text用于状态栏芯片。
  4. 确认已授予通知权限,并且notification_channel_id标识的渠道存在。

常见错误:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
问题 影响 修复
不支持的content_state键或值类型 内容缺失或呈现不正确 匹配应用程序的样式提供程序映射
通知渠道缺失或不匹配 通知无法发布到预期渠道 创建渠道并使用其确切ID
未授予通知权限 实时活动可能无法按预期显示 验证POST_NOTIFICATIONS和POST_PROMOTED_NOTIFICATIONS权限
已更改notification_id 更新或结束未定向到原始通知 在整个生命周期中保持ID不变
早于或等于timestamp 已忽略事件 使用大于上次处理时间戳的值

有关更多示例,请参阅创建实时活动。

accordion
​4. 使用Assurance进行测试

在连接的Android测试设备上使用Assurance。

  1. 打开Assurance会话并确认FCM令牌注册可见。
  2. 执行API调用以启动实时活动,然后发送具有相同的notification_id且增加了时间戳的更新和结束事件。
  3. 查看可用的SDK事件和负载,了解处理或验证错误。 确认Android有效负载使用fcm以及预期的生命周期值。
  4. 在配置文件的​ 事件 ​选项卡中,检查匹配的message.feedback事件。 检查serviceProvider是否为fcm,并查看feedbackStatus、errorCode和errorMessage的投放失败情况。
  5. 如果投放成功但未呈现Live活动,请检查设备上的应用程序日志、样式提供程序映射、通知权限和渠道配置。

场景3:投放失败和错误分析 scenario-3-delivery-failures-and-error-analysis

[适用于单一和广播用例]{class="badge informative"}

在此方案中,所有先前的检查均已通过:

如果实时活动仍未出现、更新或结束,请检查活动处理、向推送提供商的投放(iOS上的APN或Android上的FCM)以及设备端行为。

对于广播:​报表显示所有受众成员的量度。 某些配置文件可能会成功,而其他配置文件则会失败。

检查营销活动报告 check-campaign-reports

对于iOS和Android,请从营销活动报表开始。 它显示Journey Optimizer是尝试发送、排除用户档案还是发生错误。

  1. 导航到您的​实时活动营销活动。

  2. 单击​ 报表 ​按钮。

  3. 选择​查看所有时间报表。

  4. 检查​ 发送统计数据 ​量度以了解发送成功:

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
    量度 它的含义 要查找的内容
    已定位 符合受众条件的配置文件数 应包含您的测试用户档案
    发送 尝试的推送通知总数 应与您的API调用匹配
    已送达 报告的投放量度 与发送进行比较;分别验证设备呈现
    发送错误 发送失败的推送通知 调查错误原因
    发送排除项 Adobe Journey Optimizer排除的用户档案 检查您的配置文件是否已被排除
  5. 如果​发送错误 > 0,请检查​ 错误原因 ​表。 使用适用于您的平台的选项卡中的步骤1来解释错误。

  6. 如果​发送排除项 > 0,请检查​ 排除的原因 ​表:

    table 0-row-3 1-row-3 2-row-3 3-row-3
    常见排除 含义 解决方法
    配置文件已选择退出 用户已选择退出通知 检查配置文件同意状态
    令牌 令牌标记为无效 重新注册令牌(iOS)或转发当前FCM令牌(Android),或检查阻止列表状态
    配置文件不符合条件 配置文件不符合营销活动标准 查看活动受众规则
  7. 查看​ 实时活动生命周期 ​部分:

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
    量度 检查内容
    远程启动 应显示API触发的开始计数
    更新 应显示更新事件计数
    结束 应显示结束事件计数
    总计计数 实时活动活动量总计

    如果这些指标为零或与您的API调用不匹配,请使用以下特定于平台的检查来调查活动处理和推送提供程序交付。

在实时活动营销活动报告页面中了解详情。

检查平台的投放

iOS

预检查

  • 已验证的以前方案:

    • 存在具有正确liveActivityPushNotificationDetails的配置文件。
    • 营销活动平面和活动类型正确。
    • API有效负载对当前时间戳有效。
    • 更新令牌已同步(仅限单一更新和结束事件)。
  • 已确认​API调用:

    • 触发器API接受了请求。 这不会确认投放或设备呈现。
    • 活动ID和收件人详细信息正确。

调试步骤

accordion
​1. 解释发送错误

如果营销活动报告未显示任何发送错误,请跳过此步骤。 否则,请将​ 错误原因 ​表中的错误与以下常见的APN错误进行匹配:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
常见错误 含义 解决方法
标记无效 推送令牌无效或已过期 从设备重新注册实时活动令牌
未找到标记 没有与配置文件关联的有效令牌 验证liveActivityPushNotificationDetails是否存在
已拒绝APN Apple推送通知服务拒绝了推送 检查APNs证书、捆绑包ID、环境
网络超时 无法访问APN 暂时性问题;重试API调用
accordion
​2. 查看用户档案中的消息反馈事件
  1. 在Journey Optimizer中导航到​客户 > 配置文件。

  2. 搜索并打开配置文件。

  3. 选择​ 事件 ​选项卡。

  4. 筛选或搜索具有eventType = "message.feedback"的事件。

  5. 查找与实时活动的liveActivityID和event类型匹配的反馈事件。

  6. 查看以下关键字段:

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
    字段 可能值 它的含义
    feedbackStatus sent, error, denylist 来自服务提供商的投放结果
    serviceProvider apns/apnsSandbox 应该是iOS Live活动的APN
    errorCode 数字代码或null APNs特定的错误代码(如果失败)
    errorMessage 错误描述或null 人工可读的错误消息
  7. 如果feedbackStatus: "error":

    • 检查errorCode和errorMessage中的特定APN错误。
    • 常见的APN错误包括令牌过期、证书无效、捆绑包ID错误。
  8. 如果未找到反馈事件:

    • 可能尚未尝试推送通知。
    • 检查营销活动报告中是否排除了该用户档案。

如果feedbackStatus是sent: Journey Optimizer已将通知传递给APN。 这不会确认设备呈现。 继续步骤4中的设备端检查。

accordion
​3. 在Assurance中验证向APN的实时活动投放
  1. 在API调用期间,打开您的Assurance会话并将其保持活动状态。

  2. 执行API调用(开始、更新或结束)。

  3. 在​ 活动列表 ​中,查找实时活动投放活动。

  4. 搜索与APNs推送投放相关的事件。

  5. 检查以下指示器:

    • 向APNs推送请求:确认Adobe已向Apple的服务器发送推送请求
    • APNs响应:显示APNs是接受还是拒绝推送
    • 投放状态:成功或失败指示
  6. 如果发现问题,请参阅以下常见的APN传送问题:

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
    问题 Assurance中的症状 解决方法
    APNs证书已过期 身份验证错误 续订并上传新的APNs证书
    错误的环境(开发环境与生产环境) 令牌不匹配错误 确保证书与应用程序生成类型匹配
    捆绑ID不匹配 捆绑包标识符无效 验证证书包ID是否与应用程序匹配
    令牌已过期 来自APN的InvalidToken错误 重新注册实时活动令牌
    限速 请求过多 降低API调用频率
accordion
​4. 检查设备端行为

如果Adobe显示已成功交付,但设备未显示实时活动:

  • 查看iOS设备日志以了解实时活动错误。
  • 验证应用程序是否处于前台或后台(未终止)。
  • 确认设备具有网络连接。
  • 在多个设备上测试以排除特定于设备的问题。
  • 验证iOS的版本是否为16.1或更高版本。
accordion
​5. 上报至Adobe支持

如果您已完成所有步骤,但问题仍未解决,请通过以下方式联系Adobe客户关怀团队:

必需的信息:

  • 营销活动 ID 和名称
  • 配置文件命名空间和ID
  • API有效负载中的liveActivityID
  • API调用时间戳
  • 显示发送统计数据、错误原因和排除原因的活动报告屏幕截图
  • 相关配置文件事件(liveActivity.updateToken表示单一更新/结束问题和message.feedback)
  • Assurance会话详细信息和相关活动屏幕截图
  • API请求有效负载和响应,并标记凭据和设备令牌
  • APNs证书详细信息(到期、环境、捆绑包ID)
Android

预检查

  • 已验证的以前方案:

    • 配置文件具有有效的pushNotificationDetails,包括当前的FCM令牌、Android包名称和platform: "fcm"。
    • Campaign表面定位正确的Android应用程序并使用匹配的FCM凭据。
    • 对于同一notification_id(或广播的topic_name),fcm有效负载有效并且其timestamp比上一个事件新。
    • 开始、更新和结束事件使用相同的notification_id。 单一事件使用相同的FCM注册令牌;不需要单独的更新令牌。
  • 已确认​API调用:

    • API调用返回了HTTP 202(已接受)。 这将确认接受请求,而不是交付或设备呈现。
    • 活动ID和收件人详细信息正确。 对于广播,请验证受众ID和FCM主题。

调试步骤

accordion
​1. 解释发送错误

如果营销活动报告未显示任何发送错误,请跳过此步骤。 否则,请将​ 错误原因 ​表中的错误与以下常见的FCM错误进行匹配:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
常见错误 含义 解决方法
无效/未注册的令牌 FCM令牌无效或应用程序已卸载 获取当前设备令牌并使用MobileCore.setPushIdentifier(token)转发它
未找到标记 没有有效的FCM令牌与配置文件关联 验证pushNotificationDetails是否包含当前令牌
发件人标识不匹配 已为其他Firebase项目颁发令牌 将FCM凭据与应用程序的Firebase项目对齐
参数无效 有效负载已被FCM拒绝 验证fcm有效负载结构
网络超时 无法访问FCM 暂时性问题;重试API调用
accordion
​2. 查看用户档案中的消息反馈事件
  1. 在Journey Optimizer中导航到​客户 > 配置文件。

  2. 搜索并打开配置文件。

  3. 选择​ 事件 ​选项卡。

  4. 筛选或搜索具有eventType = "message.feedback"的事件。

  5. 查找您正在调查的campaign和API调用时间戳的反馈事件。

  6. 查看以下关键字段:

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
    字段 可能值 它的含义
    feedbackStatus sent, error, denylist 来自服务提供商的投放结果
    serviceProvider fcm FCM处理的Android推送投放
    errorCode 提供程序错误代码或null 如果投放失败,则显示FCM特定的错误代码
    errorMessage 错误描述或null 人工可读的错误消息
  7. 如果feedbackStatus: "error":

    • 检查errorCode和errorMessage并应用步骤1中的相应FCM分辨率。
  8. 如果未找到反馈事件:

    • 可能尚未尝试推送通知或反馈可能尚不可用。
    • 检查营销活动报告中是否排除了该用户档案。

如果feedbackStatus是sent: FCM已接受通知。 这不会确认设备是否呈现了实时活动。 继续步骤4中的设备端检查。

accordion
​3. 在Assurance中检查FCM投放

在连接的Android测试设备上使用Assurance。

  1. 打开Assurance会话,并在API调用期间将其保持活动状态。
  2. 执行API调用并将event_type设置为start、update或end。
  3. 在​ 事件 ​列表中,检查对FCM的请求及其响应的可用推送传递事件。
  4. 检查FCM是接受还是拒绝请求,并检查任何报告的错误详细信息。
  5. 对于被拒绝的请求,请使用步骤1中的FCM错误检查令牌、Firebase项目凭据和有效负载。 如果提供程序事件在会话中不可用,请使用message.feedback事件和营销活动报告。
accordion
​4. 检查设备端行为

如果Adobe显示已成功交付,但设备没有显示或更新实时活动:

  • 检查Android应用程序日志中的推送处理和实时活动渲染错误。
  • 确认允许使用通知,并使用canPostPromotedNotifications()允许升级通知。
  • 验证是否授予POST_NOTIFICATIONS和POST_PROMOTED_NOTIFICATIONS权限,以及notification_channel_id标识的渠道是否存在。
  • 确保timestamp比上次处理的事件新,并且notification_id未发生更改。 对于广播,还要验证设备对topic_name的订阅。
  • 确认应用程序未强制停止。
  • 确认设备具有网络连接。
  • 在多个设备上测试以排除特定于设备的问题。
  • 验证设备是否运行Android 16.1 (API级别36.1)或更高版本,以及应用程序是否使用targetSdk 36。
  • 检查content_state键和值类型是否与应用程序的样式提供程序匹配。
accordion
​5. 上报至Adobe支持

如果您已完成所有步骤,但问题仍未解决,请通过以下方式联系Adobe客户关怀团队:

必需的信息:

  • 营销活动 ID 和名称
  • 配置文件命名空间和ID
  • API有效负载中的notification_id和event_type;对于广播,还包括topic_name和受众ID
  • API调用时间戳
  • 显示发送统计数据、错误原因和排除原因的活动报告屏幕截图
  • 相关配置文件message.feedback事件,包括FCM错误代码和消息
  • Assurance会话详细信息和相关活动屏幕截图
  • API请求有效负载和响应,并标记凭据和设备令牌
  • Android包名称、Firebase项目和发件人ID以及FCM凭据配置详细信息;不包括私钥
  • Android操作系统版本、设备型号、通知权限状态和相关应用程序日志

场景4:实时活动更新令牌未同步 scenario-4-live-activity-update-token-not-synced

[仅适用于单一用例]{class="badge informative"}

[仅适用于iOS]{class="badge positive"}

实时活动从设备开始,但接受的update或end API请求不会更新或取消它。 可能的原因是​ 每个实例的Live活动更新令牌 ​尚未同步到Adobe的系统。 完成以下检查以确认令牌同步是否是问题。

了解更新令牌

当在设备上启动实时活动时,iOS会为该特定实时活动实例生成一个唯一的更新令牌。 以下项需要此令牌:

  • 向实时活动发送更新
  • 远程结束实时活动

每个实时活动实例都有自己的唯一更新令牌。 Adobe需要此令牌来提供更新和结束事件。

预期行为

要使更新和结束事件正常工作,必须发生以下情况:

  1. 在设备上成功启动实时活动。
  2. 设备为该Live活动实例生成更新令牌。
  3. Mobile SDK可捕获更新令牌并将其发送到Adobe。
  4. 更新令牌已同步并存储在Adobe的系统中。
  5. 后续的更新/结束API调用使用此令牌进行交付。

预检查:

  • 用户权限:首次在设备上启动实时活动时,iOS会显示系统提示:“允许[应用程序名称]提供实时活动更新?” 用户​ 必须点按“允许” ​才能生成并同步更新令牌。 如果用户点按“不允许”,则不会创建任何更新令牌,并且更新/结束请求将失败。 这是每个应用程序的一次性权限。
  • 个人资料和营销活动验证:完成方案1和方案2检查,以确保个人资料、令牌和营销活动配置正确。

调试步骤

​1. 验证Assurance中的更新令牌同步
  1. 打开Assurance会话。

  2. 请确保会话在设备上启动实时活动时处于活动状态。

  3. 筛选或搜索具有eventType = "liveActivity.updateToken"的事件。

  4. 选择事件并检查有效负载:

    • 验证token字段是否包含有效的更新令牌字符串。
    • 检查liveActivityID是否与您的实时活动实例匹配。
    • 确认activityType与您的attributes-type匹配。
  5. 如果找不到事件:

    • SDK未生成或捕获更新令牌。
    • 检查用户是否授予了实时活动权限。
    • 验证是否已在设备上成功启动实时活动。
    • 确认移动设备SDK已正确集成以捕获更新令牌。
  6. 如果找到该事件,请继续执行步骤2。

​2. 验证配置文件事件中的更新令牌
  1. 在Journey Optimizer中导航到​客户 > 配置文件。

  2. 搜索并打开配置文件。

  3. 选择​ 事件 ​选项卡。

  4. 查找liveActivity.updateToken事件。

  5. 检查事件详细信息:

    • 验证时间戳是否为最近时间戳(与实时活动开始时间匹配)。
    • 确认token和liveActivityID存在。
    • 确保activityType正确。
  6. 如果在配置文件中未找到事件:

    • 可能尚未将更新令牌事件引入配置文件。
    • 等待5-10分钟,然后重新检查。
    • 如果15分钟后仍然缺失,则可能存在事件摄取问题。
  7. 如果找到该事件,则表示已同步更新令牌。 继续执行步骤3。

​3. 在Assurance中查看实时活动交付事件
  1. 在Assurance会话中,执行更新或结束API调用。

  2. 在​ 事件列表 ​中,查找实时活动投放事件(APNs推送事件)。

  3. 检查事件以指示:

    • 推送通知已发送到APN。
    • 来自APN的响应(成功或错误)。
    • 投放确认。
  4. 如果存在APNs投放事件:已发送推送通知。 如果设备仍未更新,则问题可能出在设备端(应用程序无法处理推送、网络问题等)。

  5. 如果缺少APNs投放事件:更新令牌可能未正确存储,或者未与Adobe系统中的用户档案关联。

  6. 如果存在错误事件:检查错误详细信息中的特定失败原因(无效令牌、APN被拒绝等)。

场景5:通过API检查执行状态 scenario-5-checking-execution-status-via-the-api

[仅适用于单一用例]{class="badge informative"}

触发单一实时活动后,GET消息执行API​返回执行的当前状态。 使用它确认执行是已排队、进行中、已完成还是失败,而无需等待反馈事件进入数据集。

executionId是触发器响应中返回的消息ID。 对于单一执行,它的前缀为HUOC-。

终结点和示例请求

终结点: GET https://cjm.adobe.io/imp/message/executions/{executionId}

curl --location 'https://cjm.adobe.io/imp/message/executions/HUOC-123456' \
  --header 'x-gw-ims-org-id: <IMS_ORG_ID>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'x-sandbox-name: <SANDBOX_NAME>' \
  --header 'x-sandbox-id: <SANDBOX_UUID>' \
  --header 'x-api-key: <API_KEY>'

HTTP响应代码

代码
含义
200 OK
执行已成功找到并返回
401未授权
持有者令牌缺失或无效
403禁止访问
令牌有效,但权限不足
404未找到
执行标识不存在

执行状态值

200响应中的status字段指示执行进度:

状态
说明
PENDING
执行已排队但尚未开始
INPROGRESS
当前正在处理执行
COMPLETED
执行已成功完成
FAILED
执行遇到错误

200响应还返回executionType (unitary或batch)、executionRunMode (default或test)以及包含元数据(campaignId、journeyId、batchInstanceId、资产信息)的source块,这些元数据将执行绑定回触发的营销活动或历程。

场景6:广播营销活动配置和有效负载问题 broadcast-config

[仅适用于广播用例]{class="badge informative"}

本节介绍特定于广播实时活动的故障排除方案,这些方案需要与单一营销活动不同的调试方法。

当配置文件具有有效令牌,但受众成员的实时活动未显示、更新或按预期运行时,问题通常源于以下原因之一:

  • 营销活动未配置为API触发的营销。
  • API有效负载缺少audience或iOS上的平台特定广播标识符: input-push-channel或Android上的topic_name。
  • 有效负载字段与iOS ActivityAttributes实现或Android样式提供程序映射不匹配。
  • Apple推送渠道配置不正确,或Android设备未订阅FCM主题。

此疑难解答方案适用于广播营销活动中的所有实时活动事件: start、update和end。

iOS

预检查:

  • 促销活动类型:

    • 验证是否将营销活动创建为API触发的营销(基于广播/受众的营销活动需要)。
    • 确认已在Campaign配置中定义了受众。
  • 配置文件和令牌验证:从受众中采样多个配置文件以验证它们是否具有有效的liveActivityPushNotificationDetails。 有关详细的验证步骤,请按照方案1操作。

调试步骤

accordion
​1. 验证Campaign受众配置
  1. 在Journey Optimizer中打开​API触发的营销活动。

  2. 导航到​ 受众 ​部分并验证:

    • 为营销活动选择受众。
    • 受众ID与您的API有效负载中使用的受众ID匹配。
    • 受众包含预期的用户档案。
  3. 导航到​ 操作 ​部分。

  4. 检查​实时活动配置:

    • 必须使用正确的捆绑标识符为iOS应用程序设置配置。
    • 活动类型必须与API有效负载中的attributes-type匹配。 例如,如果您的有效负载包含"attributes-type": "AirplaneTrackingAttributes",则营销活动必须指定此相同的活动类型。
accordion
​2. 验证广播API有效负载结构

广播有效负载结构不同于单一营销活动。 验证有效负载是否遵循正确的广播格式。

广播的必填字段:

code language-json
{
   "campaignId": "878a11d4-b519-47bd-8313-fecfee19857b",
   "audience": {
      "id": "8c3dbdea-2957-401f-acf0-3966fba1601e"
   },
   "context": {
      "requestPayload": {
         "aps": {
            "input-push-channel": "FEt0NgvLEfEAAOqA6AXdIQ==",
            "content-available": 1,
            "timestamp": 1771829292,
            "event": "start",
            "attributes-type": "AirplaneTrackingAttributes",
            "content-state": { ... },
            "attributes": { ... }
         }
      }
   }
}

常见有效负载问题:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3
字段 要求 常见问题
campaignId 必须与激活的营销活动ID匹配 营销活动ID错误或使用事务性营销活动
audience.id 必须匹配AEP中的现有受众 错误的受众ID或受众不存在
input-push-channel 广播必需 — 此广播实例的唯一标识符 liveActivityData中缺少或不匹配channelID
timestamp 必须始终为当前/最新Unix纪元时间(以秒为单位) 使用旧/缓存的时间戳
event 必须为"start"、"update"或"end" 事件类型无效
attributes-type 必须匹配促销活动类型 不匹配或拼写错误
content-available 必须为1 值缺失或错误

关键广播特定字段:

  • input-push-channel:

    • 所有直播直播活动均需要。
    • 用作此特定广播实例的唯一标识符。
    • 受众中的所有用户档案都会接收与此渠道关联的实时活动。
    • 必须匹配liveActivityData.channelID中的channelID(请参阅步骤3)。
    • 您的团队必须在Apple开发人员门户中为appID创建。
    • 只有为特定appID创建的频道才能用于广播该应用程序上的实时活动。
  • audience.id:

    • 必须引用在Adobe Experience Platform中创建的有效受众区段。
    • 此受众中的所有用户档案均定位为实时活动。
    • 必须激活受众并包含具有有效liveActivityPushNotificationDetails的用户档案。

始终使用最新的时间戳:

  • timestamp字段必须始终是每个API调用的当前Unix纪元时间(以秒为单位)。
  • 此要求适用于所有事件类型: start、update和end。
  • 更新/结束的关键:使用过时的时间戳会导致更新和结束请求失败。
  • 为每个广播API调用生成新的时间戳。

可选字段:

  • dismissal-date:自动删除的Unix纪元时间(仅与end事件相关)
  • alert:通知对象为title和body

有关完整的API规范,请参阅Adobe Journey Optimizer消息传送API文档。

accordion
​3. 使content-state、attributes和input-push-channel与iOS实施保持一致

请确保有效负载字段与iOS应用程序的ActivityAttributes实现匹配,并且input-push-channel与liveActivityData中的channelID匹配。

  1. 查看iOS ActivityAttributes定义。

您的自定义ActivityAttributes结构必须实施Adobe的LiveActivityAttributes协议:

code language-swift
struct AirplaneTrackingAttributes: LiveActivityAttributes {
   public struct ContentState: Codable, Hashable {
      var journeyProgress: Int
   }

   // Adobe SDK requirement
   var liveActivityData: LiveActivityData

   // Your custom attributes
   var arrivalAirport: String
   var departureAirport: String
   var arrivalTerminal: String
}
  1. 将iOS字段映射到广播API有效负载。

包括content-state用于所有事件类型。 包括attributes(包括liveActivityData.channelID)仅用于开始事件:

code language-json
{
   "aps": {
      "input-push-channel": "FEt0NgvLEfEAAOqA6AXdIQ==",
      "event": "start",
      "timestamp": 1771829292,
      "attributes-type": "AirplaneTrackingAttributes",
      "content-state": {
         "journeyProgress": 0
      },
      "attributes": {
         "arrivalAirport": "DEL",
         "departureAirport": "MUM",
         "arrivalTerminal": "T1",
         "liveActivityData": {
            "channelID": "FEt0NgvLEfEAAOqA6AXdIQ=="
         }
      }
   }
}

关键: input-push-channel必须匹配channelID

  • aps根目录中的input-push-channel值必须与liveActivityData中的channelID完全匹配。
  • 在上述示例中,两个值均为"FEt0NgvLEfEAAOqA6AXdIQ=="。
  • 此匹配将广播实例链接到实时活动数据。
  • 不匹配会导致投放失败。

关键验证点:

  • 包含所有事件类型在content-state中的所有ContentState字段。
  • 仅包括开始事件的attributes中的所有自定义LiveActivityAttributes字段。
  • 对于开始事件,liveActivityData.channelID必须匹配input-push-channel。
  • 字段名称区分大小写,且必须完全匹配。
  • 数据类型必须匹配(String、Int、Bool、嵌套对象等)。
  • 对于更新/结束事件,请使用与原始开始事件相同的input-push-channel。

常见错误:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3
问题 影响 修复
缺少input-push-channel 广播不起作用 为每个广播添加唯一的频道ID
input-push-channel与channelID不匹配 实时活动将不会启动 确保两个值相同
更新/结束的不同input-push-channel 更新/结束将不会到达实时活动 在整个生命周期中使用相同的渠道ID
缺少liveActivityData.channelID 实时活动将不会链接到广播 在开始事件的属性中包含channelID
开始事件中缺少必填字段 实时活动将不会启动 从iOS结构添加所有字段
字段名称错误(拼写错误/大小写) 字段被忽略或分析错误 完全匹配iOS字段名称
更新/结束时的过期时间戳 设备忽略更新/结束 始终生成新的时间戳
accordion
​4. 使用Assurance进行测试

使用Assurance验证API执行和有效负载投放:

  1. 在作为受众的一部分的测试设备上打开Assurance会话。

  2. 执行广播API调用。

  3. 在​ 事件列表 ​中,查找:

    • 营销活动执行事件。
    • 实时活动交付活动。
    • 指示有效负载验证失败的错误事件。
  4. 检查事件负载以确认:

    • 已正确处理有效负载。
    • input-push-channel存在。
    • 未发生验证错误。
    • 已将实时活动发送给受众成员的APN。
Android

预检查:

  • 营销活动类型:​验证营销活动是否为​API触发的营销,以及是否定义了受众。
  • 配置文件和令牌验证:​对多个受众配置文件进行采样以验证它们是否具有带platform: "fcm"的有效pushNotificationDetails。 按照方案1中的Android检查操作。
  • 主题订阅:​确认测试设备已订阅用于广播的FCM主题。

调试步骤

accordion
​1. 验证Campaign受众配置
  1. 在Journey Optimizer中打开​API触发的营销活动。

  2. 导航到​ 受众 ​部分并验证:

    • 为营销活动选择受众。
    • 受众ID与您的API有效负载中使用的受众ID匹配。
    • 受众包含预期的用户档案。
  3. 导航到​ 操作 ​部分。

  4. 检查​ 实时活动配置 ​是否指向正确的Android包并使用匹配的FCM凭据。 Android不使用活动类型或attributes-type字段。

accordion
​2. 验证广播API有效负载结构

Android广播使用FCM主题。 包括audience.id并将fcm对象放在context.requestPayload下,而不是放在单个收件人下。

广播开始有效负载示例:

code language-json
{
   "requestId": "your-request-id",
   "campaignId": "your-marketing-campaign-id",
   "audience": {
      "id": "your-audience-id"
   },
   "context": {
      "requestPayload": {
         "fcm": {
            "topic_name": "flight_DL321",
            "notification_id": "flight-DL-321",
            "notification_channel_id": "live_updates_channel",
            "timestamp": 1771829292,
            "priority": "PRIORITY_HIGH",
            "event_type": "start",
            "title": "Flight DL-321",
            "body": "Boarding starts shortly",
            "critical_text": "25 min",
            "content_state": {
               "custom_key_template_type": "progress",
               "custom_key_journey_start": "DEL",
               "custom_key_journey_progress": 10,
               "custom_key_journey_end": "MUM"
            }
         }
      }
   }
}

将示例时间戳替换为当前Unix纪元时间(以秒为单位)。 将content_state密钥调整为您的应用程序样式提供程序。

常见有效负载问题:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3
字段 要求 常见问题
campaignId 必须与激活的营销活动ID匹配 营销活动ID错误或使用事务性营销活动
audience.id 必须匹配在营销活动中配置的受众 受众ID错误或缺少受众
topic_name 必须为非空,并且在开始、更新和结束期间未更改 缺少的主题因格式错误而被拒绝;更改的主题会中断更新/结束定位
notification_id 在整个活动生命周期内必须保持不变 更新或结束定位其他通知
notification_channel_id 必须匹配应用程序创建的通知渠道 缺少渠道或渠道不匹配
timestamp 纪元秒数;必须大于同一主题的上一个值 较旧或相等的时间戳将被忽略
event_type 必须为"start"、"update"或"end" 生命周期事件无效
content_state 必须使用应用程序的样式提供程序支持的键和值类型 不支持的键或不正确的类型

关键广播特定字段:

  • topic_name:​标识目标设备订阅的FCM主题。 在每个开始、更新和结束请求中包含相同的非空值。
  • audience.id:​在Adobe Experience Platform中标识该营销活动的受众。 验证其成员资格和有效pushNotificationDetails的配置文件示例。

时间戳和可选字段:

  • 为每个事件在epoch秒内生成新的timestamp,并确保它严格大于同一主题的最后一个值。 旧值或等于值将被忽略。
  • when可以选择设置通知的显示时间(以纪元秒为单位)。 它不能控制报文排序。
  • 对于event_type: "end",dismiss_after可选择指定在删除前已完成的活动保持可见的秒数。 它是一个持续时间,而不是纪元时间戳。

有关完整的API规范,请参阅Adobe Journey Optimizer消息传送API文档。

accordion
​3. 验证主题订阅和应用程序渲染
  1. 使用FirebaseMessaging.getInstance().subscribeToTopic(topic)确认测试设备订阅了topic_name中指定的确切主题。
  2. 验证订阅是否成功,以及应用程序是否通过其安装的Adobe Live Activities扩展支持的主题订阅跟踪API报告订阅情况。
  3. 在开始、更新和结束事件中保留topic_name和notification_id不变。
  4. 验证content_state键和值类型是否与应用程序的样式提供程序匹配。
  5. 检查是否授予了通知权限,notification_channel_id是否与应用创建的渠道匹配。

常见错误:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
问题 影响 修复
topic_name缺失或为空 请求因格式错误而被拒绝 在每个生命周期请求中包含非空主题
设备未订阅主题 设备未接收广播事件 订阅确切的主题并验证订阅是否成功
更改了主题或通知ID 更新/结束不定向原始活动 在整个生命周期内保持这两个值不变
不支持的content_state键或类型 内容缺失或呈现不正确 匹配应用程序的样式提供程序映射
早于或等于timestamp 已忽略事件 使用大于上次处理时间戳的值

有关其他字段和示例,请参阅Android广播有效负载示例。

accordion
​4. 使用Assurance进行测试

在作为受众的一部分并订阅了广播主题的已连接Android测试设备上使用Assurance 。

  1. 在执行广播API调用之前,打开您的Assurance会话。
  2. 使用相同的topic_name和notification_id发送开始、更新和结束请求,并增加时间戳。
  3. 在​ 事件 ​列表中,检查可用的SDK和投放事件是否存在有效负载处理错误。
  4. 确认有效负载包含预期的fcm对象、topic_name和event_type值。
  5. 查看营销活动报告和可用的message.feedback事件以确认FCM投放结果。 Android serviceProvider值为fcm。
  6. 如果FCM接受消息但设备未呈现活动,请检查主题订阅、通知权限、渠道配置和应用程序日志。 接受提供程序时不会确认设备呈现。

场景7:配置文件不在受众中或过时的受众快照中 scenario-7-profile-not-in-audience-or-stale-audience-snapshot

[仅适用于广播用例]{class="badge informative"}

在此方案中,营销活动和有效负载已正确配置,但特定用户档案不会接收实时活动。 这通常发生在以下情况中:

  • 用户档案不是链接到营销活动的受众的成员。
  • 受众是批处理受众,包含配置文件数据的过期快照。
  • 配置文件的推送令牌详细信息(iOS上的liveActivityPushNotificationDetails或Android上的pushNotificationDetails)最近已更新,但尚未反映在受众快照中。

此疑难解答场景专门适用于使用基于受众的定位的广播营销活动。

了解受众评估

Adobe Experience Platform使用不同的受众评估方法来确定何时在受众中反映配置文件更新:

方法
评估频率
数据新鲜度
最适合
批次
每天一次(已计划)
可能长达24小时已失效
大型受众,对时间不敏感
流传输
实时(用户档案更改)
已更新配置文件的近乎实时
时效性,需要更新配置文件
Edge
在边缘位置实时
近乎实时
Edge评估的用例

预检查

  • 营销活动和有效负载验证:

    • 为平台完成方案6中的检查,以确保营销活动和有效负载正确。
    • 验证API有效负载中的audience.id是否与营销活动配置匹配。
  • 配置文件存在:​请确认Adobe Experience Platform中存在包含有效推送令牌详细信息的配置文件。 按照方案1中的检查操作。 要查找的详细信息取决于平台:

    • iOS: liveActivityPushNotificationDetails包含有效令牌。
    • Android: pushNotificationDetails,其中包含当前FCM注册令牌、与Android包名称platform: "fcm"匹配的appId以及denylisted: false。
  • 主题订阅(仅限Android):​确认设备已订阅topic_name中指定的确切FCM主题。 受众成员资格不会使设备订阅主题。 遵循方案6中的Android主题订阅检查。

调试步骤

​1. 验证配置文件是否在受众中

首先,确认应接收实时活动的配置文件是否实际属于受众。

  1. 导航到Adobe Experience Platform中的​受众。

  2. 使用营销活动中的audience.id搜索并打开受众。

  3. 单击​ 浏览 ​或​ 示例配置文件 ​查看受众成员。

  4. 使用命名空间和身份值搜索测试配置文件。

  5. 如果在受众中未找到配置文件:

    • 配置文件不符合受众标准或区段规则。
    • 查看受众定义以了解成员资格要求。
    • 更新用户档案数据或受众定义以包含用户档案。
    • 等待受众评估完成(请参阅步骤2)。
  6. 如果在受众中找到配置文件:​请继续执行步骤2以检查数据新鲜度。

​2. 检查受众评估类型和计划

确定受众使用的是批处理、流式评估还是边缘评估,因为这决定了数据新鲜度。

note
NOTE
受众评估不会注册推送令牌或将Android设备订阅到FCM主题。 它仅确定受众快照包含哪些配置文件数据。
  1. 在​ 受众详细信息 ​页面上,检查​评估方法:

    • 批次:按计划每天评估一次。
    • 流:在发生配置文件更新时实时评估。
    • Edge:在边缘位置实时评估。

根据评估方法执行相应的故障诊断步骤:

如果受众使用批次评估:

  1. 了解批次受众限制:

    • 每天评估一次批量受众(通常在一夜之间)。
    • 受众快照可能长达24小时。
    • 如果配置文件最近注册或刷新了推送令牌详细信息(iOS上为liveActivityPushNotificationDetails,Android上为pushNotificationDetails),则更新的详细信息可能不在当前快照中。
    • 直到下一次批量评估才会反映用户档案的更新。
  2. 检查上次评估的时间:

    • 在受众详细信息中,查找​ 上次评估 ​时间戳。
    • 如果个人资料的推送令牌详细信息在此时间戳后更新,则受众快照不包括当前令牌。
  3. 解决陈旧数据:

    1. 选项1:等待计划的批次评估

      • 下一次批量评估将包括更新的用户档案数据。
      • 每天自动发生一次。
      • 最适合非紧急情况。
    2. 选项2:触发按需受众评估

      1. 导航到AEP中的​受众。
      2. 选择受众。
      3. 单击​ 立即评估 ​或​按需激活。
      4. 等待评估完成(这可能需要几分钟到几小时,具体取决于受众规模)。
      5. 验证配置文件现在是否更新了受众快照中的数据。
      6. 重试广播API调用。

如果受众使用流式评估:

  1. 了解流受众行为:

    • 发生配置文件更新时,流式受众会实时评估。
    • 新用户档案:如果符合区段标准,则在创建后不久即获得资格。
    • 已更新配置文件:更新后不久即获得资格或取消资格。
    • 现有未更改的用户档案:除非进行更新,否则不会重新评估。
  2. 识别问题:

    • 如果某个用户档案已存在并符合区段标准,但该用户档案未发生更新,则可能无法将其添加到新创建的流受众。
    • 配置文件必须接收更新(任何属性更改)才能触发重新评估。
  3. 解决问题:

    • 对于新用户档案:如果满足条件,则这些用户档案会自动获得资格。 无需执行任何操作。

    • 对于没有最近更新的现有配置文件:

      • 对用户档案进行细微更新(例如,更新时间戳字段)。
      • 这会触发流式评估并将配置文件添加到受众。
      • 替代方法:为现有用户档案使用批量受众或边缘受众。

高级:通过数据集查询进行调试 advanced-debugging-via-dataset-queries

NOTE
这些查询同时适用于iOS和Android。 两个平台都使用​ AJO消息反馈事件数据集 ​中的message.feedback个事件,其架构路径和feedbackStatus值如下所示。
sent状态表示已移交给推送提供程序: iOS上的APN或Android上的FCM。

受众:开发人员和数据工程师。 需要通过Adobe Experience Platform查询服务以SQL方式访问Journey Optimizer数据集。

何时使用: Assurance仅限于测试活动会话期间连接的设备。 使用数据集查询调查生产最终用户报告的问题,或审核事实后的投放历史记录。 数据集会公开与Assurance插件相同的生命周期和失败信息。

定位数据集

  1. 在Journey Optimizer中,导航到​数据管理 > 数据集。

  2. 启用​ 显示系统数据集 ​切换功能,并打开​AJO消息反馈事件数据集。

请注意详细信息页面上显示的确切表名。 下面的查询使用ajo_message_feedback_event_dataset,如果它不同,请将其替换为实际表名。 有关此数据集的字段,请参阅Adobe Journey Optimizer架构引用。

按实时活动ID查询

当您知道实时活动ID(例如,订单UUID或装运跟踪ID),并希望每个反馈事件在整个生命周期内都与其关联时,可使用此选项。

SELECT
  timestamp,
  identitymap,
  _experience.customerJourneyManagement
    .messageDeliveryfeedback.feedbackStatus AS status,
  _experience.customerJourneyManagement
    .messageDeliveryfeedback.messageFailure.reason AS failure_reason,
  _experience.customerJourneyManagement
    .pushChannelContext.liveActivity.event AS la_event,
  _experience.customerJourneyManagement
    .messageExecution.campaignID AS campaign_id,
  _experience.customerJourneyManagement
    .messageExecution.batchInstanceID AS batch_id,
  _id
FROM ajo_message_feedback_event_dataset
WHERE
  _experience.customerJourneyManagement
    .pushChannelContext.liveActivity.liveActivityID
    = '<YOUR_LIVE_ACTIVITY_ID>'
  AND eventtype = 'message.feedback'
ORDER BY timestamp ASC

按ECID查询

当受影响配置文件的ECID已知时,可使用此选项。 使用从配置文件检索到的ECID值替换<YOUR_ECID>。

SELECT
  timestamp,
  _experience.customerJourneyManagement
    .messageDeliveryfeedback.feedbackStatus AS status,
  _experience.customerJourneyManagement
    .messageDeliveryfeedback.messageFailure.reason AS failure_reason,
  _experience.customerJourneyManagement
    .pushChannelContext.liveActivity.event AS la_event,
  _experience.customerJourneyManagement
    .pushChannelContext.liveActivity.liveActivityID AS la_id,
  _experience.customerJourneyManagement
    .messageExecution.campaignID AS campaign_id,
  _id
FROM ajo_message_feedback_event_dataset
WHERE
  identityMap['ECID'][0].id = '<YOUR_ECID>'
  AND eventtype = 'message.feedback'
ORDER BY timestamp ASC
NOTE
identityMap是结构化MAP类型,而不是字符串。 使用上面所示的数组和结构访问器语法。 字符串函数(如LIKE)将返回DATATYPE_MISMATCH错误。
消息反馈事件数据集仅在其identityMap中存储ECID。 如果受影响的配置文件由自定义命名空间而不是ECID标识,请首先解析ECID:在AEP中导航到​配置文件,使用自定义命名空间和标识值搜索配置文件,并从配置文件的标识详细信息中检索ECID。 在上面的查询中使用该ECID值。

feedbackStatus值

值
含义
sent
已移交给推送提供商(iOS上的APN,Android上的FCM);不确认设备渲染(请参阅下文)
error
投放错误 — 检查failure_reason以了解详细信息
denylist
令牌无效、未注册或列入阻止列表(例如,未安装的应用程序);请重新注册设备令牌
exclude
发送前排除的配置文件(缺少令牌、同意问题或类型规则)
delay
传递已延迟;将重试
duplicate
投放级别重复数据删除已禁止重复发送
bounce
推送提供程序退回的投放(例如,令牌返回的硬故障)
NOTE
对于la_event字段,数据集记录初始投放事件的remotestart,而不是start。 在按事件类型进行查询时进行相应的筛选。

解释已发送状态 interpreting-the-sent-status

IMPORTANT
8小时实时活动持续时间限制仅适用于iOS,而不适用于Android。

sent的feedbackStatus确认Journey Optimizer已成功将通知传递给推送提供程序(iOS上的APN,Android上的FCM)。 它​ 不 ​确认已在设备上呈现实时活动。

在移交给推送提供程序后,数据集不会确认设备渲染。 从数据集中无法观察到设备端故障,例如操作系统限制、提供商和设备之间的网络中断或iOS上达到8小时的实时活动持续时间限制。

如果feedbackStatus为sent,但设备上未显示实时活动,请调查Journey Optimizer投放管道外的行为。 使用Assurance或应用程序级别的日志记录(包括Android上的logcat)来诊断设备端行为。

AI Knowledge Reference

This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.

For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.

  • TL;DR: This page provides a systematic approach to diagnose why Live activities fail to appear, update, or end even when the API returns HTTP 200, covering profile and token, campaign configuration, payload, and delivery issues for unitary and broadcast use cases on iOS and Android.

Intents:

  • Distinguish the unitary (API-triggered Transactional) and broadcast (API-triggered Marketing) debugging paths
  • Verify profile existence and Live activity push token sync (Scenario 1)
  • Validate campaign surface, Activity type, and API payload structure (Scenario 2)
  • Analyze delivery failures via campaign reports and message.feedback events (Scenario 3)
  • Diagnose unsynced iOS update tokens (Scenario 4) and check unitary execution status via the GET Message Execution API (Scenario 5)
  • Troubleshoot broadcast payload and audience-freshness issues (Scenarios 6 and 7) and query the feedback dataset directly (Advanced)

Glossary:

  • pushNotificationDetails: The AEP profile attribute used for Android FCM registration-token details, including appId, platform, and denylisted (product-specific)

  • topic_name: The FCM topic subscribed to by target Android devices for broadcast Live activities (product-specific)

  • Push-to-start token: An iOS APNs token used for remote start; registered by the mobile SDK and stored on the AEP profile (product-specific)

  • Update token: A per-instance APNs token generated when an iOS Live activity starts; required for iOS unitary update and end events. Android uses the same FCM registration token for start, update, and end; no separate update token is required (product-specific)

  • input-push-channel: A unique channel identifier created on the Apple Developer Portal for iOS broadcast Live activities (product-specific)

  • liveActivityData: A required property on the Adobe SDK LiveActivityAttributes protocol; the iOS examples include liveActivityID for unitary or channelID for broadcast (product-specific)

  • channelID: The value in liveActivityData.channelID; must exactly match input-push-channel for iOS broadcasts (product-specific)

  • attributeType / attributes-type: The name of the Swift ActivityAttributes struct; stored as attributeType (camelCase) on the profile and sent as attributes-type (hyphenated) in APS JSON — the same value in different representations (product-specific)

  • liveActivityPushNotificationDetails: The AEP profile attribute that stores a device’s push-to-start token, appId, platform, and attributeType (product-specific)

  • APS payload: The iOS JSON structure sent under context.requestPayload.aps, containing the event, content-state, and control fields; attributes includes the iOS struct fields for start events (product-specific)

  • Assurance: A debugging tool limited to test devices connected during an active session; use dataset queries for production end-user diagnostics (product-specific)

  • topic_name (Android): The shared FCM topic through which subscribed devices receive broadcast events; the Android equivalent of iOS input-push-channel

  • notification_id (Android): Client-generated identifier for a Live activity instance; keep it unchanged across start, update, and end events to target the same instance

  • timestamp (Android): Message ordering key, expressed in epoch seconds

  • when (Android): Optional notification display time, expressed in epoch seconds; it does not control message ordering

  • dismiss_after (Android): Used only for end events; specifies how many seconds the completed Live activity remains visible before removal

Guardrails:

  • Android audience membership does not subscribe a device to the FCM topic; verify topic subscription separately from audience evaluation.

  • Use API-triggered Transactional campaigns for unitary Live activities and API-triggered Marketing campaigns for broadcasts.

  • The High Throughput option must not be enabled, since it is incompatible with Live activity.

  • Assurance sessions are for test and QA devices only; end-user production devices are not connected to Assurance.

  • Android: unitary Live activities use the same regular FCM push token to start, update, and end, and no separate activity tokens are required; broadcast events reach subscribed devices through the shared FCM topic identified by topic_name.

  • Android timestamp must strictly increase for every event with the same notification_id (or topic_name for broadcasts); updates are displayed only if their timestamp is newer than the last processed value, and older or equal timestamps are ignored.

  • Android action_type / action_uri are not read by the current Android SDK.

  • iOS requirements: a physical iOS device on iOS 16.1 or later; the Xcode Simulator supports local start only (remote push via APNs is not supported on Simulator); remote start from Assurance requires iOS 17.1 or later, a valid push-to-start token, and a valid channel configuration; Adobe Experience Platform Mobile SDK 5.11.0 or later.

  • Batch audiences may be up to 24 hours stale (batch evaluation, once daily); this audience-freshness risk is not applicable to unitary use cases.

  • The first time a Live activity starts on a device, iOS shows a one-time permission prompt; the user must tap “Allow” for update tokens to be generated and synced.

  • For iOS broadcasts, input-push-channel must exactly match liveActivityData.channelID; a mismatch causes delivery failures.

  • For iOS, a feedbackStatus of sent confirms hand-off to APNs only, not device rendering; device-side failures and the 8-hour Live activity duration limit are not observable from the dataset.

Terminology:

  • Canonical name: API Triggered Campaign — Acronym: n/a — campaign types used for Live activities: API-triggered Transactional (unitary), API-triggered Marketing (broadcast)
  • Synonyms: “attributeType” = “attributes-type” (the same value; camelCase on the profile, hyphenated in APS JSON)
  • Do not confuse: input-push-channel (in the iOS APS payload) ≠ liveActivityData.channelID (in the iOS attributes); their values must match for broadcasts.
  • Do not confuse: “Push-to-start token” (starts an iOS Live activity, stored on the profile) ≠ “Update token” (updates or ends an iOS unitary instance, per instance)
  • Do not confuse: “Unitary” (API-triggered Transactional, individual profile) ≠ “Broadcast” (API-triggered Marketing, audience segment)
  • Do not confuse: execution statuses “PENDING” ≠ “INPROGRESS” ≠ “COMPLETED” ≠ “FAILED”
  • Do not confuse: feedbackStatus “sent” ≠ “error” ≠ “exclude” ≠ “delay”
  • Do not confuse: “timestamp” (iOS: the current Unix epoch time in seconds for every call; Android: the ordering key that must strictly increase per notification_id or topic_name) ≠ “when” (Android: optional notification display time that does not control ordering)
  • Do not confuse: la_event value “remotestart” (recorded in the dataset for initial delivery) ≠ “start” (the event field value in the payload)

FAQ:

  • Q: Why does the API return 200 OK but the Live activity does not appear? — A successful response (200 OK) does not guarantee the Live activity appears; the delivery can fail at multiple points, from API request validation through device rendering, so work through Scenarios 1 to 3.
  • Q: Can I use Assurance for production end-user devices? — No; Assurance sessions are for test and QA devices only. For production diagnostics, use the dataset queries.
  • Q: Why do update and end calls fail after the Live activity started? — The per-instance update token may not be synced; the user must have tapped “Allow” on the one-time permission prompt for update tokens to be generated (Scenario 4).
  • Q: How do I check execution status programmatically? — Use the GET Message Execution API; for unitary executions the executionId is prefixed with HUOC-, and the status field returns PENDING, INPROGRESS, COMPLETED, or FAILED.
  • Q: What does a feedbackStatus of sent mean on iOS? — It confirms Journey Optimizer successfully handed the notification to APNs; it does not confirm that the Live activity was rendered on the device.
  • Q: Why are some audience members not receiving a broadcast? — The profile may not be in the audience, or a batch audience snapshot may be up to 24 hours stale; trigger on-demand evaluation or ensure a streaming update occurs (Scenario 7).

Personas:

  • marketer: Can open the Reports button on a Live activity Campaign and select View all time report to check Sending Statistics metrics. Can review the Live activity lifecycle section for Remote starts, Updates, Ends, and Totals count figures. The page states that if Send errors are greater than 0, check the Error Reasons table. Where: “Check campaign reports”.

Onboarding:

  • Level: Intermediate
  • First minimal step: Navigate to Customer, then Profiles, in Journey Optimizer to search for a profile using the namespace and identity value from the API request.
  • Success check: The profile is found, and you can continue with the token checks for your platform.
  • Previous: Creating the Live activity message before triggering it: Create a Live activity message (mobile-live/create-mobile-live.md)
  • Next: Learning more about Live activity campaign reporting metrics: Campaign Live activity report (reports/campaign-global-report-cja-activity.md)
recommendation-more-help
journey-optimizer-help