实时活动故障诊断 troubleshoot-mobile-live

1. 在Journey Optimizer中，导航到​客户 > 配置文件。
2. 使用API请求中的命名空间和身份值搜索。
3. 如果找不到配置文件，则该配置文件不存在或摄取未完成。 在触发实时活动之前创建配置文件或等待摄取。
4. 如果找到配置文件，请继续执行下面的步骤2以检查推送令牌是否已同步。

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

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

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

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

如果未找到任何事件，则表示您的移动应用无法正确调用Messaging.registerLiveActivity。 您需要修复SDK集成。

1. 从您的​配置文件，访问​ 属性 ​选项卡。

2. 找到liveActivityPushNotificationDetails。

3. 验证令牌配置：

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

验证每个字段：

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

如果liveActivityPushNotificationDetails缺失：令牌尚未同步。 在Assurance中看到liveActivity.pushToStart事件后等待5-10分钟。

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

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

单一有效负载：

{
  "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": { ... }
        }
      }
    }
  }]
}

常见有效负载问题：

关键：始终使用最新的时间戳

• 在发出每个API调用时，timestamp字段必须​ 始终 ​为当前​Unix纪元时间（秒）。
• 这适用于​所有事件类型： start、update和​，特别是end。
• 对更新/结束请求的影响：使用过时的或旧的时间戳将导致更新和结束请求失败或被设备忽略。
• 请​ 不 ​重复使用以前请求中的时间戳或使用缓存的值。
• 为每个API调用生成新的时间戳。

可选字段（所有事件类型）：

• requestId：用于跟踪的唯一标识符（推荐）。
• alert：通知对象为title和body（用于提醒注意更新）。

关于dismissal-date：

• 包含Unix纪元时间（秒）的可选字段。
• 仅在event: "end"​时相关。
• 指定何时应自动从设备中删除实时活动。
• 如果未在最终事件中提供，实时活动将保持可见，直到用户将其消除。
• 必须为未来的时间戳（晚于timestamp）。

确保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" } } }

验证核对清单：

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

• 包括LiveActivityAttributes中的所有attributes字段（仅限开始事件），包括：

  • liveActivityData （必需；通常包含liveActivityID或类似的标识符）
  • 结构中的所有自定义字段

• 完全匹配字段名称（区分大小写）。

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

• 保留嵌套的对象结构。

常见错误：

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

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

1. 打开Assurance会话。

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

3. 在​ 事件列表 ​中，检查：

   • 营销活动执行事件。
   • 实时活动交付活动。
   • 有效负载验证错误事件。

4. 查看事件负载以验证：

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

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

2. 单击​ 报表 ​按钮。

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

4. 请查看以下部分：

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

      table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
      量度	它的含义	要查找的内容
      已定位	符合受众条件的配置文件数	应包含您的测试用户档案
      发送	尝试的推送通知总数	应与您的API调用匹配
      已送达	已成功交付到设备	比较发送以查看成功率
      发送错误	发送失败的推送通知	高数字
      发送排除项	Adobe Journey Optimizer排除的用户档案	检查您的配置文件是否已被排除

   2. 如果发送错误> 0，请检查​ 错误原因 ​表以了解具体的错误代码和消息：

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

   3. 如果​发送排除项 > 0，请检查​ 排除的原因 ​表：

      table 0-row-3 1-row-3 2-row-3 3-row-3
      常见排除项	含义	解决方法
      配置文件已选择退出	用户已选择退出通知	检查配置文件同意状态
      列入阻止列表令牌	令牌标记为无效	重新注册令牌或检查阻止列表状态
      配置文件不符合条件	配置文件不符合营销活动标准	查看活动受众规则

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

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. 如果未找到反馈事件：

   • 可能尚未尝试推送通知
   • 检查营销活动报告中是否排除了用户档案（如上面的步骤1所述）。

1. 打开Assurance会话，它在API调用期间必须处于活动状态。

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调用频率

1. 查看营销活动报告中的实时活动生命周期量度。

   在营销活动报告中，查看​ 实时活动生命周期 ​部分：

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

   如果这些指标为零或与您的API调用不匹配，则Adobe与APN之间存在交付问题。

2. 如果Adobe显示已成功交付，但设备未显示实时活动：

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

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

必需的信息：

• 营销活动 ID 和名称

• 配置文件命名空间和ID

  • API有效负载中的liveActivityID

• API调用时间戳

