@tencent-rtc/mcp 1.4.7 → 1.6.0-beta.1

package/resource/{doc → knowledge}/callkit/core-sdk/flutter/offline-push.md

@@ -1,35 +1,43 @@
-This document provides step-by-step instructions for implementing offline push notifications using the [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) plugin. This solution is ideal for scenarios where **AtomicXCore** is integrated without a user interface.
+This document provides step-by-step instructions for implementing offline push notifications using the [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) plugin. This solution is ideal for scenarios where AtomicXCore is integrated without a user interface.
+
+## Effect Preview
+
+|**Android (FCM)**|**iOS (APNs)**|
+|---------|---------|
+|||
 
 ## Activate the Service
 
-Navigate to the **Chat Console > App Push > Integration Settings**, then click **Purchase Now** or **Free Trial** (each app can try the free trial once, valid for 7 days).
+Navigate to [Chat Console > App Push > Integration Settings](https://console.trtc.io/chat/push-plugin-push-identifier), then click **Purchase Now** or **Free Trial** (each app can try the free trial once, valid for 7 days).
 
 > **Note:**
 >
-> After the push plugin trial or purchase expires, push services (including offline push for standard messages, broadcast/tag push, etc.) will be automatically disabled. To avoid business interruption, please purchase or renew the service in advance.
+
+> After the push plugin trial or purchase expires, push services (including offline push for standard messages, broadcast/tag push, etc.) will be automatically disabled. To avoid business interruption, please [purchase](https://buy.intl.cloud.tencent.com/avc) or [renew](https://console.tencentcloud.com/expense/renewal) the service in advance.
+>
 
 ## Integration Recommendations
 
 ### Choosing a Push Channel
 
 Since FCM depends on Google services, select your integration strategy based on your business's operational region:
-
 - **Global operations (including China and overseas):** For reliable message delivery worldwide, integrate both domestic vendor push services and FCM push services.
+
 - **Overseas-only operations (excluding Mainland China):** Domestic vendor push services are not necessary. Follow this guide to integrate FCM Data Message.
 
 ### Improving Push Delivery Rates
 
 From our experience, over 90% of users miss call notifications because they manually disable app notification permissions. To maximize call notification reach, we recommend:
-
 1. **Send notifications responsibly:** Avoid pushing low-quality or irrelevant notifications that may cause users to disable notification permissions due to spam.
 
-2. **Offer granular notification controls:** Take inspiration from apps like WeChat — provide distinct toggles for **Notification** and **FCM Data Message** in your app settings, rather than advising users to disable all notifications in system settings.
+2. **Offer granular notification controls:** Take inspiration from apps like WeChat—provide distinct toggles for Notification and FCM Data Message in your app settings, rather than advising users to disable all notifications in system settings.
 
 ## Implementation
 
-**Install the plugin:** In your project root directory, run the following command to install the [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) plugin.
+**Install the plugin:**
 
-```bash
+In your project root directory, run the following command to install the [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) plugin.
+``` bash
 flutter pub add tencent_cloud_chat_push
 ```
 
@@ -38,44 +46,46 @@ flutter pub add tencent_cloud_chat_push
 ### Step 1: Vendor Configuration
 
 #### Prerequisites
+1. Register your app on the [FCM Push Platform](https://console.firebase.google.com/u/0/) to obtain your **AppID**, **AppKey**, and the `google-services.json` file required for offline push functionality.
 
-1. Register your app on the [FCM Push Platform](https://console.firebase.google.com/u/0/?hl=en) to obtain your **AppID**, **AppKey**, and the `google-services.json` file required for offline push functionality.
+2. Log in to the [Chat Console](https://console.trtc.io/chat/), go to [**App Push > Integration Settings**](https://console.trtc.io/chat/push-plugin-push-identifier), select FCM, add your FCM certificate, and choose **Data Message** as the message type.
 
-2. Log in to the Chat Console, go to **App Push > Integration Settings**, select **FCM**, add your FCM certificate, and choose **Data Message** as the message type.
+   |Vendor Push Platform|IM Console Configuration|
+   |---------|---------|
+   |||
 
 #### Download and Add Configuration Files
 
-Once you complete the vendor push setup in the console, download and add the configuration files to your project. Place the downloaded `timpush-configs.json` in your app module's `assets` directory, and add `google-services.json` to your `app` directory.
+Once you complete the vendor push setup in the console, download and add the configuration files to your project. Place the downloaded `timpush-configs.json` in your app module's `assets` directory, and add `google-services.json` to your app directory.
+
+|**Select and download timpush-configs.json**|**Download google-services.json**|**Add to your project**|
+|---------|---------|---------|
+||||
 
 ### Step 2: Integrate Android Push Plugin
 
 Add the following dependency to your project's `android/app/build.gradle` file:
-
-**build.gradle.kts:**
-
-```kotlin
+``` java
+// build.gradle.kts
 implementation("com.tencent.timpush:fcm:8.8.7375")
-```
-
-**build.gradle:**
 
-```groovy
+// build.gradle
 implementation "com.tencent.timpush:fcm:latest.release"
 ```
 
 > **Note:**
 >
-> TIMPush requires IM SDK version **7.9.5666** or higher. You can check version and update info in the [Changelog](https://pub.dev/packages/tencent_cloud_chat_push/changelog).
->
-> The dependency version in `build.gradle` must match the version of `tencent_cloud_chat_push`.
+> - TIMPush requires IM SDK version **7.9.5666** or higher. You can check version and update info in the [Changelog](https://pub.dev/packages/tencent_cloud_chat_push/changelog).
+> - The dependency version in `build.gradle` must match the version of `tencent_cloud_chat_push`.
 
 ### Step 3: Project Configuration
 
-In `android/app/src/main`, create a new Application class at the same level as `MainActivity` — for example, `MyApplication`. If you already have a custom Application class, you can reuse it.
+In `android/app/src/main`, create a new Application class at the same level as `MainActivity`, for example, `MyApplication`.
 
-Add the following code to your Application class:
+If you already have a custom Application class, you can reuse it.
 
-```java
+Add the following code to your Application class:
+``` java
 import com.tencent.chat.flutter.push.tencent_cloud_chat_push.application.TencentCloudChatPushApplication;
 
 public class MyApplication extends TencentCloudChatPushApplication {
@@ -88,33 +98,34 @@ public class MyApplication extends TencentCloudChatPushApplication {
 
 > **Note:**
 >
-> If you have an existing Application class, simply extend `TencentCloudChatPushApplication` and ensure `onCreate()` calls `super.onCreate();`.
 
-You also need to update your `MainActivity`. Open `android/app/src/main/AndroidManifest.xml` and add the `android:name` attribute to the `<application>` tag, referencing your custom Application class.
-
-### Step 4: Complete Project Configuration
+> If you have an existing Application class, simply extend `TencentCloudChatPushApplication` and ensure `onCreate()` calls `super.onCreate();`.
+>
 
-In the project-level `build.gradle` file under `buildscript > dependencies`, add:
+You also need to update your MainActivity file:
 
-```groovy
-buildscript {
-    dependencies {
-        classpath 'com.google.gms:google-services:4.3.15'
-    }
-}
-```
+Open `android/app/src/main/AndroidManifest.xml` and add the `android:name` attribute to the `` tag, referencing your custom Application class:
 
-In the `app` directory's `build.gradle` file, add:
+##### 4.Complete Project Configuration
+- In the project-level `build.gradle` file under `buildscript` > `dependencies`, add:
 
-```groovy
-apply plugin: 'com.google.gms.google-services'
-```
+   ``` java
+   buildscript {
+       dependencies {
+           classpath 'com.google.gms:google-services:4.3.15'
+       }
+   }
+   ```
+- In the `app` directory's `build.gradle` file, add:
 
-In the `app` directory's `build.gradle`, set your application package name:
+   ``` java
+   apply plugin: 'com.google.gms.google-services'
+   ```
+- In the `app` directory's `build.gradle`, set your application package name:
 
-```groovy
-applicationId 'com.****.callkit'
-```
+   ``` java
+   applicationId 'com.****.callkit'
+   ```
 
 ## iOS (APNs)
 
@@ -123,16 +134,17 @@ applicationId 'com.****.callkit'
 #### Apply for APNs Certificate
 
 ##### Enable Remote Push for Your App
+1. Log in to the [Apple Developer Center](https://developer.apple.com/account/), click **Certificates, Identifiers & Profiles** or use the sidebar to access the **Certificates, IDs & Profiles** page.
 
-1. Log in to the [Apple Developer Center](https://developer.apple.com/account/), click **Certificates, Identifiers & Profiles** to access the **Certificates, IDs & Profiles** page.
-
-2. Click the **+** button next to **Identifiers**.
+2. Click the **+** button next to Identifiers.
 
 3. You can either create a new AppID or add the `Push Notification` service to your existing AppID.
 
    > **Note:**
    >
+
    > Your app's `Bundle ID` cannot use a wildcard `*`; otherwise, remote push will not work.
+   >
 
 4. Select **App IDs** and click **Continue**.
 
@@ -143,10 +155,9 @@ applicationId 'com.****.callkit'
 7. Check **Push Notifications** to enable remote push.
 
 #### Generating the Certificate
-
 1. Select your AppID and click **Configure**.
 
-2. In the **Apple Push Notification service SSL Certificates** section, you'll see two `SSL Certificate` entries: one for **Development**, one for **Production**.
+2. In the **Apple Push Notification service SSL Certificates** section, you'll see two `SSL Certificate` entries: one for Development, one for Production.
 
 3. Choose **Create Certificate** for the Development environment. The system will prompt you to provide a Certificate Signing Request (CSR).
 
@@ -164,44 +175,50 @@ applicationId 'com.****.callkit'
 
    > **Note:**
    >
+
    > The Production certificate is actually a combined certificate for both Sandbox (Development) and Production environments and can be used for both.
+   >
 
 10. Double-click to open the downloaded Development and Production SSL certificates, which will be imported into Keychain.
 
-11. In **Keychain Access**, under **Login > My Certificates**, right-click to export the newly created Development (`Apple Development IOS Push Service`) and Production (`Apple Push Services`) certificates as `.p12` files.
+11. In Keychain Access, under **Login > My Certificates**, right-click to export the newly created Development (`Apple Development IOS Push Service`) and Production (`Apple Push Services`) certificates as `.p12` files.
+
+   > **Note:**
+   >
 
-    > **Note:**
-    >
-    > Set a password when exporting the `.p12` file.
+   > Set a password when exporting the `.p12` file.
+   >
 
 #### Uploading the Certificate to the Console
-
-1. Log in to the Chat Console.
+1. Log in to the [Chat Console](https://console.trtc.io/chat/).
 
 2. Select your Chat application and go to its **Access Settings**.
 
 3. In **Access Settings**, switch to **iOS**, click **Add Certificate**, select certificate type, upload the iOS certificate (`.p12`), set the certificate password, and click **Confirm**.
 
-> **Note:**
->
-> - Use only English characters for certificate names (avoid brackets or special characters).
-> - You must set a password when uploading the certificate; otherwise, push notifications will not be received.
-> - Certificates for App Store release must be set to **Production** environment; otherwise, push notifications will not be received.
-> - The uploaded `.p12` certificate must be a valid certificate you applied for.
+   > **Note:**
+   >
+>   - Use only English characters for certificate names (avoid brackets or special characters).
+>   - You must set a password when uploading the certificate; otherwise, push notifications will not be received.
+>   - Certificates for App Store release must be set to Production environment; otherwise, push notifications will not be received.
+>   - The uploaded `.p12` certificate must be a valid certificate you applied for.
 
 ### Step 2: Push Parameter Configuration
 
-Upload the iOS APNs push certificate you obtained to the Chat Console. The Chat Console assigns a certificate ID. Register push notifications by passing this certificate ID (`apnsCertificateID`) as follows:
+Upload the iOS APNs push certificate you obtained to the Chat Console.
 
-```dart
-TencentCloudChatPush().registerPush(apnsCertificateID: yourCertificateId);
+The Chat Console assigns a certificate ID. Register push notifications by passing this certificate ID (`apnsCertificateID`) as follows:
+``` java
+TencentCloudChatPush().registerPush(apnsCertificateID: Your certificate ID);
 ```
 
 ### Step 3: Project Configuration
 
-You can use Xcode, Visual Studio Code, or Android Studio for editing. Open `ios/Runner/AppDelegate.swift` and add the highlighted code below:
+You can use Xcode, Visual Studio Code, or Android Studio for editing.
+
+Open `ios/Runner/AppDelegate.swift` and add the code highlighted below. The specific code is provided after the image.
 
-```swift
+``` swift
 import UIKit
 import Flutter
 
@@ -246,42 +263,42 @@ import tencent_cloud_chat_push
 ## Custom Incoming Call Push
 
 ### Step 1: Register the Push Plugin
-
 1. **Register the push plugin immediately after login completes.**
 
-   Call `TencentCloudChatPush().registerPush`, passing the click callback function you previously defined. You may also pass `apnsCertificateID` (iOS certificate ID) and `androidPushOEMConfig` (Android vendor push configuration). These were specified in earlier steps; if unchanged, you can omit them.
+   Call `TencentCloudChatPush().registerPush`, passing the click callback function you previously defined.
 
-```dart
-TencentCloudChatPush().registerPush(
-    onNotificationClicked: _onNotificationClicked,
-    sdkAppId: yourSdkAppId,
-    appKey: "Client secret",
-    apnsCertificateID: yourCertificateId);
-```
+   You may also pass `apnsCertificateID` (iOS certificate ID) and `androidPushOEMConfig` (Android vendor push configuration). These were specified in earlier steps; if unchanged, you can omit them.
 
+   ``` java
+   TencentCloudChatPush().registerPush(
+       onNotificationClicked: _onNotificationClicked,
+       sdkAppId: Your sdkAppId,
+       appKey: "Client secret",
+       apnsCertificateID: Your certificate ID);
+   ```
 2. **Implement Android auto-login.**
 
    FCM's data mode wakes up the offline app, so you also need to implement login and app launch in `onAppWakeUpEvent`.
 
-```dart
-TencentCloudChatPush().registerOnAppWakeUpEvent(onAppWakeUpEvent: () {
-    // TODO: Login operation
-});
-```
+   ``` java
+   TencentCloudChatPush().registerOnAppWakeUpEvent(onAppWakeUpEvent: () {
+         // TODO: Login operation
+   });
+   ```
 
 ### Step 2: Customize Incoming Call Notification Style (FCM)
 
-You can use third-party plugins (such as `flutter_local_notifications`) to display notifications, or create a native `NotificationView` for advanced notification styles. Here, we demonstrate using `flutter_local_notifications`:
+You can use third-party plugins (such as flutter_local_notifications) to display notifications, or create a native `NotificationView` for advanced notification styles. Here, we demonstrate using flutter_local_notifications:
 
-**Integrate the Plugin:**
+#### Integrate the Plugin
 
-```bash
+Add the flutter_local_notifications plugin with:
+``` bash
 flutter pub add flutter_local_notifications
 ```
 
-**Display Notification:**
-
-```dart
+#### Display Notification
+``` java
 final plugin = FlutterLocalNotificationsPlugin();
 
 const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
@@ -305,62 +322,59 @@ await plugin.show(
 ### Step 3: Show Incoming Call Notification (FCM)
 
 You need to listen for incoming call events. After login (Step 1), if there are offline incoming call events, **CallStore** will automatically resend them. You can display custom push notifications (Step 2) for these events:
-
 1. **Listen for incoming call events:** Subscribe to the [onCallReceived](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/flutter/v1.0/en/api_call_call_store/CallEventListener/onCallReceived.html) event. This event is triggered when an incoming call is received and provides call details.
 
-2. **Show incoming call notification:** When the `onCallReceived` event is triggered, display the notification UI using the call information from the event. In the callback, use the event's call data to trigger your custom push notification (see Step 2).
-
-```dart
-import 'package:atomic_x_core/atomicxcore.dart';
-import 'package:flutter_local_notifications/flutter_local_notifications.dart';
-
-bool isNotificationShowing = false;
-
-void showNotification() async {
-  final plugin = FlutterLocalNotificationsPlugin();
-  const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
-  await plugin.initialize(const InitializationSettings(android: androidSettings));
-  await plugin.show(
-    0,                            // Unique notification identifier
-    'Incoming Call',
-    'Zhang San is calling you',
-    const NotificationDetails(
-      android: AndroidNotificationDetails(
-        'call_channel',
-        'Call Notification',
-        importance: Importance.high,
-        priority: Priority.high,
-      ),
-    ),
-  );
-  isNotificationShowing = true;
-}
-
-void closeNotification() {
-  final plugin = FlutterLocalNotificationsPlugin();
-  plugin.cancel(0);               // Unique notification identifier to close
-  isNotificationShowing = false;
-}
-
-CallEventListener? _listener;
-
-void _addNotificationListener() {
-  _listener = CallEventListener(
-    onCallReceived: (callId, mediaType, userData) {
-      showNotification();
-    },
-    onCallEnded: (callId, mediaType, reason, userId) {
-      closeNotification();
-    },
-  );
-  CallStore.shared.addListener(_listener!);
-  CallStore.shared.state.selfInfo.addListener(() {
-    if (isNotificationShowing) {
-      closeNotification();
-    }
-  });
-}
-```
+2. **Show incoming call notification:** When the [onCallReceived](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/flutter/v1.0/en/api_call_call_store/CallEventListener/onCallReceived.html) event is triggered, display the notification UI using the call information from the event. In the callback, use the event's call data to trigger your custom push notification (see Step 2).
+
+   ``` java
+   import 'package:atomic_x_core/atomicxcore.dart';
+   import 'package:flutter_local_notifications/flutter_local_notifications.dart';
+
+   bool isNotificationShowing = false;
+
+   void showNotification() async {
+     final plugin = FlutterLocalNotificationsPlugin();
+     const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
+     await plugin.initialize(settings: const InitializationSettings(android: androidSettings));
+     await plugin.show(
+       id: 0,              // Unique notification identifier
+       title: 'Incoming Call',
+       body: 'Zhang San is calling you',
+       notificationDetails: const NotificationDetails(
+         android: AndroidNotificationDetails(
+           'call_channel',
+           'Call Notification',
+           importance: Importance.high,
+           priority: Priority.high,
+         ),
+       ),
+     );
+     isNotificationShowing = true;
+   }
+   void closeNotification() {
+     final plugin = FlutterLocalNotificationsPlugin();
+     plugin.cancel(
+       id: 0,        // Unique notification identifier to close
+     );
+     isNotificationShowing = false;
+   }
+   void _addNotificationListener() {
+     _listener = CallEventListener(
+       onCallReceived: (callId, mediaType, userData) {
+         showNotification();
+       },
+       onCallEnded: (callId, mediaType, reason, userId) {
+         closeNotification();
+       },
+     );
+     CallStore.shared.addListener(_listener!);
+     CallStore.shared.state.selfInfo.addListener(() {
+       if (isNotificationShowing) {
+         closeNotification();
+       }
+     });
+   }
+   ```
 
 ## FAQs
 
@@ -368,31 +382,40 @@ void _addNotificationListener() {
 
 Apple's deviceToken depends on the current build environment. Please check:
 
-- During integration, ensure the `businessID` used for push parameter configuration matches the certificate ID for the corresponding environment.
-- **Console certificate creation check:**
-    - **Production environment certificate:** Upload as **Apple Push Notification Service SSL (Sandbox & Production)**, and test after archiving a Release build. Do not test directly in Xcode.
-    - **Development environment certificate:** Archive a Release build for testing, and select the correct certificate type when creating.
+During integration, ensure the businessID used for push parameter configuration matches the certificate ID for the corresponding environment.
+
+Console certificate creation check:
+- Production environment certificate: Upload as Apple Push Notification Service SSL (Sandbox & Production), and test after archiving a Release build. Do not test directly in Xcode.
+
+- Development environment certificate: Archive a Release build for testing, and select the correct certificate type when creating.
 
 ### In the iOS development environment, registration sometimes does not return deviceToken or APNs token request fails?
 
 This is typically caused by APNs service instability. Try the following:
-
 1. Insert a SIM card and test using a 4G network.
+
 2. Uninstall and reinstall, restart the app, or reboot the device and retry.
+
 3. Test with a production build.
+
 4. Test on a different iOS device.
 
 ### Incoming call UI does not appear after app is killed?
+- Confirm that push notifications are received. If not, check if the IM console certificate was uploaded correctly. Refer to Step 1 of **Vendor Configuration.**
+
+- Verify that FCM Data Message is selected in the console.
+
+- Check if data messages are being received. Filter logs (keyword: TIMPush) and look for the log shown below.
 
-- Confirm that push notifications are received. If not, check whether the IM console certificate was uploaded correctly. Refer to **Step 1: Vendor Configuration**.
-- Verify that **FCM Data Message** is selected in the console.
-- Check whether data messages are being received. Filter logs (keyword: `TIMPush`) and inspect the corresponding output.
 - Confirm that **auto-login** is implemented. Only after auto-login will call requests be pulled and the incoming call UI displayed.
 
 ### How to force usage of the FCM channel?
 
 To enforce FCM channel usage, call:
-
-```java
+``` java
 TIMPushManager.getInstance().forceUseFCMPushChannel(true);
 ```
+
+## Contact Us
+
+If you have any questions or suggestions during integration or usage, join the [Telegram](https://t.me/+Lmw2MSqW6ethMGM1) technical discussion group or [contact us](https://trtc.io/contact) for support.