@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/doc/callkit/core-sdk/android/offline-push.md

@@ -1,368 +0,0 @@
-在 Android 平台，当您的应用进程被杀死或处于后台时，若收到音视频通话邀请，对方将无法收到任何通知，导致通话无法接通。因此，集成离线推送是确保您的音视频通话功能可用的必要条件（用户呼叫始终在线的 Web 端坐席等特殊情况除外）。本文档将指导您完成 FCM Data Message 的推送集成步骤。即使应用未运行，也能将通话邀请等关键信令送达设备，从而唤醒应用并启动通话界面。
-
-## 开通服务
-
-进入 IM 控制台 > 插件市场，单击**立即购买**或**免费试用**（每个应用可免费试用一次，有效期7天）。
-
-**注意：**
-
-推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您的业务正常使用，请提前 购买/续费。
-
-## 集成建议 [必看]
-
-### 如何选择推送渠道？
-
-由于 FCM 依赖于 Google 服务，请根据您的业务运营区域选择合适的集成策略：
-
-**跨国全球业务（涉及国内外）：**为确保全球范围内消息的触达率，建议同时集成国内各厂商推送服务以及 FCM 推送服务。
-
-**仅限海外市场（不涉及中国大陆）：**无需集成国内厂商服务。请直接参考本文档集成 FCM Data Message 即可。
-
-**仅限中国大陆境内：**无需集成 FCM。请参考集成 Notification，按需集成 **Notification** (小米、华为、OPPO、vivo 等国内厂商) 推送即可。
-
-### 如何提高通话触达率？
-
-根据我们的经验，超过 90% 的用户接不到通话通知的原因是手动关闭了应用的通知权限。为确保通话可达率，我们强烈建议：
-
-1. **审慎发送通知：**避免向用户推送低质量或无关联的通知，减少用户因骚扰而关闭通知权限的可能性。
-
-2. **提供精细控制：**借鉴微信等优秀应用的做法，在应用设置内为用户提供独立的开关，分别控制"Notification"和"FCM Data Message"，而非引导用户去系统设置中一刀切地关闭所有通知。
-
-## 快速接入
-
-### 步骤1：厂商配置
-
-1. 将您自己的应用注册到 FCM 推送平台，得到 **AppID** 和 **AppKey** 等参数以及 `google-services.json` 文件 ，来实现离线推送功能。
-
-2. 登录 即时通信 IM 控制台，在**推送管理** > **接入设置**功能栏，选择 FCM，添加 FCM 的证书，其中，消息类型选择**透传（数据）消息**。
-
-### 步骤2：接入推送插件
-
-1. **添加配置文件：**完成控制台厂商推送信息填写后，下载并添加配置文件到工程。将下载的 `timpush-configs.json` 文件添加到应用模块的 `assets` 目录下，将 `google-services.json` 添加到工程 `app` 目录下。
-
-2. **集成推送插件：**在项目的 `app` 目录下的`build.gradle`文件中添加如下依赖：
-
-```gradle
-implementation "com.tencent.timpush:timpush:latest.release"
-implementation "com.tencent.timpush:fcm:latest.release"
-```
-
-**说明：**
-
-TIMPush 需要集成 IM SDK 在**7.9.5666**版本及以上。TIMPush 的版本号及更新信息，可以在 更新日志 中进行查询。
-
-### 步骤3：工程配置
-
-1. 在项目级 `build.gradle` 文件的 `buildscript` > `dependencies` 下添加以下配置：
-
-```gradle
-buildscript {
-    dependencies {
-        classpath 'com.google.gms:google-services:4.3.15'
-    }
-}
-```
-
-2. 在项目的 `app` 目录下的`build.gradle`文件中添加下方配置
-
-```gradle
-apply plugin: 'com.google.gms.google-services'
-```
-
-3. 在项目的 `app` 目录下，找到并打开`build.gradle`文件，将应用包名修改为您的实际应用包名。
-
-```gradle
-applicationId 'com.****.callkit'
-```
-
-## 自定义来电推送
-
-### 步骤1：监听 FCM 推送
-
-当 FCM 推送唤醒应用时，TIMPush 插件会发送“应用唤醒”广播。收到该广播后，请按以下步骤处理以确保来电通知正常显示：
-
-1. **监听应用唤醒广播：**应用被唤醒，收到 TIMPush 发送的广播。
-
-2. **执行自动登录：**登录后通话服务状态可用，如何登录可参考 [login](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.login/-login-store/login.html)。
-
-```kotlin
-import android.content.BroadcastReceiver
-import android.content.Context
-import android.content.Intent
-import android.content.IntentFilter
-import android.os.Bundle
-import androidx.localbroadcastmanager.content.LocalBroadcastManager
-
-class PushWakeupReceiver : BroadcastReceiver() {
-    override fun onReceive(context: Context?, intent: Intent?) {
-        if (intent?.action == "TIMPush.BROADCAST_IM_LOGIN_AFTER_APP_WAKEUP") {
-            val bundle = intent.getExtras()
-            // 2.执行自动登录
-            // autoLogin()
-        }
-    }
-}
-
-class MainActivity : AppCompatActivity() {
-    private val wakeupReceiver = PushWakeupReceiver()
-    private var callListener: CallListener? = null
-
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        // 1.监听应用唤醒广播
-        observeAppWakeup()
-    }
-
-    private fun observeAppWakeup() {
-        val filter = IntentFilter("TIMPush.BROADCAST_IM_LOGIN_AFTER_APP_WAKEUP")
-        LocalBroadcastManager.getInstance(this).registerReceiver(wakeupReceiver, filter)
-    }
-}
-```
-
-### 步骤2：自定义来电通知样式
-
-您可以使用 `NotificationManager` 通知管理类显示您定制的来电通知界面，实现方式如下：
-
-1. **创建一个来电通知管理类**（`IncomingCallNotificationManager`）：封装推送的创建和显示等逻辑。
-
-2. **自定义来电通知的 UI 样式：**您可以使用 `RemoteViews` 定制通知布局。关于如何使用 `NotificationCompat.Builder` 配置通知的详细参数（如 Channel、PendingIntent、优先级等），请参阅 Android 官方文档： [NotificationCompat.Builder](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder)。
-
-```kotlin
-import android.app.Notification
-import android.app.NotificationChannel
-import android.app.NotificationManager
-import android.content.Context
-import android.content.Intent
-import android.os.Build
-import android.widget.RemoteViews
-import androidx.core.app.NotificationCompat
-
-class IncomingCallNotificationManager(private val context: Context) {
-    private val channelId = "incoming_call_channel"
-    private val channelName = "来电通知"
-    private val notificationId = 1001
-    private var remoteViews: RemoteViews? = null
-    private val notificationManager: NotificationManager =
-        context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
-
-    init {
-        // 1.创建通知渠道
-        createNotificationChannel()
-    }
-
-    private fun createNotificationChannel() {
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            val channel = NotificationChannel(
-                channelId,              // 渠道 ID（唯一标识）
-                "来电通知",              // 渠道名称（用户可见）
-                NotificationManager.IMPORTANCE_HIGH  // 重要性：高优先级
-            ).apply {
-                description = "显示来电通知"  // 渠道描述（用户可见）
-                enableLights(true)          // 启用通知灯
-                enableVibration(true)       // 启用震动
-                setShowBadge(false)         // 不显示角标
-            }
-            notificationManager.createNotificationChannel(channel)
-        }
-    }
-
-    // 2. 显示自定义来电通知的 UI 样式
-    fun showIncomingCallNotification(
-        callerName: String,
-        callerAvatar: Int?, // Bitmap 或 Int (资源 ID)
-        isVideoCall: Boolean
-    ) {
-        // RemoteViews 用于在通知中显示自定义的布局
-        remoteViews = RemoteViews(context.packageName, R.layout.incoming_call_notification)
-
-        // 设置来电者姓名
-        remoteViews?.setTextViewText(R.id.tv_caller_name, callerName)
-
-        // 设置通话类型描述（视频通话 或 语音通话）
-        remoteViews?.setTextViewText(R.id.tv_call_desc, if (isVideoCall) "视频通话" else "语音通话")
-
-        // 设置通话类型图标
-        val callTypeIcon = if (isVideoCall) {R.drawable.ic_video_call} else {R.drawable.ic_audio_call}
-        remoteViews?.setImageViewResource(R.id.img_call_type, callTypeIcon)
-
-        // 设置呼叫用户头像
-        remoteViews?.setImageViewResource(R.id.img_avatar, callerAvatar)
-
-        // 创建通知对象
-        val notification = NotificationCompat.Builder(context, channelId)
-            .setSmallIcon(R.drawable.ic_notification_small)  // 状态栏显示的小图标
-            .setContent(remoteViews)                         // 设置自定义布局
-            .setCustomContentView(remoteViews)               // 标准视图（通知栏收起时）
-            .setCustomBigContentView(remoteViews)            // 展开视图（通知栏展开时）
-            .setOngoing(true)                                // 持续通知（用户无法滑动删除）
-            .setAutoCancel(true)                             // 点击后自动取消
-            .setCategory(NotificationCompat.CATEGORY_CALL)   // 分类为通话通知
-            .setVisibility(NotificationCompat.VISIBILITY_PUBLIC) // 锁屏时可见
-            .setTimeoutAfter(60000)                          // 60秒后自动取消
-            .build()
-
-        notificationManager.notify(notificationId, notification)
-    }
-}
-```
-
-上述来电通知样式的布局文件如下（ `R.layout.incoming_call_notification` ）：
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:layout_width="match_parent"
-    android:layout_height="wrap_content"
-    android:orientation="horizontal"
-    android:padding="16dp"
-    android:background="#FFFFFF"
-    android:gravity="center_vertical">
-
-    <!-- 用户头像 -->
-    <ImageView
-        android:id="@+id/img_avatar"
-        android:layout_width="56dp"
-        android:layout_height="56dp"
-        android:layout_gravity="center_vertical"
-        android:scaleType="centerCrop"
-        android:src="@drawable/callview_ic_avatar"
-        android:background="@drawable/avatar_background" />
-
-    <!-- 用户信息和描述 -->
-    <LinearLayout
-        android:layout_width="0dp"
-        android:layout_height="wrap_content"
-        android:layout_weight="1"
-        android:layout_gravity="center_vertical"
-        android:layout_marginStart="16dp"
-        android:orientation="vertical">
-
-        <TextView
-            android:id="@+id/tv_caller_name"
-            android:layout_width="wrap_content"
-            android:layout_height="wrap_content"
-            android:textSize="18sp"
-            android:textStyle="bold"
-            android:textColor="#212121"
-            android:maxLines="1"
-            android:ellipsize="end"
-            android:text="来电" />
-
-        <LinearLayout
-            android:layout_width="wrap_content"
-            android:layout_height="wrap_content"
-            android:layout_marginTop="6dp"
-            android:orientation="horizontal"
-            android:gravity="center_vertical">
-
-            <ImageView
-                android:id="@+id/img_call_type"
-                android:layout_width="16dp"
-                android:layout_height="16dp"
-                android:src="@drawable/ic_audio_call" />
-
-            <TextView
-                android:id="@+id/tv_call_desc"
-                android:layout_width="wrap_content"
-                android:layout_height="wrap_content"
-                android:layout_marginStart="6dp"
-                android:textSize="14sp"
-                android:textColor="#757575"
-                android:text="语音通话" />
-        </LinearLayout>
-    </LinearLayout>
-</LinearLayout>
-```
-
-### 步骤3：展示来电通知
-
-您需要监听来电事件，登录成功后（步骤1），如果有离线来电事件，**CallStore** 会自动补发，您可以在该事件中显示定制的推送通知（步骤2），实现方式如下：
-
-1. **监听来电事件：**订阅 [onCallReceived](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-listener/on-call-received.html) 事件。该事件在收到来电时触发，并包含通话所需的关键信息。
-
-2. **展示来电通知：**当收到 [onCallReceived](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-listener/on-call-received.html) 事件后，根据该事件携带的通话信息展示通知界面。在 [onCallReceived](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-listener/on-call-received.html) 回调中，根据事件携带的通话信息，并调用自定义的推送通知（参考步骤 2）进行展示。
-
-```kotlin
-class MainActivity : AppCompatActivity() {
-    private val wakeupReceiver = PushWakeupReceiver()
-    private var callListener: CallListener? = null
-
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        // 1.监听来电事件
-        observeCallReceived()
-    }
-
-    private fun observeCallReceived() {
-        callListener = object : CallListener() {
-            override fun onCallReceived(callId: String, mediaType: CallMediaType, userData: String) {
-                super.onCallReceived(callId, mediaType, userData)
-                // 2.显示来电通知
-                showIncomingCallNotification(mediaType)
-            }
-        }
-        callListener?.let { CallStore.shared.addListener(it) }
-    }
-
-    private fun showIncomingCallNotification(mediaType: CallMediaType) {
-        try {
-            val callerName = CallStore.shared.observerState.activeCall.value.inviterId
-            val notificationManager = IncomingCallNotificationManager(this)
-            notificationManager.showIncomingCallNotification(
-                callerName = callerName,
-                callerAvatar = R.drawable.callview_ic_avatar,
-                isVideoCall = mediaType == CallMediaType.Video
-            )
-        } catch (e: Exception) {
-        }
-    }
-}
-```
-
-**onCallReceived 事件详细说明：**当收到来电事件时触发。
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| callId | String | 此次通话的唯一标识。 |
-| mediaType | [CallMediaType](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-media-type/index.html) | 通话媒体类型，用于指定发起音频通话还是视频通话。CallMediaType.Video ：视频通话。CallMediaType.Audio ：语音通话。 |
-
-**activeCall 结构体详细说明：**活跃通话响应式数据，包含通话 ID、主叫 ID 、被叫 ID 列表、通话媒体类型、通话计时等关键信息。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| callId | String | 此次通话的唯一标识。 |
-| roomId | String | 此次通话的房间 ID 。 |
-| inviterId | String | 发起通话用户的 ID 。 |
-| inviteeIds | LinkedHashSet<String> | 被叫用户的 ID 列表。 |
-| chatGroupId | String | 此次通话的群组 ID ，与 Chat 配合使用。 |
-| mediaType | CallMediaType | 此次通话的媒体类型。CallMediaType.Video：视频通话。CallMediaType.Audio：语音通话。 |
-| result | CallDirection | 通话结果/方向。CallDirection.Unknown：未知通话。CallDirection.Missed：未接通话。CallDirection.Incoming：来电通话。CallDirection.Outgoing：拨出通话。 |
-| duration | Long | 通话时长。 |
-| startTime | Long | 通话接通的开始时间。 |
-
-### 运行效果
-
-完成以上 3 步以后，来电通知效果如下：
-
-## 常见问题
-
-若在集成过程中遇到问题，请务必先查阅 插件推送 > 常见问题 进行自助排查。
-
-### 应用被杀死后无法弹出来电界面
-
-确认收到了推送，收不到推送需要确认下 IM 控制台是否正确上传证书。参见文档上述**快速接入**的第一步，看下是否添加正确。
-
-确认控制台选择了 FCM 数据消息，对照上述准备条件的第二步。
-
-确认收到数据消息，过滤日志（关键字：TIMPush），检查下述日志是否有打印记录（如果收不到消息，可以使用 IM 控制台的 排查工具 查看原因）。
-
-确认实现了**自动登录**。自动登录后才会去拉取通话请求，才能显示来电界面。
-
-### 怎样强制使用 FCM 通道？
-
-若您的业务想要强制使用 FCM 通道，可调用以下接口：
-
-```java
-TIMPushManager.getInstance().forceUseFCMPushChannel(true);
-```