• 屏幕截图：

  • 营销活动报告（发送统计数据、错误原因、排除的原因）
  • 配置文件事件(liveActivity.updateToken， message.feedback)
  • 显示投放事件的Assurance会话

• 完成API请求负载

• APNs证书详细信息（到期、环境、捆绑包ID）

1. 打开Assurance会话。

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

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

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

   • 验证token字段是否包含有效的更新令牌字符串。
   • 检查liveActivityID是否与您的实时活动实例匹配。
   • 确认activityType与您的attributes-type匹配。

5. 如果找不到事件：

   • SDK未生成或捕获更新令牌。
   • 检查用户是否被授予实时活动权限。
   • 验证是否已在设备上成功启动实时活动。
   • 确认移动设备SDK已正确集成以捕获更新令牌。

6. 如果找到事件，请继续执行步骤2。

1. 在Journey Optimizer中导航到​客户 > 配置文件。

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

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

4. 查找liveActivity.updateToken事件。

5. 检查事件详细信息：

   • 验证时间戳是否为最新（与实时活动开始的时间匹配）。
   • 确认token和liveActivityID存在。
   • 确保activityType正确。

6. 如果在配置文件中未找到事件：

   • 可能尚未将更新令牌事件引入配置文件。
   • 等待5-10分钟，然后重新检查。
   • 如果15分钟后仍然缺失，则可能存在事件摄取问题。

7. 如果找到事件，则表示更新令牌已同步。 您可以继续执行步骤3。

1. 在Assurance会话中，执行更新或结束API调用。

2. 在​ 事件列表 ​中，查找实时活动投放事件（APNs推送事件）。

3. 检查事件以指示：

   • 推送通知已发送到APN。
   • 来自APN的响应（成功或错误）。
   • 投放确认。

4. 如果存在APNs投放事件：已发送推送通知。 如果设备仍未更新，则问题可能出在设备端（应用程序无法处理推送、网络问题等）。

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

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

1. 在Journey Optimizer中打开​API触发的营销活动。

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

   • 为营销活动选择受众。
   • 受众ID与您的API有效负载中使用的受众ID匹配。
   • 受众包含预期的用户档案。

3. 导航到​ 操作 ​部分。

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

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

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

广播的必填字段：

{
  "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": "update",
        "attributes-type": "AirplaneTrackingAttributes",
        "content-state": { ... },
        "attributes": { ... }
      }
    }
  }
}

常见有效负载问题：

关键广播特定字段：

• input-push-channel：

  • 所有直播活动均需要此参数。
  • 用作此特定广播实例的唯一标识符。
  • 受众中的所有用户档案都会收到与此渠道关联的实时活动。
  • 必须匹配channelID中的liveActivityData.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文档。

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

1. 查看iOS ActivityAttributes定义。

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

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有效负载。

对于所有事件，包括attributes和content-state：

      {
      "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

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

关键验证点：

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

常见错误：

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

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

2. 执行广播API调用。

3. 在​ 事件列表 ​中，查找：

   • 营销活动执行事件。
   • 实时活动交付活动。
   • 指示有效负载验证失败的错误事件。

4. 检查事件负载以确认：

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

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

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

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

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

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

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

   • 配置文件不符合受众标准或区段规则。
   • 查看受众定义以了解成员资格要求。
   • 更新用户档案数据或受众定义以包含用户档案。
   • 等待受众评估完成（请参阅步骤2）。

6. 如果在受众中找到配置文件：​请继续执行步骤2以检查数据新鲜度。

确定受众使用批量评估还是流式评估，因为这决定了数据新鲜度。

1. 在​ 受众详细信息 ​页面上，检查​评估方法：

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

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

如果受众使用批次评估：

1. 了解批次受众限制：

   • 每天评估一次批量受众（通常在一夜之间）。
   • 受众快照可能长达24小时。
   • 如果配置文件最近注册了实时活动令牌，则这些令牌可能不在当前快照中。
   • 直到下一次批量评估才会反映用户档案的更新。

2. 检查上次评估的时间：

   • 在受众详细信息中，查找​ 上次评估 ​时间戳。
   • 如果个人资料的liveActivityPushNotificationDetails在此时间戳之后更新，则受众具有过时数据。

3. 解决陈旧数据：

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

      • 下一次批量评估将包括更新的用户档案数据。
      • 每天自动发生一次。
      • 最适合非紧急情况。

   2. 选项2：触发按需受众评估

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

如果受众使用流式评估：

1. 了解流受众行为：

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

2. 识别问题：

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

3. 解决问题：

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

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

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