第3章：SplitInstall请求构建与参数调优

动态交付请求的构建质量直接决定模块下载的成功率、安装时效性和用户体验。本章围绕 InstallRequest 的核心构建流程，深入剖析语言/地区条件、延迟选项、回调监听、超时设置四项关键参数的调优策略，并结合调试手段与常见错误案例，提供可直接落地的稳定性提升方案。

3.1 InstallRequest 构建原理与流程

SplitInstallRequest 是动态交付的请求载体，开发者通过 Builder 模式装配模块标识和条件约束。请求构建分为四个阶段：

1. 模块指定：通过 addModule() 添加一个或多个特性模块名。
2. 条件注入：语言、地区、延迟策略等过滤条件在 Builder 中注册。
3. 回调注册：绑定 SplitInstallStateUpdatedListener 监听全程状态。
4. 超时绑定：通过 SplitInstallClient 配置请求级别超时。

3.2 语言/地区条件配置

Play Core 提供 setLanguage() 和 setRegion() 方法，使动态模块仅在特定语言或地区环境下才被允许下载或触发安装。注意：条件不是过滤，而是“许可” – 若未设置，则所有用户均可获取；若设置，则仅匹配的用户才会在请求中被视为有效。

3.3 延迟选项（Deferred Install）

延迟安装允许模块在后台静默下载，在用户下次重启应用时自动安装。通过 setDeferredInstall() 标记请求为延迟模式。参数调优建议：

• 延迟 vs 即时：核心功能模块应使用即时请求（默认），非关键资源（如主题包）使用延迟请求以减少前台等待。
• 网络条件：延迟请求默认仅在 Wi-Fi 下下载，可通过 setRequireCharging(true) 限制充电条件，避免耗电。
• 批量延迟：多个延迟模块建议合并为一个请求，利用 addModule() 批量添加，减少系统调度开销。

3.4 回调监听与状态机

注册监听器后，SessionState 会依次经历：PENDING → DOWNLOADING → INSTALLING → INSTALLED。监听器必须处理 REQUIRES_USER_CONFIRMATION 状态，调用 showConfirmationDialog() 获取用户授权。

SplitInstallClient client = SplitInstallClientFactory.create(context);
SplitInstallStateUpdatedListener listener = state -> {
    switch (state.status()) {
        case SplitInstallSessionStatus.PENDING:
            log("请求排队中");
            break;
        case SplitInstallSessionStatus.DOWNLOADING:
            log("下载中 " + state.bytesDownloaded() + "/" + state.totalBytesToDownload());
            break;
        case SplitInstallSessionStatus.INSTALLED:
            log("安装完成");
            break;
        case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
            state.resolutionIntent().
                addOnSuccessListener(intent -> client.showConfirmationDialog(activity, intent));
            break;
        case SplitInstallSessionStatus.FAILED:
            log("失败: " + state.errorCode());
            break;
    }
};
client.registerListener(listener);

3.5 超时设置与防卡死

Play Core 不提供直接的请求超时 API，但可通过 SplitInstallClient 的 setTimeoutMillis(long) 设置会话超时。建议配置 60 秒，避免长时间占用资源。

SplitInstallClientConfig config = SplitInstallClientConfig.newBuilder()
    .setLanguage(Locale.getDefault().toLanguageTag())
    .setTimeoutMillis(60000)   // 60 秒超时
    .build();
SplitInstallClient client = SplitInstallClientFactory.create(context, config);

若超时后模块仍未完成，会触发 ERROR_SESSION_NOT_FOUND 或 ERROR_TIMEOUT（需结合客户端重试逻辑）。

3.6 调试与部署建议

• 使用 adb shell am broadcast -a com.google.android.play.core.splitinstall.action.SPLIT_INSTALL 触发测试安装。
• 在 build.gradle 中设置 splitDimension 的 language 和 region，确保本地测试时条件与正式环境一致。
• 部署前使用 SplitInstallManager 的 getInstalledModules() 验证模块已存在，避免重复请求。

3.7 常见错误与稳定性优化