@tencent-rtc/mcp 1.4.7 → 1.6.0

package/resource/knowledge/push/integration/ios.md

@@ -0,0 +1,246 @@
+> **Note:**
+>
+
+> If you need to use products like Chat, CallKit, RoomKit, LiveKit simultaneously, please refer to [Chat Quick Integration Solution](https://www.tencentcloud.com/document/product/1047/50033).
+>
+
+### Step 1: Integrate TIMPush
+1. The TIMPush component supports CocoaPods integration. You need to add the component dependencies in the Podfile.
+
+   ``` objectivec
+   target 'YourAppName' do
+     # Uncommment the next line if you're using Swift or would like to use dynamic frameworks
+     use_frameworks!
+     use_modular_headers!
+
+     # Pods for Example
+     pod 'TXIMSDK_Plus_iOS_XCFramework'
+     # The version number "VERSION" can be obtained from the .
+     pod 'TIMPush', 'VERSION'
+   end
+   ```
+2. Run the following command to install the TIMPush component.
+
+   ``` bash
+   pod install
+   # If you cannot install the latest version of TUIKit, run the following command to update your local CocoaPods repository list.
+   pod repo update
+   ```
+
+### Step 2: Set push parameters
+1. After you upload a certificate to the Chat console, the Chat console will assign a certificate ID to you, as shown below.
+
+2. You need to implement the `- businessID` protocol method in AppDelegate to return the certificate ID.
+
+【Objective-C】
+``` objectivec
+#pragma mark - TIMPush
+- (int)businessID {
+    // businessID provided by the back console
+    int  kBusinessID = 0;
+    return kBusinessID;
+}
+
+- (NSString *)applicationGroupID {
+    //AppGroup ID
+    return kTIMPushAppGroupKey;
+}
+
+- (BOOL)onRemoteNotificationReceived:(NSString *)notice {
+    // custom navigate
+    return NO;
+}
+```
+
+【Swift】
+``` swift
+#pragma mark - TIMPush
+//Swift must carry the @objc keyword
+@objc func businessID() -> Int32 {
+    // Certificate ID provided by the back console
+    return 0
+}
+@objc func applicationGroupID() -> String {
+    //AppGroup ID
+    return "group.com.yourcompony.pushkey"
+}
+@objc func onRemoteNotificationReceived(_ notice: String?) -> Bool {
+    // custom navigate
+    return false
+}
+```
+
+### Step 3: Register for Push
+
+ After the push registration is successful through the API call, offline push notifications can be received.
+
+【Objective-C】
+``` objectivec
+ const int sdkAppId = your sdkAppId;
+ static const NSString *appKey = @"Client Key";
+
+ [TIMPushManager registerPush:sdkAppId appKey:appKey succ:^(NSData * _Nonnull deviceToken) {
+
+   } fail:^(int code, NSString * _Nonnull desc) {
+
+ }];
+```
+
+【Swift】
+``` swift
+let sdkAppId: Int = 0
+let appKey: String = "Client Key"
+
+TIMPushManager.registerPush(Int32(sdkAppId), appKey: appKey, succ: { deviceToken in
+    // success
+}, fail: { code, desc in
+    // failed
+})
+```
+
+> **Note:**
+>
+> 1. After you log in, when you see the APNs configuration success log printed on the console, it indicates that the integration is successful.
+> 2. If your app has obtained push permissions, you can receive remote push notifications when the app is moved to the background or the process is killed.
+
+### Step 4: Push Delivery Rate Statistics
+1. If you need to collect data on push delivery and click rates, you need to implement the `- applicationGroupID` method in the `AppDelegate.m` file and get the App Group ID ([the generation method can be referred to in Vendor Configuration - Generating App Group ID](https://www.tencentcloud.com/document/product/1047/60548#ae5590eb-b974-4226-9f1b-720fb0201c85)).
+
+2. Call the push delivery rate statistics function in the Notification Service Extension's `-didReceiveNotificationRequest:withContentHandler:` method.
+
+【Objective-C】
+``` objectivec
+@implementation NotificationService
+- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
+    //appGroup identifies the app group shared between the main app and extension. It needs to be configured in the App Groups capability of the main app.
+    //Format: group + [mainBundleID] + key
+    //E.g., group.com.tencent.im.pushkey
+    NSString * appGroupID = kTIMPushAppGroupKey;
+    __weak typeof(self) weakSelf = self;
+    [TIMPushManager handleNotificationServiceRequest:request appGroupID:appGroupID callback:^(UNNotificationContent *content) {
+        weakSelf.bestAttemptContent = [content mutableCopy];
+        // Modify the notification content here...
+        // self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
+        weakSelf.contentHandler(weakSelf.bestAttemptContent);
+    }];
+}
+@end
+```
+
+【Swift】
+``` swift
+override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
+    self.contentHandler = contentHandler
+    bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+    //appGroup identifies the app group shared between the main app and extension. It needs to be configured in the App Groups capability of the main app.
+    //Format: group + [mainBundleID] + key
+    //E.g., group.com.tencent.im.pushkey
+    TIMPushManager.handleNotificationServiceRequest(request: request, appGroupID: "appGroupID") {
+        [weak self] content  in
+        if let bestAttemptContent = self?.bestAttemptContent {
+            // Modify the notification content here...
+            bestAttemptContent.title = "\(bestAttemptContent.title) [modified]"
+            contentHandler(bestAttemptContent)
+        }
+    }
+}
+```
+
+   > **Note:**
+   >
+>   3. To report push delivery data, enable the mutable-content switch to support iOS 10's extension feature.
+
+>   4. Data details can be viewed on the Push Data Page. The Push Data Page can only be used after [purchasing the Push Plugin](https://buy.cloud.tencent.com/avc).
+
+### Step 5: **Verify Connection**
+
+Run the App, filter logs using the keyword "TIMPush", and check the related logs:
+
+If logs similar to the image above appear, it indicates that Push has been successfully integrated, and you can proceed to the next step.
+
+### Step 6: Send push notifications
+
+Detailed usage instructions can be found at: [RESTful APIs - Initiate All-staff/Tag Push](https://www.tencentcloud.com/document/product/1047/60561).
+
+### Step 7: Click Custom Redirect after offline push
+
+If you need to customize the parsing of received remote push notifications, you can implement it as follows:
+
+【Custom click redirect implementation】
+
+> **Note:**
+>
+
+> It is recommended to place the registration callback timing in the didFinishLaunchingWithOptions function of the AppDelegate.
+>
+
+【Objective-C】
+``` objectivec
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+    [TIMPushManager addPushListener:self];
+    return YES;
+}
+#pragma mark - TIMPushListener
+- (void)onNotificationClicked:(NSString *)ext {
+        // Getting ext for Definition redirect
+}
+```
+
+【Swift】
+``` swift
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    // Override point for customization after application launch.
+    TIMPushManager.addPushListener(listener: self)
+    return true
+}
+
+@objc func onNotificationClicked(_ ext: String) {
+    //Clicked
+}
+@objc func onRecvPushMessage(_ message: TIMPushMessage) {
+    //onRecvPushMessage
+}
+@objc func onRevokePushMessage(_ messageID: String) {
+    //onRevokePushMessage
+}
+```
+
+【Custom click redirect implementation (old solution)】
+
+You need to implement the `- onRemoteNotificationReceived` method in the AppDelegate.m file.
+
+【Objective-C】
+``` objectivec
+#pragma mark - TIMPush
+
+- (BOOL)onRemoteNotificationReceived:(NSString *)notice {
+    //- If YES is returned, TIMPush will not execute the built-in TUIKit offline push parsing logic, leaving it entirely to you to handle.
+    //NSString *ext = notice;
+    //OfflinePushExtInfo *info = [OfflinePushExtInfo createWithExtString:ext];
+    //return YES;
+
+    //- If NO is returned, TIMPush will continue to execute the built-in TUIKit offline push parsing logic and continue to callback - navigateToBuiltInChatViewController:groupID: method.
+    return NO;
+}
+```
+
+【Swift】
+``` swift
+@objc func onRemoteNotificationReceived(_ notice: String) -> Bool {
+    //- If YES is returned, TIMPush will not execute the built-in TUIKit offline push parsing logic, leaving it entirely to you to handle.
+    // let ext = notice
+    // let info = OfflinePushExtInfo.create(withExtString: ext)
+    // return true
+
+    //- If false is returned, TIMPush will continue to execute the built-in TUIKit offline push parsing logic and continue to callback - navigateToBuiltInChatViewController:groupID: method.
+    return false
+}
+```
+
+### Regarding All-staff/Tag Push
+
+All-staff/Tag Push supports sending specific content, and also allows for the delivery of personalized content to specific user groups based on Tag, attribute, such as Membership Activities, Regional Notifications, etc. It aids in User Acquisition, Conversion, Activation Promotion, and other operational work phases, while also supporting Push Delivery Reports, Self-service Push Troubleshooting Tool. For more details, please see [Effect Display](https://www.tencentcloud.com/document/product/1047/60541).
+
+For more detailed content, it is recommended to refer to [All-staff/Tag Push](https://www.tencentcloud.com/document/product/1047/60561).
+
+Congratulations on completing the integration of the Push Plugin. Please note: After the **trial or purchase expiry of the Push Plugin, push services (including regular message offline push, all-staff push, etc.) will be automatically stopped**. To avoid affecting the normal use of your business, please [purchase](https://buy.cloud.tencent.com/avc)/[renew](https://buy.cloud.tencent.com/avc) in advance.

package/resource/knowledge/push/integration/react-native.md

@@ -0,0 +1,366 @@
+### Effect Showcase
+| Xiaomi 11 Pro (Integrated with <a href="https://ext.dcloud.net.cn/plugin?id=9035">CallKit</a>) | iPhone 13 | Samsung Galaxy A23 Overseas Version (Google FCM Push) |
+| --- | --- | --- |
+
+### Step 1: Create a React Native project (skip this step if you already have one)
+``` bash
+npx @react-native-community/cli@latest init MyReactNativeApp --version 0.75.0
+```
+
+### Step 2: **Entering the MyReactNativeApp Directory**, Integrating @tencentcloud/react-native-push
+
+【npm】
+``` bash
+npm install @tencentcloud/react-native-push --save
+```
+
+【yarn】
+``` bash
+yarn add @tencentcloud/react-native-push
+```
+
+### Step 3:**Register for Push Notifications**
+
+Copy the following code to `App.tsx` and replace `SDKAppID` and `appKey` with your application's information.
+
+> **Note:**
+>
+
+> After successfully registering the push service with `registerPush`, you can obtain the push ID, namely RegistrationID, through `getRegistrationID`. You can push messages to the specified RegistrationID.
+>
+
+``` javascript
+import Push from '@tencentcloud/react-native-push';
+
+const SDKAppID = 0; // Your SDKAppID
+const appKey = ''; // Client Key
+
+if (Push) {
+  // If you need to connect with the Chat login userID (i.e., push messages to this userID),
+  // please use the setRegistrationID API
+  // Push.setRegistrationID(userID, () => {
+      // console.log('setRegistrationID ok', userID);
+  // });
+
+  Push.registerPush(SDKAppID, appKey, (data) => {
+      console.log('registerPush ok', data);
+      Push.getRegistrationID((registrationID) => {
+        console.log('getRegistrationID ok', registrationID);
+      });
+    }, (errCode, errMsg) => {
+      console.error('registerPush failed', errCode, errMsg);
+    }
+  );
+
+  // Listen for notification bar click events to get push extension information
+  Push.addPushListener(Push.EVENT.NOTIFICATION_CLICKED, (res) => {
+    // res is the push extension information
+    console.log('notification clicked', res);
+  });
+
+  // Listen for online push
+  Push.addPushListener(Push.EVENT.MESSAGE_RECEIVED, (res) => {
+    // res is the message content
+    console.log('message received', res);
+  });
+
+  // Listen for online push recall
+  Push.addPushListener(Push.EVENT.MESSAGE_REVOKED, (res) => {
+    // res is the ID of the recalled message
+    console.log('message revoked', res);
+  });
+}
+```
+
+### Step 4: Configuring Vendor Push
+
+【Android】
+1. After completing the vendor push information in the console, download the `timpush-configs.json` file from the console and add it to the `MyReactNativeApp/android/app/src/main/assets` directory of the project. If this directory does not exist, please create it manually. As shown in the figure:
+
+2. Huawei, HONOR, vivo, FCM.
+
+【FCM】
+
+When you need to support FCM push, you must configure the `google-services.json` file in the `MyReactNativeApp/android/app` directory (**Please note! Not in the **`MyReactNativeApp/android/app/src/main/assets directory`). As shown in the picture:
+
+【Huawei】
+
+【HONOR】
+3. To support HONOR Push, you need to configure `appID` in the `MyReactNativeApp/android/app/build.gradle` file. As shown in the figure:
+
+``` bash
+......
+android {
+    ......
+    defaultConfig {
+        ......
+        manifestPlaceholders = [
+          "HONOR_APPID" : ""
+        ]
+    }
+}
+```
+
+|Obtain HONOR appID|Configure HONOR appID|
+|---------|---------|
+|||
+
+4. Download the `mcs-services.json` file from the [Honor Developer Management Center](https://developer.honor.com/en/), and configure it in the `MyReactNativeApp/android/app` directory (**Please note! Not in the **`MyReactNativeApp/android/app/src/main/assets directory` directory).
+
+【vivo】
+
+To support vivo Push, you need to configure `appID` and `appKey` in the `MyReactNativeApp/android/app/build.gradle` file. As shown in the figure:
+``` bash
+......
+android {
+    ......
+    defaultConfig {
+        ......
+        manifestPlaceholders = [
+          "VIVO_APPKEY" : "0",
+          "VIVO_APPID" : "0",
+        ]
+    }
+}
+```
+
+|Obtain vivo appID && appKey|Configure vivo appID && appKey|
+|---------|---------|
+|||
+
+【iOS】
+5. Please upload the iOS APNs Push Certificate obtained in the manufacturer configuration step to the Chat Console. The Chat Console will assign a Certificate ID to you, as shown in the figure:
+
+6. In the `MyReactNativeApp/ios/MyReactNativeApp` directory, create a new `Resources` folder and a new `timpush-configs.json` file. Edit `timpush-configs.json` and enter the certificate ID obtained from the console, as shown below:
+
+``` javascript
+{
+  "businessID": "Your Certificate ID"
+}
+```
+
+7. Open the MyReactNativeApp project in XCode, right-click the project > **Add Files to "MyReactNativeApp"**, and add the `timpush-configs.json` directory to the project. As shown in the figure:
+
+### Step 5: **Configuring Native Modules and Dependencies**
+
+【Android】
+
+> **Note:**
+>
+
+> Please ensure the package name in `timpush-configs.json` matches the `applicationId` value in `MyReactNativeApp/android/app/build.gradle`. Inconsistency will result in offline push notifications being unavailable.
+>
+
+1. Open the `MyReactNativeApp/android` directory with Android Studio.
+
+2. Modify the project entry file.
+
+【The project entry file is: MainApplication.kt】
+``` java
+...
+import com.tencent.qcloud.rntimpush.TencentCloudPushApplication
+
+// Replace Application with TencentCloudPushApplication
+class MainApplication : TencentCloudPushApplication(), ReactApplication {
+  ...
+  //  add TencentCloudPushPackage to the list of packages returned in ReactNativeHost's getPackages() method
+  override fun getPackages(): List<ReactPackage> =
+    PackageList(this).packages.apply {
+        // Packages that cannot be autolinked yet can be added manually here, for example:
+        // add(MyReactNativePackage())
+    }
+}
+```
+
+【The project entry file is: MainApplication.java】
+``` java
+...
+import com.tencent.qcloud.rntimpush.TencentCloudPushApplication;
+
+// Replace Application with TencentCloudPushApplication
+public class MainApplication extends TencentCloudPushApplication implements ReactApplication {
+  ...
+  // add TencentCloudPushPackage to the list of packages returned in ReactNativeHost's getPackages() method
+  @Override
+  protected List<ReactPackage> getPackages() {
+    List<ReactPackage> packages = new PackageList(this).getPackages();
+    // Packages that cannot be autolinked yet can be added manually here, for example:
+    // packages.add(new MyReactNativePackage());
+    return packages;
+  }
+  ...
+```
+3.  Edit the `android/build.gradle` file to update `repositories`, `dependencies`, and `allprojects`.
+
+``` java
+buildscript {
+    ...
+    repositories {
+        ...
+        google()
+        mavenCentral()
+        maven { url 'https://mirrors.tencent.com/nexus/repository/maven-public/' }
+        // Configure the Maven repository address for HMS Core SDK.
+        maven { url 'https://developer.huawei.com/repo/' }
+        maven { url 'https://developer.hihonor.com/repo' }
+    }
+    dependencies {
+        ...
+        // If the com.android.tools.build:gradle in your created project does not have a version number, set it to 8.5.0
+        // classpath("com.android.tools.build:gradle:8.5.0")
+        classpath 'com.google.gms:google-services:4.3.15'
+        classpath 'com.huawei.agconnect:agcp:1.9.1.301'
+        classpath 'com.hihonor.mcs:asplugin:2.0.1.300'
+    }
+}
+allprojects {
+    repositories {
+        mavenCentral()
+        maven { url 'https://mirrors.tencent.com/nexus/repository/maven-public/' }
+        // Configure the Maven repository address for HMS Core SDK.
+        maven { url 'https://developer.huawei.com/repo/' }
+        maven { url 'https://developer.hihonor.com/repo' }
+    }
+}
+...
+```
+4.  Edit the `android/app/build.gradle` file, configure the vendor's push package as needed, and apply the plugin.
+
+``` javascript
+...
+// If your APP requires FCM push notifications, uncomment the following line
+// apply plugin: 'com.google.gms.google-services'
+// If your APP requires Huawei push notifications, uncomment the following line
+// apply plugin: 'com.huawei.agconnect'
+// If your APP requires HONOR push notifications, uncomment the following line
+// apply plugin: 'com.hihonor.mcs.asplugin'
+...
+android {
+    ...
+    defaultConfig {
+        ...
+        manifestPlaceholders = [
+            "VIVO_APPKEY" : "0", // If your App requires vivo push notifications, please configure 'VIVO_APPKEY' and 'VIVO_APPID'
+            "VIVO_APPID" : "0",
+            "HONOR_APPID" : "" // If your APP requires HONOR push notifications, please configure 'HONOR_APPID'
+        ]
+    }
+}
+
+dependencies {
+  ...
+  // Please import all or part of the following vendor push packages as needed.
+  // Only by importing the push package of the corresponding vendor
+  // can you enable the native push capability of that vendor.
+  implementation 'com.tencent.timpush:huawei:8.3.6498'
+  implementation 'com.tencent.timpush:xiaomi:8.3.6498'
+  implementation 'com.tencent.timpush:oppo:8.3.6498'
+  implementation 'com.tencent.timpush:vivo:8.3.6498'
+  implementation 'com.tencent.timpush:honor:8.3.6498'
+  implementation 'com.tencent.timpush:meizu:8.3.6498'
+  implementation 'com.tencent.timpush:fcm:8.3.6498'
+}
+```
+5. After completing the above steps, select **File > Sync Project with Gradle Files**.
+
+【iOS】
+6. Open **MyReactNativeApp/ios/MyReactNativeApp.xcworkspace** with XCode.
+
+7. Go to the `MyReactNativeApp/ios` directory and install TIMPush.
+
+``` bash
+pod install
+# If you cannot install the latest version, run the following command to update your local CocoaPods repository list
+pod repo update
+```
+8. Enable push notification feature in the app. Open the Xcode project, and select and add **Push Notifications** on the **Project > Target > Capabilities** page.
+
+### Step 6: **Running on a Real Device (Make sure to enable notification permissions on your phone before testing, allowing the app to send notifications.)**
+
+Starting from the project's root directory, run the following command in the command prompt to install and launch your app on the device:
+
+【Android】
+``` bash
+npm run android
+```
+
+【iOS】
+``` bash
+npm run ios
+```
+
+### Step 7: Message Push Reach Statistics
+
+If you need to collect data on delivery, please complete the setup as follows:
+
+【Huawei】
+
+**Receipt Address:**
+- Singapore : https://apisgp.im.qcloud.com/v3/offline_push_report/huawei
+
+- Korea: https://apikr.im.qcloud.com/v3/offline_push_report/huawei
+
+- USA: https://apiusa.im.qcloud.com/v3/offline_push_report/huawei
+
+- Germany: https://apiger.im.qcloud.com/v3/offline_push_report/huawei
+
+- Indonesia: https://apiidn.im.qcloud.com/v3/offline_push_report/huawei
+
+- China: https://api.im.qcloud.com/v3/offline_push_report/huawei
+
+> **Note:**
+>
+
+> Huawei Push Certificate ID <= 11344, using Huawei Push v2 version interface does not support reach and click receipt, please regenerate and update the certificate ID.
+>
+
+【HONOR】
+
+**Receipt Address:**
+- Singapore : https://apisgp.im.qcloud.com/v3/offline_push_report/honor
+
+- Korea: https://apikr.im.qcloud.com/v3/offline_push_report/honor
+
+- USA: https://apiusa.im.qcloud.com/v3/offline_push_report/honor
+
+- Germany: https://apiger.im.qcloud.com/v3/offline_push_report/honor
+
+- Indonesia: https://apiidn.im.qcloud.com/v3/offline_push_report/honor
+
+- China: https://api.im.qcloud.com/v3/offline_push_report/honor
+
+【vivo】
+| Callback Address Configuration | Receipt ID Configuration in the Chat Console |
+| --- | --- |
+| <strong>Receipt Address:</strong><br>- Singapore :https://apisgp.im.qcloud.com/v3/offline_push_report/vivo<br>- Korea:https://apikr.im.qcloud.com/v3/offline_push_report/vivo<br>- USA: https://apiusa.im.qcloud.com/v3/offline_push_report/vivo<br>- Germany: https://apiger.im.qcloud.com/v3/offline_push_report/vivo<br>- Indonesia: https://apiidn.im.qcloud.com/v3/offline_push_report/vivo<br>- China: https://api.im.qcloud.com/v3/offline_push_report/vivo |  |
+
+【Meizu】
+
+|Enable Receipt Switch|Configure Receipt Address|
+|---------|---------|
+|||
+
+**Receipt Address:**
+- Singapore : https://apisgp.im.qcloud.com/v3/offline_push_report/meizu
+
+- Korea: https://apikr.im.qcloud.com/v3/offline_push_report/meizu
+
+- USA: https://apiusa.im.qcloud.com/v3/offline_push_report/meizu
+
+- Germany: https://apiger.im.qcloud.com/v3/offline_push_report/meizu
+
+- Indonesia: https://apiidn.im.qcloud.com/v3/offline_push_report/meizu
+
+- China: https://api.im.qcloud.com/v3/offline_push_report/meizu
+
+> **Note:**
+>
+
+> After enabling the Receipt Switch, please make sure the Receipt Address is configured correctly. Failing to configure or configuring the wrong address will affect the push feature.
+>
+
+【iOS】
+
+For iOS push reach statistics configuration, see **Statistics of Push Arrival Rate**.
+
+No configuration is needed for other supported manufacturers; FCM does not support the push notification statistics feature.