团队基建 / 通知 SDK

SDK 接口草案 · v0.1

清理 App × Launcher

以系统默认桌面角色为准切换通知模式。PUSH SDK 决定是否提醒、何时提醒。Launcher SDK 渲染桌面通知,宿主统一处理落地页和广告。

01

双模式流程

同一个 App 首页入口。系统默认桌面与通知授权分别决定能展示什么。

演练

纯 App · 已授权 显示系统通知。第一次已授权的用户在首页直接启用 PUSH。

首次启动 · 检查并申请系统通知权限

允许或拒绝,均继续到 Launcher 引导。系统里已有授权可直接复用。

引导设置 Launcher

从系统返回后重新读取默认桌面角色。

纯 App

未成为默认 Launcher
进入 App 首页

首次流程中仍未授权时,展示一次通知说明。用户点击继续才申请,系统不再允许弹框时提供设置入口。

已授权 · 启用 PUSH

按策略开启常驻通知。定时、解锁和转后台触发仍需经过投递条件。

未授权 · PUSH 关闭

清理功能正常使用。授权变化后按当前状态重算。

首页根页面返回 · 询问是否设置 Launcher

「去设置」打开系统选择页,确认成功后切到 Launcher 模式。取消系统选择回到 App。点「直接退出」按正常返回退出。

实际退出后的首次冷启动回访

先进入 App 首页,仍关闭通知时再给一次自定义提示。此次回访机会只消费一次,设置返回、回前台和旋转不算冷启动回访。纯 App 模式下,之后根页面返回仍可询问 Launcher。

Launcher + App

已成为默认 Launcher
仍进入 App 首页

关闭 SDK 的系统 PUSH 任务和常驻通知。用户在根页面返回时,复核角色并通过系统 HOME 入口回到当前默认桌面。

解锁 · Launcher 主屏幕可见

PUSH SDK 校验角色、桌面可见性、投放人群、开关、间隔、次数和关闭冷却。高优先级弹窗存在时跳过。

Launcher SDK 显示桌面通知

在 Launcher 自身界面渲染。仅实际显示成功时计入次数,切换默认桌面或离开桌面时撤下。

点击 · 走 ICON 入口广告与落地页

同时记录真实来源为桌面通知。点击只提交一次,关闭或滑除不执行跳转。

本方案中的系统通知权限指 POST_NOTIFICATIONS。现有「清除通知」功能独立使用系统通知访问。桌面通知是 Launcher 自身界面中的 View。

02

三个模块如何交互

桌面是否能显示由 Launcher SDK 报告。PUSH SDK 持有提醒判定,宿主只接一条跳转入口。

宿主 App

  • 清理业务、Splash、App 首页和实际落地页。
  • 初始化 SDK,绑定启动页和首页生命周期。
  • 接入统一的跳转器与宿主状态,将桌面通知广告接到 ICON 入口。

PUSH SDK

  • Launcher 角色与发通知权限检查,系统授权和两种自定义弹窗。
  • 回访记账、事件监听、频控、触发和模式切换。
  • 构建系统通知与模板,向 Launcher 请求桌面展示。

Launcher SDK

  • 提供 HOME 组件并维护桌面可见及可交互状态。
  • 渲染和移除桌面通知 View,报告是否真的显示。
  • 回传点击或关闭事件。同一通知 ID 的事件在本次展示中唯一。

桌面通知从解锁到点击

  1. 解锁事件
  2. PUSH 校验并去重
  3. Launcher 确认已显示
  4. PUSH 计次
  5. 用户点击
  6. 宿主 ICON 链路

首版按宿主和 Launcher 同 APK、同进程设计。Launcher 实现 LauncherNoticePort,宿主初始化时传入。PUSH 只依赖公开接口,桌面 View 与布局由 Launcher SDK 维护。公开类型可以放在独立的 API 契约包中供两边编译。

投递规则

飞书参考以确认的 B 侧买量用户为投放对象。两种模式共用总开关和静默时段,各自维护开关、日上限和最短间隔。归因尚未确认时,收到宿主状态更新后重算。

系统 PUSH

触发时还需校验本地 PUSH 分组、通知权限及渠道,以及设备亮屏解锁。要求纯 App 模式、App 已在后台且无自有广告在展示。常驻入口使用独立的 push_service 渠道,按自身开关和服务条件恢复。

桌面通知

解锁后仅在默认 Launcher 的主屏幕可交互时展示。PUSH 选择符合人群、间隔和次数的配置,Launcher 检查高优先级弹窗和窗口状态。支持卡片或弹窗,自动关闭时间为 0 时由点击、关闭或离开桌面结束。

03

SDK 对外接口

宿主接入只做初始化、启动准备、首页绑定和统一路由。

