react-native-nitro-ali-push 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hengkx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# react-native-nitro-ali-push
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+阿里云移动推送（Alibaba Cloud Push）的 React Native 封装，基于 **Nitro Modules** 实现：
+
+- iOS 原生端：**Swift**（`HybridAliPushPlugin` 实现 Nitro 生成的 `HybridAliPushPluginSpec`）
+- Android 原生端：**Kotlin**（`HybridAliPushPlugin` 继承 Nitro 生成的 `HybridAliPushPluginSpec`）
+- 原生桥接层由 `nitrogen` 代码生成器生成，无需手写 C++ / JNI / Objective-C
+- 推送事件通过 Nitro 回调（`addListener` 返回退订闭包）直接派发，不再依赖 `NativeEventEmitter`
+
+> 旧版（基于 TurboModule + 经典 bridge interop）位于 `react-native-ali-push`，本库为其 Nitro 重构版。
+
+---
+
+## 要求
+
+| 依赖 | 版本 |
+| --- | --- |
+| react-native | >= 0.76（新架构） |
+| react | * |
+| react-native-nitro-modules | >= 0.37.0 |
+| Android | `minSdk 21`、`compileSdk 34` |
+| iOS | `13.0+`、Xcode 14+ |
+
+---
+
+## 安装
+
+```bash
+npm install react-native-nitro-ali-push
+# 或
+yarn add react-native-nitro-ali-push
+```
+
+iOS 需要执行：
+
+```bash
+cd ios && pod install
+```
+
+---
+
+## iOS 集成
+
+### 1. 引入阿里云推送 SDK（`CloudPushSDK`）
+
+**方式一：CocoaPods（默认，推荐）**
+
+阿里云推送的 pod 不在 CocoaPods trunk，而在官方自己的 spec 仓库，所以要先在 `ios/Podfile` **顶部**声明 source：
+
+```ruby
+source 'https://github.com/aliyun/aliyun-specs.git'
+source 'https://cdn.cocoapods.org/'
+```
+
+若本机还没添加过该仓库，先执行一次：
+
+```bash
+pod repo add AliyunRepo https://github.com/aliyun/aliyun-specs.git
+```
+
+本库 podspec 默认已声明 `s.dependency "AlicloudPush", "~> 3"`，因此无需再做其它配置，直接 `pod install` 即可。
+
+**方式二：手动集成**
+
+从 [阿里云移动推送控制台](https://push.console.aliyun.com/) 下载 iOS SDK，把 `CloudPushSDK.framework`（3.x 为 `CloudPushSDK.xcframework`）放到本库 `ios/` 目录下。
+podspec 检测到该文件后会自动改用 `vendored_frameworks`，不再依赖 `AlicloudPush`，无需修改 podspec。
+
+> 若 `pod install` 报 `Unable to find a specification for 'AlicloudPush'`，说明 Podfile 里缺少上面的阿里云 source。
+
+### 2. AppDelegate 中初始化
+
+iOS 端的推送初始化必须在原生层完成（不能在 JS 中 `initPush`）：
+
+```swift
+import UIKit
+import UserNotifications
+// 本库模块名由 podspec 名 react-native-nitro-ali-push 推导为 react_native_nitro_ali_push。
+// HybridAliPushPlugin 是 public，跨模块使用需 import 本库模块（不在 NitroAliPush）。
+import react_native_nitro_ali_push
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+
+  func application(_ application: UIApplication,
+                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    // ... 其他初始化（RCTBridge 等）...
+
+    // 初始化阿里云推送
+    HybridAliPushPlugin.shared().setParams(
+      "<appKey>",
+      appSecret: "<appSecret>",
+      lauchOptions: launchOptions as? [AnyHashable: Any],
+      createNotificationCategoryHandler: {}
+    )
+
+    return true
+  }
+
+  // 注册 deviceToken
+  func application(_ application: UIApplication,
+                  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+    HybridAliPushPlugin.shared().application(application,
+      didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
+  }
+
+  func application(_ application: UIApplication,
+                  didFailToRegisterForRemoteNotificationsWithError error: Error) {
+    HybridAliPushPlugin.shared().application(application,
+      didFailToRegisterForRemoteNotificationsWithError: error)
+  }
+
+  // 收到远程通知
+  func application(_ application: UIApplication,
+                  didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+                  fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
+    HybridAliPushPlugin.shared().application(application,
+      didReceiveRemoteNotification: userInfo,
+      fetchCompletionHandler: completionHandler)
+  }
+}
+```
+
+> 若 CocoaPods 编译时提示找不到 `React` / `CloudPushSDK` 模块，请在 Podfile 中开启 `use_frameworks!` 或 `use_modular_headers!`。
+
+---
+
+## Android 集成
+
+### 1. `AndroidManifest.xml` 配置 AppKey / AppSecret
+
+在 `Application` 节点下（或 `MainApplication`）添加 `meta-data`：
+
+```xml
+<application ...>
+  <meta-data android:name="com.alibaba.app.appkey" android:value="<appKey>" />
+  <meta-data android:name="com.alibaba.app.appsecret" android:value="<appSecret>" />
+</application>
+```
+
+### 2. 初始化
+
+Android 端在 JS 中调用 `initPush` 即可：
+
+```ts
+import AliPush from 'react-native-nitro-ali-push';
+
+await AliPush.initPush('<appKey>', '<appSecret>');
+```
+
+---
+
+## 用法
+
+### 订阅推送消息
+
+```ts
+import AliPush from 'react-native-nitro-ali-push';
+
+const unsubscribe = AliPush.addEventListener('aliyunPushReceived', (message) => {
+  console.log(message.title, message.body, message.extras, message.type);
+});
+
+// ... 不再需要时
+unsubscribe();
+```
+
+### 账号 / 标签 / 别名
+
+```ts
+await AliPush.bindAccount('user_001');
+await AliPush.unbindAccount();
+
+await AliPush.bindTag(1, ['news', 'sports'], null); // target: 1 设备 / 2 账号 / 3 别名
+await AliPush.unbindTag(1, ['news'], null);
+
+await AliPush.addAlias('alias_001');
+await AliPush.removeAlias('alias_001');
+
+const tags = await AliPush.listTags(1);
+const aliases = await AliPush.listAliases();
+```
+
+### 设备号与角标
+
+```ts
+const deviceId = await AliPush.getDeviceId();
+
+await AliPush.setApplicationIconBadgeNumber(0);
+const badge = await AliPush.getApplicationIconBadgeNumber();
+```
+
+---
+
+## API 参考
+
+所有方法均返回 `Promise`（除事件订阅）。详见源码 `src/index.ts` 的 JSDoc。
+
+| 方法 | 说明 | 平台差异 |
+| --- | --- | --- |
+| `initPush(appKey, appSecret)` | 初始化推送 | Android 必需；iOS 为无操作（在 AppDelegate 初始化） |
+| `getDeviceId()` | 获取设备 `deviceId` | — |
+| `bindAccount(account)` | 绑定账号 | — |
+| `unbindAccount()` | 解绑账号 | — |
+| `bindTag(target, tags, alias)` | 绑定标签 | `target`: 1 设备 / 2 账号 / 3 别名 |
+| `unbindTag(target, tags, alias)` | 解绑标签 | 同上 |
+| `listTags(target)` | 列出标签 | 返回服务端响应字符串 |
+| `addAlias(alias)` / `removeAlias(alias)` | 添加 / 移除别名 | — |
+| `listAliases()` | 列出别名 | 返回服务端响应字符串 |
+| `setApplicationIconBadgeNumber(badge)` | 设置角标 | — |
+| `getApplicationIconBadgeNumber()` | 获取角标 | — |
+| `getInitialMessage()` | 获取冷启动首条消息 | 无则 `null` |
+| `getAuthorizationStatus()` | 获取通知授权状态 | Android 返回系统通知权限实际状态 |
+| `syncBadgeNum(badge)` | 同步角标到服务端 | 仅 iOS 有效 |
+| `addEventListener(event, listener)` | 订阅 `aliyunPushReceived` | 返回退订函数 |
+| `removeEventListener(unsubscribe)` | 取消订阅 | — |
+
+事件载荷类型见 `src/types.ts` 的 `AliPushMessage`。
+
+---
+
+## 开发 / 重新生成原生代码
+
+修改 `src/specs/*.nitro.ts` 后，运行代码生成器重新产出原生桥接层：
+
+```bash
+npm run codegen   # 等价于 npx nitrogen
+```
+
+类型检查：
+
+```bash
+npm run typecheck   # tsc --noEmit
+```
+
+本库源码（含类型与 JSDoc）位于 `src/`，原生端位于 `android/` 与 `ios/`，生成的桥接代码位于 `nitrogen/generated/`（随包发布，消费者无需自行运行 codegen）。Metro 会直接使用 `src/index.ts`（`package.json` 的 `source` / `react-native` 字段）。
+
+## License
+
+[MIT](./LICENSE) © hengkx &lt;ycxzhkx@gmail.com&gt;
+
+仓库与问题反馈：<https://github.com/hengkx/react-native-nitro-ali-push>

package/android/CMakeLists.txt

@@ -0,0 +1,31 @@
+project(NitroAliPush)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME NitroAliPush)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# 定义 C++ 库（具体的源文件由 Nitro 代码生成器自动加入）。
+add_library(${PACKAGE_NAME} SHARED)
+
+set(NITRO_SANITIZER "" CACHE STRING "Native sanitizer")
+if(NITRO_SANITIZER STREQUAL "address")
+  target_compile_options(${PACKAGE_NAME} PUBLIC -fsanitize=address -fno-omit-frame-pointer)
+  set_target_properties(${PACKAGE_NAME} PROPERTIES LINK_FLAGS "-fsanitize=address")
+elseif(NOT NITRO_SANITIZER STREQUAL "")
+  message(FATAL_ERROR "Unsupported NITRO_SANITIZER: ${NITRO_SANITIZER}")
+endif()
+
+# 引入 Nitro 生成的自动链接脚本与所有生成的 C++ 源文件。
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroAliPush+autolinking.cmake)
+
+# 本地头文件包含目录。
+include_directories("src/main/cpp")
+
+# 日志库与 Android 核心库。
+find_library(LOG_LIB log)
+target_link_libraries(
+  ${PACKAGE_NAME}
+  ${LOG_LIB}
+  android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,139 @@
+buildscript {
+  // buildscript 块会先于脚本其余部分求值，因此这里不能复用下面定义的 getKotlinVersion()
+  def kotlin_version = rootProject.ext.has('kotlinVersion')
+      ? rootProject.ext.get('kotlinVersion')
+      : '1.9.24'
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath 'com.android.tools.build:gradle:7.3.1'
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+  }
+}
+
+def getKotlinVersion() {
+  return rootProject.ext.has('kotlinVersion')
+      ? rootProject.ext.get('kotlinVersion')
+      : '1.9.24'
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/NitroAliPush+autolinking.gradle'
+
+android {
+  namespace "com.margelo.nitro.alipush"
+  compileSdkVersion 34
+
+  defaultConfig {
+    minSdkVersion 21
+    targetSdkVersion 34
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", "true"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared"
+        abiFilters (*reactNativeArchitectures())
+      }
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += "src/main/java"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+}
+
+repositories {
+  maven { url "https://maven.aliyun.com/repository/public" }
+  maven { url "https://maven.aliyun.com/repository/google" }
+  google()
+  mavenCentral()
+  maven { url 'https://developer.huawei.com/repo/' }
+  maven { url 'https://developer.hihonor.com/repo' }
+}
+
+dependencies {
+  // 新架构下使用 react-android（内含 Nitro / TurboModule 基础设施）。
+  implementation "com.facebook.react:react-android:+"
+
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:${getKotlinVersion()}"
+
+  // 阿里云移动推送 SDK（含 CloudPush、自建通道与厂商通道依赖）。
+  api("com.aliyun.ams:alicloud-android-push:3.10.1") {
+    // 若宿主工程已引入以下依赖，可取消对应 exclude 注释避免重复。
+    // exclude(module: 'alicloud-android-utdid')
+    // exclude(module: 'alicloud-android-beacon')
+  }
+  api 'com.aliyun.ams:alicloud-android-third-push:3.10.1'
+  //华为依赖
+  api 'com.aliyun.ams:alicloud-android-third-push-huawei:3.10.1'
+  //小米依赖
+  api 'com.aliyun.ams:alicloud-android-third-push-xiaomi:3.10.1'
+  //OPPO依赖
+  api 'com.aliyun.ams:alicloud-android-third-push-oppo:3.10.1'
+  //vivo依赖
+  api 'com.aliyun.ams:alicloud-android-third-push-vivo:3.10.1'
+  //魅族依赖
+  api 'com.aliyun.ams:alicloud-android-third-push-meizu:3.10.1'
+  //荣耀
+  api 'com.aliyun.ams:alicloud-android-third-push-honor:3.10.1'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,30 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- 阿里云推送需要网络与后台运行权限 -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <!-- 阿里云推送广播接收器（务必 exported=false） -->
+        <receiver
+            android:name="com.margelo.nitro.alipush.AliPushMessageReceiver"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
+            </intent-filter>
+        </receiver>
+
+        <!-- 第三方通道通知点击中转 -->
+        <activity
+            android:name="com.margelo.nitro.alipush.ThirdPartMessageActivity"
+            android:exported="true"
+            android:launchMode="singleTask">
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

package/android/src/main/java/com/margelo/nitro/alipush/AliPushMessageReceiver.kt

@@ -0,0 +1,156 @@
+package com.margelo.nitro.alipush
+
+import android.content.Context
+import android.os.Bundle
+import android.util.Log
+import com.alibaba.sdk.android.push.MessageReceiver
+import com.alibaba.sdk.android.push.notification.CPushMessage
+import com.margelo.nitro.core.AnyMap
+
+/**
+ * 阿里云推送广播接收器。
+ *
+ * 在 `AndroidManifest.xml` 中静态注册（见同目录 `AndroidManifest.xml`）。收到通知 /
+ * 消息 / 通知打开 / 通知删除等回调时，把数据组装成 [AliPushMessage] 并通过
+ * [HybridAliPushPlugin.dispatch] 发往 JS 的 `aliyunPushReceived` 事件；同时把「App 未
+ * 运行被通知唤起」场景下的首条消息缓存到 [HybridAliPushPlugin]（由 `getInitialMessage`
+ * 读取后清空）。
+ */
+class AliPushMessageReceiver : MessageReceiver() {
+
+  override fun onNotification(
+    context: Context?,
+    title: String?,
+    summary: String?,
+    extraMap: Map<String, String>?,
+  ) {
+    val message = AliPushMessage(
+      title = title,
+      subtitle = null,
+      body = summary,
+      badge = null,
+      extras = buildExtras(extraMap),
+      type = AliPushMessageType.NOTIFICATION,
+      actionIdentifier = null,
+      appState = null,
+      date = Variant_Double_String.create(System.currentTimeMillis().toDouble()),
+    )
+    HybridAliPushPlugin.dispatch(message)
+  }
+
+  override fun onMessage(context: Context?, intent: android.content.Intent?) {
+    val message = intent?.getSerializableExtra("message") as? CPushMessage
+    val extras = AnyMap()
+    message?.let {
+      extras.setString("appId", it.appId ?: "")
+      extras.setString("messageId", it.messageId ?: "")
+    }
+    intent?.extras?.let { putBundle(extras, it) }
+    val payload = AliPushMessage(
+      title = message?.title,
+      subtitle = null,
+      body = message?.content,
+      badge = null,
+      extras = extras,
+      type = AliPushMessageType.MESSAGE,
+      actionIdentifier = null,
+      appState = null,
+      date = Variant_Double_String.create(System.currentTimeMillis().toDouble()),
+    )
+    HybridAliPushPlugin.dispatch(payload)
+  }
+
+  override fun onNotificationOpened(
+    context: Context?,
+    title: String?,
+    summary: String?,
+    extraMap: Map<String, String>?,
+  ) {
+    val message = AliPushMessage(
+      title = title,
+      subtitle = null,
+      body = summary,
+      badge = null,
+      extras = buildExtras(extraMap),
+      type = AliPushMessageType.NOTIFICATION,
+      actionIdentifier = "opened",
+      appState = null,
+      date = Variant_Double_String.create(System.currentTimeMillis().toDouble()),
+    )
+    HybridAliPushPlugin.dispatch(message)
+  }
+
+  override fun onNotificationRemoved(context: Context?, messageId: String?) {
+    val extras = AnyMap()
+    if (messageId != null) extras.setString("messageId", messageId)
+    val message = AliPushMessage(
+      title = null,
+      subtitle = null,
+      body = null,
+      badge = null,
+      extras = extras,
+      type = AliPushMessageType.NOTIFICATION,
+      actionIdentifier = "removed",
+      appState = null,
+      date = Variant_Double_String.create(System.currentTimeMillis().toDouble()),
+    )
+    HybridAliPushPlugin.dispatch(message)
+  }
+
+  override fun onChannelRegistration(context: Context?, errorCode: String?) {
+    Log.d("AliPush", "onChannelRegistration: $errorCode")
+  }
+
+  // ---------------------------------------------------------------------------
+  // 内部工具
+  // ---------------------------------------------------------------------------
+
+  private fun buildExtras(extraMap: Map<String, String>?): AnyMap? {
+    if (extraMap.isNullOrEmpty()) return null
+    val map = AnyMap()
+    for ((k, v) in extraMap) {
+      map.setString(k, v)
+    }
+    return map
+  }
+
+  private fun putBundle(target: AnyMap, bundle: Bundle) {
+    bundle.keySet()?.forEach { key ->
+      when (val value = bundle.get(key)) {
+        is String -> target.setString(key, value)
+        is Double -> target.setDouble(key, value)
+        is Int -> target.setDouble(key, value.toDouble())
+        is Boolean -> target.setBoolean(key, value)
+        is Long -> target.setInt64(key, value)
+      }
+    }
+  }
+
+  companion object {
+    /**
+     * 由中转 Activity 传入点击通知的 `Bundle`，组装并派发到 JS。
+     * 第三方通道的通知点击数据通常放在 `Intent` 的 extras 中。
+     */
+    fun dispatchFromIntent(extras: Bundle?) {
+      if (extras == null) return
+      val title = extras.getString("title")
+      val body = extras.getString("body") ?: extras.getString("summary")
+      val e = AnyMap()
+      extras.keySet()?.forEach { key ->
+        (extras.get(key) as? String)?.let { e.setString(key, it) }
+      }
+      val message = AliPushMessage(
+        title = title,
+        subtitle = null,
+        body = body,
+        badge = null,
+        extras = e,
+        type = AliPushMessageType.NOTIFICATION,
+        actionIdentifier = "opened",
+        appState = null,
+        date = Variant_Double_String.create(System.currentTimeMillis().toDouble()),
+      )
+      HybridAliPushPlugin.dispatch(message)
+    }
+  }
+}