实时音视频 Android 通话离线推送接入（海外场景）

说明：
本文档适用于在 海外（Google Play 等）应用市场上架的 App。如果您的 App 仅在中国大陆上架，请参见 Android 通话离线推送接入（中国大陆）。
TUICallKit 组件支持在 App 退到后台或被系统杀死时，通过 FCM（Firebase Cloud Messaging）推送通道唤醒被叫用户，使其能及时收到来电。
集成效果
按照本文档接入后，您的 App 在被杀进程或锁屏状态下也能及时唤醒被叫用户的来电通知：
应用在前台时的显示效果
应用在后台时或者离线时的显示效果
﻿
﻿
﻿
﻿
﻿
﻿
说明：
为获得良好的通话来电体验，建议您引导用户在 App 中开启 “通知”、“显示在其他应用上层”、“后台拉起界面” 等权限。
海外通话离线推送由 FCM（Firebase Cloud Messaging） 下发，需要您先在 Firebase 控制台创建项目并下载 google-services.json。
FCM 需要设备带有 GMS（Google Mobile Services）服务才能工作。中国大陆地区出厂的设备一般不带 GMS，请勿在国内场景下仅依赖 FCM。
如果您的 App 同时面向中国大陆用户，请同时参见 Android 通话离线推送接入（中国大陆） 接入国内厂商通道。
完成选择后，请先阅读 前置准备 章节完成 FCM 项目创建和证书申请，再前往对应方案章节完成接入。
前置准备
需要先在 Firebase 创建项目、把 FCM 凭据上传到 IM 控制台、并把控制台返回的证书 ID 告诉 SDK。
步骤1：创建 Firebase 项目并下载 google-services.json
1. 登录 Firebase 控制台，Add Project 创建新项目（或使用已有项目）。
2. 在项目里 Add an app > Android，输入 App 的包名（必须与您 App 的 applicationId 完全一致）。
3. 下载生成的 google-services.json，放到 App 模块根目录（与 build.gradle 同级）。
4. 进入 Firebase 项目 Project Settings > Cloud Messaging，记录下 Server Key（用于上传到 IM 控制台）。
﻿
﻿
﻿
说明：
如果 Firebase 控制台 Cloud Messaging 标签下找不到 Server Key 入口，请按 Firebase 官方文档启用 Cloud Messaging API（Legacy）。
步骤2：将 FCM 凭据上传到 IM 控制台
﻿打开 IM 控制台 > 选择您的 IM 应用 > 推送服务 > 概览 > 配置厂商证书 。在右侧 Android 标签下，推送类型选择 FCM，添加 FCM 证书，
﻿
说明：
应用包名必须与您 App 的 applicationId 一致。
上传成功后会得到一个 FCM 证书 ID，用于后续 SDK 调用 setCertificateID 时填写。
功能接入
注意：
使用 TIMPush 推送插件首先需要开通 TIMPush 服务（付费/限时免费试用）。
步骤1：开通服务
进入 IM 控制台 > 插件市场，单击立即购买或免费试用（每个应用可免费试用一次，有效期 7 天）。
﻿
注意：
推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您业务正常使用，请提前 购买 / 续费。
步骤2：接入 TIMPush 主包和 FCM 外挂
在 App 模块 build.gradle 中添加：
dependencies {
    implementation 'io.trtc.uikit:atomicx-core:latest.release'
﻿
    // TIMPush 主包（必引）
    implementation 'com.tencent.timpush:timpush:latest.release'
﻿
    // FCM 外挂
    implementation 'com.tencent.timpush:fcm:latest.release'
}
步骤3: 配置应用 google-services Gradle 插件
在工程根目录的 build.gradle 中添加：
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}
在 App 模块的 build.gradle 顶部应用插件：
apply plugin: 'com.google.gms.google-services'
步骤4：下载并添加 TIMPush 配置文件
完成厂商配置后，在腾讯云控制台下载 timpush-configs.json，下载路径为：控制台 > 推送服务 Push > 推送设置 > 厂商配置 > 下载证书，示意图为：
﻿
下载后，将该文件添加到应用模块的 assets 目录。推荐存储路径：app/src/main/assets/timpush-configs.json，其中 app 是您项目的应用模块，可替换成实际名称。如果工程中没有 assets 目录，请在 src/main/ 下手动创建。
注意：
TIMPush 注册推送时会读取该文件中的厂商证书配置，不要放在 MainActivity 同级目录、工程根目录或 res 目录。如果文件缺失或放错目录，SDK 无法获得对应厂商通道配置，可能导致注册或收消息失败。
步骤5：实现自动登录
方案二在 App 被推送唤起时，TIMPush 会通过 TUICore 事件总线发出登录通知。您需要在 Application 中监听该事件并实现自动登录逻辑，否则被叫端在应用被杀死后无法拉起来电 UI。
import com.tencent.qcloud.tuicore.TUIConstants;
import com.tencent.qcloud.tuicore.TUICore;
import com.tencent.qcloud.tuicore.interfaces.ITUINotification;
﻿
TUICore.registerEvent(
    TUIConstants.TIMPush.EVENT_IM_LOGIN_AFTER_APP_WAKEUP_KEY,
    TUIConstants.TIMPush.EVENT_IM_LOGIN_AFTER_APP_WAKEUP_SUB_KEY,
    new ITUINotification() {
        @Override
        public void onNotifyEvent(String key, String subKey, Map<String, Object> param) {
            if (TUIConstants.TIMPush.EVENT_IM_LOGIN_AFTER_APP_WAKEUP_KEY.equals(key)
                    && TUIConstants.TIMPush.EVENT_IM_LOGIN_AFTER_APP_WAKEUP_SUB_KEY.equals(subKey)) {
                // 实现您的自动登录逻辑（拉起通话页面前必须先完成 IM 登录）
                autoLogin();
            }
        }
    }
);
说明：
该事件由 TIMPush 主包在用户点击通知横幅唤起 App 时发出。
TIMPush 主包通过 ServiceInitializer 机制自动初始化，并在 IM 登录成功后自动 registerPush 拿 token，业务侧无需手动调用任何初始化方法。
步骤6：拨打通话
AtomicXCore 的 CallStore 在发起通话时自动携带离线推送参数，您不需要手动设置任何 offlinePushInfo 字段。默认推送内容如下：
字段
默认值
推送标题
主叫用户的 ID。
推送描述
中文环境下为「您有新的来电」，其它语言为「You have a new call」。
铃声
SDK 内置铃声。
如果您想自定义推送标题或描述，可在发起通话时通过 CallParams 传入 offlinePushTitle / offlinePushDescription，传入后会覆盖上述默认值。
import io.trtc.tuikit.atomicxcore.api.call.CallStore
import io.trtc.tuikit.atomicxcore.api.call.CallParams
import io.trtc.tuikit.atomicxcore.api.call.CallMediaType
﻿
val params = CallParams().apply {
    timeout = 30                              // 超时时间（秒）
    userData = "自定义数据"                    // 扩展信息（可选）
﻿
    // 可选：自定义离线推送标题和描述（不填则使用默认值）
    offlinePushTitle = "Alice"
    offlinePushDescription = "is calling you"
}
﻿
val userIdList = listOf("被叫用户的 userID")
﻿
CallStore.shared.calls(
    participantIds = userIdList,
    mediaType = CallMediaType.VIDEO,           // VIDEO 视频通话，AUDIO 语音通话
    params = params
) { result ->
    if (result.isSuccess) {
        // 通话发起成功，跳转到您自己的通话页面
    } else {
        // 通话失败处理
    }
}
高级功能
自定义铃声
如果您想自定义该铃声，可以替换 tuicallkit-kt/src/main/res/raw/phone_ringing.mp3 文件。
注意：
替换掉该铃声后，不论应用在前台、后台或者离线，铃声都会是替换后的铃声。
替换后其他厂商手机收到邀请后的铃声也会是替换后的铃声。
常见问题
通用问题
收不到推送，如何排查？
按以下顺序逐项排查：
1. 检查 IM 控制台：FCM 证书是否上传成功，消息类型是否选择“透传（数据）消息”（不能选“通知消息”）。
2. 检查应用包名（applicationId）：必须与 Firebase 项目里注册的包名一致，与 IM 控制台上传证书时填的包名一致。
3. 检查 google-services.json：是否放到 App 模块根目录、应用了 com.google.gms.google-services 插件。
4. 检查设备 GMS 环境：FCM 需要设备带有 Google Mobile Services。可以装一个测试 App（比如 Google Play 商店）确认 GMS 可用。
5. 检查通知权限：在系统设置中确认您的 App 已授予“通知”权限（Android 13+ 需要在运行时申请）。
6. 过滤 Logcat 关键字 [PushManager] 和 [ChannelManager] ：查看 SDK 实际调用的 FCM 通道及返回结果。
应用被杀死后无法弹出来电 UI，怎么办？
如果已经收到推送但没有弹出来电 UI，按以下顺序排查：
1. 确认收到数据消息：过滤 Logcat 关键字 TIMPush，确认有收到 FCM 透传消息的日志打印。如果没收到，说明卡在推送下发环节，请按 常见问题：收不到推送，如何排查？ 排查。
2. 确认应用已实现自动登录：SDK 收到推送后会自动尝试拉取通话请求，但拉取依赖 IM 已登录态。如果应用被杀进程后没有实现自动登录，SDK 拉不到通话请求，自然也不会显示来电 UI。建议在应用启动入口或 Application.onCreate 中实现 IM 自动登录逻辑。
3. 确认权限：部分厂商系统需要授予“显示在其他应用上层”、“后台拉起界面”权限才能在被杀状态下弹出来电 UI，请引导用户在系统设置中开启。
中国大陆用户能用 FCM 吗？
通常不能。中国大陆出厂的设备一般不带 GMS（Google Mobile Services），FCM 服务无法连接到 Google 推送服务器。如果您的 App 同时面向国内用户，请同时参见 Android 通话离线推送接入（中国大陆）接入国内厂商通道。SDK 会根据设备类型自动选择对应通道，无需手动判断。
我的 App 同时面向国内和海外，需要分别打两个包吗？
不需要。同一个 App 可以同时引入国内厂商外挂和 FCM 外挂，并在 setCertificateID 中一次性填入所有证书 ID：
LoginStore.shared.setCertificateID(
    mapOf(
        // 国内
        "huaweiCertificateId" to "12345",
        "xiaomiCertificateId" to "12345",
        "xiaomiAppId" to "...",
        "xiaomiAppKey" to "...",
        // ... 其他国内厂商
﻿
        // 海外
        "fcmCertificateId" to "12345"
    )
)
SDK 会根据当前设备品牌自动选择对应的通道，国内设备走国内厂商通道，海外设备走 FCM。
如何确认 TIMPush 推送链路是否正常工作？
过滤 Logcat 关键字 TIMPush，关注这几条日志：
register success：FCM 通道注册 token 成功
setOfflinePushConfig success：token 上报到 IM 后台成功
主叫端发起呼叫后，被叫端日志中出现 onReceiveNotificationMessage：表示已收到推送
如果某一段日志缺失，请按 常见问题：收不到推送，如何排查？ 的顺序排查。
交流与反馈
如有问题，可以 联系我们，进行技术交流和产品沟通。
应用在前台时的显示效果	应用在后台时或者离线时的显示效果
字段	默认值
推送标题	主叫用户的 ID。
推送描述	中文环境下为「您有新的来电」，其它语言为「You have a new call」。
铃声	SDK 内置铃声。
Android 通话离线推送接入（海外场景）

本页目录：

集成效果

前置准备

步骤1：创建 Firebase 项目并下载 google-services.json

步骤2：将 FCM 凭据上传到 IM 控制台

功能接入

步骤1：开通服务

步骤2：接入 TIMPush 主包和 FCM 外挂

步骤3: 配置应用 google-services Gradle 插件

步骤4：下载并添加 TIMPush 配置文件

步骤5：实现自动登录

步骤6：拨打通话

高级功能

自定义铃声

常见问题

通用问题

收不到推送，如何排查？

应用被杀死后无法弹出来电 UI，怎么办？

中国大陆用户能用 FCM 吗？

我的 App 同时面向国内和海外，需要分别打两个包吗？

如何确认 TIMPush 推送链路是否正常工作？

交流与反馈
