常见问题

接入过程中的常见问题与处理方法。

连接

说明设备已安装星流，但星河岛尚未响应。常见原因是星流中的星河岛未启用，或设备刚刚启动、尚未就绪；在 OPPO、一加、realme 手机上，也可能是用户尚未安装或启用星流官方插件「流体云事件接入」，插件启用前星河岛不显示。星河岛就绪后客户端会自动连接，无需重复调用 connect()。

设备未安装星流，或已安装的星流版本不支持通信版本 7。星河岛 SDK 0.1.2 仅能连接通信版本为 7 的星流，高于或低于 7 均不兼容。

星河岛核对应用身份未通过。请确认应用由自身进程调用 SDK，且工具包的清单声明已合并到应用中。

应用正在前台：默认情况下，应用在前台时其内容不在星河岛显示，离开应用后立即出现；用户关闭星流「显示规则」页的「进入对应应用时隐藏」后照常显示。
排位靠后：更高优先级的事项正在显示，内容在副岛或等待队列中。
用户已收起该内容：此前应用应已收到 onDismissed。用户开启「长时间未操作时收起」或「停留后收起」时，内容也可能被自动收起；此情形不会收到 onDismissed。
锁屏设置：锁屏时按 LockScreenVisibility 与系统锁屏通知设置显示。

不能。用户开启「显示应用来源」时，来源栏由星河岛根据发送应用写入，应用不能修改；该开关默认关闭，用户可在星流「显示规则」页打开或关闭。

不能。导航与通话模板仅用于系统导航与来电，以防止应用内容冒充。

同一应用 10 秒内最多自动展开一次；熄屏、下拉通知栏或勿扰模式下也不会自动展开。

请确认更新时使用了与首次提交相同的内容编号。编号不同会被视为新的事项。

每个应用每秒最多提交 10 次（start、update、end 均计入）。计时与音乐进度由星河岛自行推进，无需逐秒更新；其他进度请在有明显变化时更新。

每个应用最多保留 3 条通过 SDK 提交的内容，排队内容也计入。星河岛自行读取的同应用通知与音乐不占用此名额。请先结束已完成的内容。

内容已受理，但有图片不符合要求而未显示。位图的宽和高须在 1 至 2048 像素之间，占用内存不超过 8 MB，且未被回收。

显示来源栏时，来源栏已显示应用图标，卡片左侧只放内容自身的图像。卡片上的图像不接受 IslandImage.appIcon()，胶囊与副岛可以使用。用户关闭「显示应用来源」且卡片没有内容图像时，星河岛会在卡片左侧显示应用图标。

早期接入库（astraisland-client）已停止提供，新版星流不再接受其连接。请改用星河岛 SDK 0.1.2：替换工具包，并按快速开始改用 com.astraisland.sdk 包中的接口；应用自行绘制整张卡片的方式不再提供，请改用九套卡片模板。

使用消息模板 MessageCard，调用 setReplyEnabled(true) 开启回复。状态配图见回复与发送状态。

「标为已读」需要应用添加文字按钮，并在 onAction 中处理会话状态。仅添加按钮不会自动标记已读。写法见标为已读。

该提示只表示回复文字已经交给接入应用。是否发出、是否送达，由应用实际使用的短信或聊天服务确认。

请核对通知编号与标签是否和本应用实际发布的通知一致。屏蔽横幅还要求对应内容正在主岛或副岛显示，且用户开启「屏蔽系统横幅」；排队或隐藏期间不屏蔽横幅。

设置了 setPostedAt 时，请仅在收到新消息时更新发送时间；刷新同一消息的按钮或图片时保留原时间。未设置发送时间时，发送人或正文变化才视为新消息。自动展开另受每个应用十秒一次的限制。

横屏不截取卡片标题。数值保留数字与单位，长文本按完整短状态显示；可用 setLandscapeText 提供数字与英文分组后四行内的完整短文字。消息显示应用名称，音乐优先显示波形。

disconnect() 会结束本应用通过 SDK 提交的全部内容。需要在离开应用页面后继续显示时，应按实际业务生命周期管理客户端；不要把页面关闭直接等同于事项结束。星河岛重新启动后，等待 READY，通过 listMine() 核对并重新提交仍有效的事项。