实时活动疑难解答 troubleshoot-mobile-live

Adobe Experience Platform Assurance中的“实时活动”视图可验证应用程序的设置、检查活动事件，并允许您从测试会话远程启动、更新或结束活动。

要求

三个选项卡

从Assurance开始、更新和结束

开始实时活动。 打开对话框以选择注册的活动类型，选择统一或广播，输入广播频道ID（仅限广播），并编辑预填充的APS JSON有效负载。 按钮已禁用，或者如果未满足推送开始令牌、iOS版本或渠道配置要求，则会返回错误。

发送更新。 从现有活动的概述选项卡中，发送更新（推送新内容）或结束事件。 为了统一，插件会自动使用活动的更新令牌。 对于广播，它将定向订阅了同一广播频道ID的所有设备。 负载必须是有效的JSON，并且与活动的属性架构匹配；否则，请求会被拒绝。

有关设置和会话连接步骤，请参阅Adobe Experience Platform Assurance文档。

导航到Journey Optimizer中的API触发的营销活动，并检索：

• 营销活动名称和ID
• Campaign版本（如果适用）
• 营销活动类型： 事务型 （单一）或​营销 （广播）
• 表面配置：用于实时活动的iOS应用程序表面
• 活动类型：在营销活动中配置的AttributeType结构名称

在进行API调用以触发实时活动时，保存：

• API请求负载，包括配置文件标识符和实时活动数据
• api响应，包括状态代码、消息ID、请求ID
• 调用API的时间戳
• 使用的端点，例如/campaign/{CAMPAIGN_ID}/execute

从您的API请求中检索：

• 配置文件命名空间，例如ECID、电子邮件、客户ID
• API调用中使用的配置文件ID

确保您可以在Adobe Experience Platform中查找此配置文件。 在Experience Platform文档🔗中了解如何查找配置文件。

从测试设备收集以下信息：

• 设备型号，例如iPhone 14 Pro
• iOS版本
• 应用程序包标识符
• APN推送令牌
• 测试时的网络连接状态

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应用配置表面，使其包标识符与您配置文件liveActivityPushNotificationDetails中的appId匹配。 例如，如果您的配置文件具有"appId": "com.example.myapp"，则表面必须针对同一应用程序。
3. 检查营销活动配置中的​ 活动类型 ​是否与用户档案的liveActivityPushNotificationDetails中的attributeType完全匹配。 例如，如果您的配置文件具有"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" } } }

验证核对清单：

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

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

  • 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:

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

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

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

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

关键验证点：

• 包含所有事件类型在content-state中的所有ContentState字段。
• 仅包括开始事件的attributes中的所有自定义LiveActivityAttributes字段。
• 对于开始事件，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. 解决问题：

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

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

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