宿主接入 · Kotlin 伪代码
// Application.onCreate
val push = PushSdk.install(
    app = this,
    launcher = LauncherSdk.noticePort(),
    entries = hostEntryRouter,
    routes = hostAllowedRouteIds,
    hostSignals = deliverySignals,
)

// Splash.onCreate,先注册 Activity Result
val launch = push.bindStartup(this)
lifecycleScope.launch {
    val ticket = launch.prepareHome()
    openAppHome(ticket)
}

// AppHome.onCreate,普通首页可以传 null
push.bindHome(
    host = this,
    ticket = launchTicket,
    isAtRoot = navigation::isAtRoot,
    onExit = ::finish,
)

// 已有宿主跳转器
val hostEntryRouter = EntryRouter { activity, request ->
    openThroughHostEntryPipeline(activity, request)
}
PUSH 与 Launcher 的接口签名
object PushSdk {
    fun install(
        app: Application,
        launcher: LauncherNoticePort,
        entries: EntryRouter,
        routes: Set<RouteId>,
        hostSignals: StateFlow<HostSignals>,
    ): PushClient = TODO()
}

interface PushClient {
    val state: StateFlow<PushState>
    fun bindStartup(host: ComponentActivity): StartupSession
    fun bindHome(
        host: ComponentActivity,
        ticket: LaunchTicket?,
        isAtRoot: () -> Boolean,
        onExit: () -> Unit,
    )
}

interface StartupSession {
    suspend fun prepareHome(): LaunchTicket
}

interface LauncherNoticePort {
    val surface: StateFlow<LauncherSurface>
    val actions: Flow<DesktopNoticeAction>
    @MainThread fun showNotice(notice: DesktopNotice): ShowResult
    @MainThread fun dismissNotice(id: NoticeId)
}

fun interface EntryRouter {
    fun open(activity: Activity, request: EntryRequest)
}

data class HostSignals(
    val audience: Audience, // PAID_B, OTHER, UNKNOWN
    val inLocalPushCohort: Boolean,
    val globalOn: Boolean,
    val localPushOn: Boolean,
    val desktopNoticeOn: Boolean,
    val appAdShowing: Boolean,
)

enum class ShowResult {
    SHOWN, NOT_VISIBLE, BUSY, UNAVAILABLE
}
接口或数据调用与契约
install / HostSignals同一进程内幂等,从固定路径读产品 AAR。宿主统一提供已确认买量、PUSH 分组、开关和自有广告展示状态。需要投放资格的规则在状态未知时等待重算。无长期 Activity 引用。配置无效时关闭通知能力,宿主首页照常打开。
bindStartup → prepareHome在 onCreate 注册权限与角色的 Activity Result,界面就绪后执行首次引导。返回含启动 ID 和进入原因的 LaunchTicket,交接给宿主首页。旋转和重建复用同一轮状态。
bindHome在 onCreate 绑定。首页可见后按票据补提示。正常页面返回交给宿主导航。根页面返回时复核角色,纯 App 模式显示询问,Launcher 模式通过系统 HOME 入口返回。允许正常退出时先记录退出,再调用 onExit。
PushStatemode 为 APP 或 LAUNCHER。原始系统授权 canPostSystemNotifications、实际启用 systemPushEnabled 和桌面可见 launcherSurfaceVisible 分开报告。
LauncherSurface / ShowResult桌面真实前景窗口可见且可交互才返回就绪。SHOWN 表示 View 已显示,NOT_VISIBLE、BUSY 和 UNAVAILABLE 均不计次。未展示成功不跨场景补发。
DesktopNotice / DesktopNoticeAction下发 noticeId、展示文案、图标引用和有效期。Launcher 只回传 Clicked 或 Dismissed 及该 ID。PUSH 按已展示记录解析,不接受 UI 临时传入任意目标。
EntryRequestrouteId 必须在宿主白名单内。eventId 用于去重。桌面点击的 entryKind=LAUNCHER_ICON,origin=DESKTOP_NOTICE。系统通知使用 entryKind=SYSTEM_NOTIFICATION,对应落地页返回 App 首页。

两种点击统一进入 SDK 清单注册的内部 Activity(exported=false),解析并消费短期一次性令牌,再将 Activity 交给宿主 EntryRouter。系统通知使用显式 Activity PendingIntent,桌面通知通过 Launcher 界面上的用户点击进入同一个入口。宿主沿用自身广告流程和页面栈。

04

产品资源包 → AAR

提交一个 ZIP,CI 校验后生成产品配置 AAR。PUSH 内核独立发版,宿主通过一个 Maven 依赖接入产品配置及其传递依赖。

  1. 资源 ZIP
  2. 校验 schema、图标、翻译和路由
  3. Gradle 打包产品 AAR
  4. 宿主依赖产品坐标

ICON_TEXT

清理助手
查看可清理的文件

一个图标、标题和正文,整条点击对应一个落地页。两种样式都配置系统状态栏用的单色小图标。

SHORTCUT_GRID

清理 大文件 应用管理

每个入口配置独立图标、名称和路由。首版模板最多显示 3 个入口,收起态受限时保留总入口,其余在展开态提供。

ZIP 目录与交付坐标
cleaner-push-profile.zip
├── profile.json
├── routes.json
├── strings/
│   ├── default.json
│   └── zh-CN.json
└── res/
    ├── drawable/ic_notify_small.xml
    └── drawable-nodpi/
        ├── ic_clean.webp
        ├── ic_files.webp
        └── ic_apps.webp

# routes.json 示例
{"routeIds":["home","clean","large_files","apps"]}

# CI 发布示例
team:cleaner-push-profile:1.0.0
└── team:push-sdk:<locked-version>

# 宿主 Gradle
implementation("team:cleaner-push-profile:1.0.0")
profile.json · 模板示例
{
  "schemaVersion": 1,
  "productId": "cleaner",
  "system": {
    "smallIcon": "ic_notify_small",
    "ongoing": {
      "template": "SHORTCUT_GRID",
      "defaultRoute": "home",
      "items": [
        {"id":"clean","icon":"ic_clean","labelKey":"clean","routeId":"clean"},
        {"id":"large","icon":"ic_files","labelKey":"large_files","routeId":"large_files"},
        {"id":"apps","icon":"ic_apps","labelKey":"apps","routeId":"apps"}
      ]
    },
    "triggers": {
      "timer": {"content":"clean_reminder","intervalMinutes":20},
      "unlock": {"content":"clean_reminder","minIntervalMinutes":20},
      "background": {"content":"clean_reminder"}
    },
    "content": {
      "clean_reminder": {"titleKey":"app_name","bodyKey":"clean_body","routeId":"clean"}
    }
  },
  "desktop": {
    "style":"CARD",
    "icon":"ic_clean",
    "titleKey":"app_name",
    "bodyKey":"clean_body",
    "routeId":"clean",
    "autoDismissSeconds":0,
    "policy":{"minIntervalMinutes":60,"maxPerDay":3}
  }
}
JSON 样例

各触发项可独立配置频控并选择内容 ID。定时和解锁参考默认 20 分钟,按远端配置覆盖。漏过周期跳过,配置变化后下一周期应用并保留频控历史。桌面间隔及上限的 JSON 数值用于示例,实际值由产品组确认。

每个渠道只合并一个生效产品包,入口固定为 assets/team-push/profile.json。CI 校验 schema、默认语言、引用、入口 ID、路由白名单和图标,并生成资源键到 Android 资源 ID 的索引。运行时再次校验路由。裸 AAR 不携带 Maven 的传递依赖关系,手工接入时同时引入内核 AAR。

05

模式切换与验收

先验证组合状态、异步切换和系统条件,再开始封装。

场景预期结果
首次允许或拒绝通知权限两条路径均到 Launcher 引导;角色未设时进入 App 首页,按实际授权决定是否询问一次。
首次冷启动回访、旋转、从设置返回只有实际退出后的首次冷启动回访有一次补问机会。系统授权或切换角色结果回调不触发回访提示。
角色设为 / 退出 Launcher切入后取消 SDK 的系统推送任务、停止用于该功能的常驻服务并撤下 SDK 自己的通知。退出后撤下桌面通知,按当前授权恢复 App 模式策略。异步发送之前重新校验角色与权限。
授权撤回或通知渠道关闭只停止被禁用的系统通知能力。Launcher 桌面通知仍由角色、桌面可见性和频控判定。
同一次解锁并发、间隔不足、桌面在后台事件令牌去重,串行判定和提交成功次数。桌面不可见、窗口忙或未实际显示不计次。模式切走后丢弃旧请求。
点击与关闭桌面点击进入宿主 ICON 的广告链与目标落地页,保留桌面来源字段。重复点击不重复开页。关闭不跳转。
配置损坏、路由失效或系统限制对应提醒停用,清理功能仍可用。可用模板保留安全的默认入口。先验证布局收起/展开、大字体和低版本兼容。

平台约束

埋点可接入宿主采集器。SDK 统一记录权限请求与结果、候选、实际展示、点击和跳过原因。桌面通知的广告入口按 ICON 处理,展示与点击仍按原始桌面通知来源记录一次。

评审待定 实际频控值和触发范围、前台服务用途,以及退出回访提示的埋点口径。返回系统默认桌面选择并取消时,草案默认回 App 首页。

需求来源 以本次提出的双模式接入为主,核对了参考文档的权限补问、本地投递条件、触发、桌面通知和 FCM。飞书需求参考