xuqinmin12/XuqmGroup-HarmonySDK
0
0
派生 0
代码 工单 合并请求 版本发布 百科 动态

docs(sdk): 添加 Android SDK 文档和 API 设计规范

浏览代码 
- 新增 Android SDK 使用文档，包含模块结构、集成方式和快速开始指南
- 添加 SDK API 重设计规范，统一初始化和登录接口设计
- 补充安全设计规范，完善 UserSig 鉴权和敏感数据处理方案
- 创建平台 REST API 规范，定义服务端到服务端的调用接口
- 添加离线推送架构设计，集成各大厂商推送服务与 IM 联动方案
这个提交包含在：
XuqmGroup 2026-04-29 15:46:39 +08:00
父节点 5c97b669ae
当前提交 b3d510ddae
共有 14 个文件被更改，包括 123 次插入 和 35081 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

2
.hvigor/cache/file-cache.json vendored
查看文件

文件差异因一行或多行过长而隐藏

2
.hvigor/cache/task-cache.json vendored
查看文件

文件差异因一行或多行过长而隐藏

74
.hvigor/outputs/logs/details/details.json
查看文件

@ -7,7 +7,6 @@
"INCLUDE_IN_BUILD": true,
"IS_COMMAND_LINE_ENTRY_MODULE": false,
"MODULE_TYPE": "har",
"IS_BYTE_CODE_HAR": true,
"IS_INCREMENTAL_MODULE": true
},
{
@ -17,15 +16,14 @@
"IS_COMMAND_LINE_ENTRY_MODULE": false,
"MODULE_TYPE": "entry",
"INCREMENTAL_TASKS": {
"COMPILE_ARKTS": false
"COMPILE_ARKTS": true
},
"IS_INCREMENTAL_MODULE": false
"IS_INCREMENTAL_MODULE": true
}
],
"NATIVE_COMPILER": "Default",
"IS_FULL_BUILD": true,
"BUILD_MODE": "debug",
"USE_NORMALIZED_OHMURL": true
"IS_FULL_BUILD": false,
"BUILD_MODE": "debug"
},
"HVIGOR": {
"IS_INCREMENTAL": true,
@ -34,50 +32,20 @@
"IS_HVIGORFILE_TYPE_CHECK": false,
"TASK_TIME": {
"923fe53966c6cd9343e11af776cd4b05be315ea4b200b02e4d5dfb0f929b73bf": {
"clean": 6854084,
"PreBuild": 57877208,
"CreateModuleInfo": 313958,
"GenerateMetadata": 1059542,
"PreCheckSyscap": 113666,
"GeneratePkgContextInfo": 4513000,
"ProcessIntegratedHsp": 210250,
"SyscapTransform": 1379833,
"ProcessRouterMap": 1444334,
"ProcessShareConfig": 693041,
"ProcessStartupConfig": 484167,
"CreateBuildProfile": 407542,
"MergeProfile": 1007333,
"GenerateLoaderJson": 3654458,
"ConfigureCmake": 76708,
"MakePackInfo": 1146667,
"ProcessProfile": 64121000,
"BuildNativeWithCmake": 118208,
"ProcessResource": 1388167,
"CompileResource": 172291834,
"BuildNativeWithNinja": 288083,
"BuildJS": 653791,
"ProcessLibs": 2090750,
"DoNativeStrip": 806875,
"CacheNativeLibs": 255417750,
"CompileArkTS": 2806613791,
"GeneratePkgModuleJson": 794250,
"ProcessCompiledResources": 138375,
"PackageHap": 221881709,
"PackingCheck": 2139958,
"SignHap": 820869459,
"CollectDebugSymbol": 420750,
"assembleHap": 78875
"CreateModuleInfo": 591083,
"PreCheckSyscap": 186208,
"ProcessIntegratedHsp": 333500,
"SyscapTransform": 12419000,
"ProcessStartupConfig": 799500,
"ConfigureCmake": 57125,
"BuildNativeWithCmake": 53875,
"BuildNativeWithNinja": 125916,
"BuildJS": 765334
},
"77aabe6c19463543339f337db9c84e4d10fd2f56ea0aedaf85a0214d59e93ec4": {
"clean": 1606375,
"PreBuild": 20062292,
"CreateHarBuildProfile": 780417,
"ConfigureCmake": 129750,
"MergeProfile": 1277375,
"BuildNativeWithCmake": 71500,
"BuildNativeWithNinja": 441083,
"ProcessLibs": 2313208,
"DoNativeStrip": 1523833
"ConfigureCmake": 68125,
"BuildNativeWithCmake": 139875,
"BuildNativeWithNinja": 437542
}
},
"APIS": [
@ -88,7 +56,13 @@
"ENABLE_CPP_FUNCTION_LEVEL_INCREMENTAL": false
},
"CONFIG_PROPERTIES": {},
"BUILD_ID": "202604290016471500",
"TOTAL_TIME": 5208027167
"BUILD_ID": "202604291536118220",
"ERROR_MESSAGE": [
{
"CODE": "10505001",
"TIMESTAMP": "1777448175246"
}
],
"TOTAL_TIME": 3424986416
}
}

10736
.hvigor/report/report-202604281921369060.json
查看文件

文件差异内容过多而无法显示 加载差异

13214
.hvigor/report/report-202604281921524500.json
查看文件

文件差异内容过多而无法显示 加载差异

11033
.hvigor/report/report-202604282012345420.json
查看文件

文件差异内容过多而无法显示 加载差异

9
README.md
查看文件

@ -76,8 +76,6 @@ export default class EntryAbility extends UIAbility {
await XuqmSDK.init(this.context, {
appKey: 'ak_your_app_key',
appSecret: 'as_your_app_secret',
apiBaseUrl: 'https://api.xuqm.com',
imBaseUrl: 'wss://im.xuqm.com',
debug: true,
})
}
@ -195,13 +193,16 @@ import { XuqmSDK } from '@xuqm/harmony-sdk'
const result = await XuqmSDK.update.checkAppUpdate('ak_xxx')
if (result.hasUpdate && result.info) {
const { latestVersionName, downloadUrl, forceUpdate } = result.info
const { latestVersionName, marketUrl, forceUpdate } = result.info
console.log(`发现新版本 ${latestVersionName}`)
// platform 'harmony': 通常引导用户跳转应用市场
if (marketUrl) {
await XuqmSDK.update.openAppMarket(getContext(this), marketUrl)
}
}
```
`checkAppUpdate` 内部通过 `bundleManager.getBundleInfoForSelfSync` 获取当前 `versionCode`。
Harmony 版本不提供本地安装包下载，更新只跳转应用市场。
### 检查 RN Bundle 热更新

2
entry/src/main/ets/entryability/EntryAbility.ets
查看文件

@ -9,8 +9,6 @@ export default class EntryAbility extends UIAbility {
await XuqmSDK.init(this.context, {
appKey: 'YOUR_APP_KEY',
appSecret: 'YOUR_APP_SECRET',
apiBaseUrl: 'https://api.xuqm.com',
imBaseUrl: 'wss://im.xuqm.com',
debug: true,
})
}

96
xuqm-sdk/scripts/xuqm_release.gradle.kts
查看文件

@ -13,12 +13,13 @@
* Config: xuqm.properties in the module or project root
* ---
* xuqm.serverUrl=https://update.dev.xuqinmin.com
* xuqm.appId=your-app-id
* xuqm.appKey=your-app-key
* xuqm.apiToken=your-api-token
* xuqm.storeTargets=HUAWEI # optional: HUAWEI,HONOR,...
* xuqm.autoPublishAfterReview=false
* xuqm.publishImmediately=false
* xuqm.scheduledPublishAt= # optional ISO datetime
* xuqm.webhookUrl= # optional
* xuqm.marketUrl= # Harmony app market URL
* ---
*
* Version is read from AppScope/app.json5 (standard HarmonyOS project layout).
@ -62,6 +63,16 @@ fun readHarmonyVersion(projectDir: File): HarmonyVersion {
return HarmonyVersion(name, code)
}
fun readHarmonyBundleName(projectDir: File): String {
val json5 = listOf(
File(projectDir, "AppScope/app.json5"),
File(projectDir.parentFile, "AppScope/app.json5"),
).firstOrNull { it.exists() } ?: throw GradleException("AppScope/app.json5 not found")
val content = json5.readText()
return Regex(""""bundleName"\s*:\s*"([^"]+)"""").find(content)?.groupValues?.get(1)
?: throw GradleException("bundleName not found in app.json5")
}
// ── HTTP helpers ──────────────────────────────────────────────────────────
fun httpGet(url: String, token: String): String {
@ -98,6 +109,22 @@ fun httpMultipartPost(url: String, token: String, parts: Map<String, Any>): Stri
fun parseJson(json: String, key: String) =
Regex(""""$key"\s*:\s*"([^"]+)"""").find(json)?.groupValues?.get(1)
fun promptLine(message: String): String? {
val console = System.console() ?: return null
print(message)
return console.readLine()
}
fun promptYesNo(message: String, default: Boolean = false): Boolean {
val answer = promptLine(message + if (default) " [Y/n]: " else " [y/N]: ")?.trim().orEmpty()
return when {
answer.isBlank() -> default
answer.equals("y", ignoreCase = true) || answer.equals("yes", ignoreCase = true) -> true
answer.equals("n", ignoreCase = true) || answer.equals("no", ignoreCase = true) -> false
else -> default
}
}
// ── Task ──────────────────────────────────────────────────────────────────
tasks.register("xuqmRelease") {
@ -110,19 +137,28 @@ tasks.register("xuqmRelease") {
doLast {
val cfg = loadXuqmCfg(projectDir)
val serverUrl = cfg.getProperty("xuqm.serverUrl") ?: throw GradleException("xuqm.serverUrl missing")
val appId = cfg.getProperty("xuqm.appId") ?: throw GradleException("xuqm.appId missing")
val appKey = cfg.getProperty("xuqm.appKey") ?: throw GradleException("xuqm.appKey missing")
val apiToken = cfg.getProperty("xuqm.apiToken") ?: throw GradleException("xuqm.apiToken missing")
val storeTargets = cfg.getProperty("xuqm.storeTargets", "")
val autoPublish = cfg.getProperty("xuqm.autoPublishAfterReview", "false").toBoolean()
val scheduledAt = cfg.getProperty("xuqm.scheduledPublishAt", "")
val publishImmediately = cfg.getProperty("xuqm.publishImmediately", "false").toBoolean()
var scheduledAt = cfg.getProperty("xuqm.scheduledPublishAt", "")
val webhookUrl = cfg.getProperty("xuqm.webhookUrl", "")
val marketUrl = cfg.getProperty("xuqm.marketUrl", "")
var publishMode = cfg.getProperty("xuqm.publishMode", "").trim().uppercase()
if (publishMode.isBlank() && !publishImmediately && scheduledAt.isBlank() && !autoPublish && System.console() != null) {
publishMode = promptReleaseMode()
if (publishMode == "SCHEDULED" && scheduledAt.isBlank()) {
scheduledAt = promptLine("Scheduled publish time (ISO datetime): ")?.trim().orEmpty()
}
}
// ── 1. Read local version ──────────────────────────────────────────
val (versionName, versionCode) = readHarmonyVersion(projectDir)
println("[xuqm] Local version: $versionName ($versionCode)")
val bundleName = readHarmonyBundleName(projectDir)
println("[xuqm] Local version: $versionName ($versionCode), appKey: $appKey")
// ── 2. Check server ────────────────────────────────────────────────
val listResp = httpGet("$serverUrl/api/v1/updates/app/list?appId=$appId&platform=ANDROID", apiToken)
val listResp = httpGet("$serverUrl/api/v1/updates/app/list?appId=$appKey&platform=HARMONY", apiToken)
val serverCode = Regex(""""versionCode"\s*:\s*(\d+)""").findAll(listResp)
.mapNotNull { it.groupValues[1].toIntOrNull() }.maxOrNull() ?: 0
println("[xuqm] Server latest versionCode: $serverCode")
@ -135,47 +171,45 @@ tasks.register("xuqmRelease") {
}
// ── 3. Locate HAP ──────────────────────────────────────────────────
val hapDir = File(projectDir, "entry/build/default/outputs/default")
val hapFile = hapDir.listFiles { f -> f.extension == "hap" }?.firstOrNull()
?: throw GradleException("HAP not found in ${hapDir.absolutePath}")
println("[xuqm] HAP: ${hapFile.absolutePath}")
// ── 4. Upload ──────────────────────────────────────────────────────
// ── 4. Upload release metadata to update service ──────────────────
if (marketUrl.isBlank()) {
throw GradleException("xuqm.marketUrl missing for Harmony release")
}
val parts = mutableMapOf<String, Any>(
"appId" to appId, "platform" to "ANDROID",
"appId" to appKey, "platform" to "HARMONY",
"versionName" to versionName, "versionCode" to versionCode,
"forceUpdate" to "false", "autoPublishAfterReview" to autoPublish.toString(),
"apkFile" to hapFile,
"packageName" to bundleName,
"marketUrl" to marketUrl,
)
if (storeTargets.isNotBlank()) parts["storeSubmitTargets"] = "[\"${storeTargets.split(",").joinToString("\",\"")}\"]"
if (scheduledAt.isNotBlank()) parts["scheduledPublishAt"] = scheduledAt
if (webhookUrl.isNotBlank()) parts["webhookUrl"] = webhookUrl
if (publishMode == "NOW") parts["publishImmediately"] = "true"
println("[xuqm] Uploading HAP...")
println("[xuqm] Uploading Harmony release metadata...")
val uploadResp = httpMultipartPost("$serverUrl/api/v1/updates/app/upload", apiToken, parts)
val versionId = parseJson(uploadResp, "id")
?: throw GradleException("[xuqm] Upload failed:\n$uploadResp")
println("[xuqm] Uploaded, version ID: $versionId")
// ── 5. Trigger store submission ────────────────────────────────────
if (storeTargets.isNotBlank()) {
println("[xuqm] Triggering store submission: $storeTargets")
val body = """{"storeTypes":[${storeTargets.split(",").joinToString(",") { "\"$it\"" }}]}"""
if (publishImmediately || publishMode == "NOW") {
println("[xuqm] Published immediately in update service.")
} else if (publishMode == "SCHEDULED" || scheduledAt.isNotBlank()) {
println("[xuqm] Will auto-publish at: ${scheduledAt.ifBlank { "(use update service scheduled publish config)" }}")
} else if (autoPublish) {
println("[xuqm] Will auto-publish after store reviews pass.")
} else if (System.console() != null && promptYesNo("[xuqm] Publish now?", false)) {
val client = HttpClient.newHttpClient()
val req = HttpRequest.newBuilder(URI.create("$serverUrl/api/v1/updates/store/app/$versionId/execute-submit"))
val req = HttpRequest.newBuilder(URI.create("$serverUrl/api/v1/updates/app/$versionId/publish"))
.header("Authorization", "Bearer $apiToken")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body)).build()
val storeResp = client.send(req, HttpResponse.BodyHandlers.ofString())
println("[xuqm] Store submission HTTP ${storeResp.statusCode()}")
.POST(HttpRequest.BodyPublishers.noBody())
.build()
val publishResp = client.send(req, HttpResponse.BodyHandlers.ofString())
println("[xuqm] Publish HTTP ${publishResp.statusCode()}")
}
println("[xuqm] Done.")
if (scheduledAt.isNotBlank()) {
println("[xuqm] Will publish at: $scheduledAt")
} else if (autoPublish) {
println("[xuqm] Will auto-publish after store reviews pass.")
} else {
if (!publishImmediately && publishMode != "NOW" && scheduledAt.isBlank() && !autoPublish) {
println("[xuqm] Publish manually: POST $serverUrl/api/v1/updates/app/$versionId/publish")
}
}

2
xuqm-sdk/src/main/ets/core/Endpoints.ets 普通文件
查看文件

@ -0,0 +1,2 @@
export const DEFAULT_API_BASE_URL = 'https://dev.xuqinmin.com'
export const DEFAULT_IM_WS_URL = 'wss://dev.xuqinmin.com/ws/im'

3
xuqm-sdk/src/main/ets/core/HttpClient.ets
查看文件

@ -1,6 +1,7 @@
import http from '@ohos.net.http'
import type { ApiResponse, HttpHeaders } from './Types'
import { SDKContext } from './SDKContext'
import { DEFAULT_API_BASE_URL } from './Endpoints'
export class HttpClient {
static async request<T>(
@ -11,7 +12,7 @@ export class HttpClient {
): Promise<T> {
const config = SDKContext.getConfig()
const token = SDKContext.getToken()
const url = config.apiBaseUrl.replace(/\/$/, '') + path + (query ? '?' + query : '')
const url = DEFAULT_API_BASE_URL.replace(/\/$/, '') + path + (query ? '?' + query : '')
const client = http.createHttp()
try {

6
xuqm-sdk/src/main/ets/core/Types.ets
查看文件

@ -1,8 +1,6 @@
export interface SDKConfig {
appKey: string
appSecret: string
apiBaseUrl: string
imBaseUrl: string
debug: boolean
}
@ -145,6 +143,8 @@ export interface AppVersionInfo {
latestVersionCode: number
latestVersionName: string
downloadUrl: string
marketUrl?: string
appStoreUrl?: string
forceUpdate: boolean
releaseNotes: string
}
@ -154,6 +154,8 @@ export interface RnBundleInfo {
downloadUrl: string
md5: string
forceUpdate: boolean
packageName?: string
packageMatched?: boolean
}
export interface PushTokenInfo {

3
xuqm-sdk/src/main/ets/im/ImClient.ets
查看文件

@ -1,6 +1,7 @@
import webSocket from '@ohos.net.webSocket'
import { HttpClient } from '../core/HttpClient'
import { SDKContext } from '../core/SDKContext'
import { DEFAULT_IM_WS_URL } from '../core/Endpoints'
import type {
ChatType,
ConversationData,
@ -129,7 +130,7 @@ export class ImClient {
if (this.destroyed) return
const config = SDKContext.getConfig()
const token = SDKContext.getToken() ?? ''
const url = config.imBaseUrl.replace(/\/$/, '') + '/ws/im?token=' + encodeURIComponent(token)
const url = DEFAULT_IM_WS_URL.replace(/\/$/, '') + '?token=' + encodeURIComponent(token)
this.ws = webSocket.createWebSocket()

22
xuqm-sdk/src/main/ets/update/UpdateSDK.ets
查看文件

@ -1,6 +1,7 @@
import bundleManager from '@ohos.bundle.bundleManager'
import request from '@ohos.request'
import common from '@ohos.app.ability.common'
import request from '@ohos.request'
import type { BusinessError } from '@ohos.base'
import { HttpClient } from '../core/HttpClient'
import type { AppVersionInfo, RnBundleInfo } from '../core/Types'
import { SDKContext } from '../core/SDKContext'
@ -23,7 +24,7 @@ export class UpdateSDK {
const currentVersionCode = bundleInfo.versionCode
const data = await HttpClient.get<AppVersionInfo>(
`/api/v1/updates/app/check?appKey=${appKey}&versionCode=${currentVersionCode}&platform=harmony`
`/api/v1/updates/app/check?appKey=${appKey}&versionCode=${currentVersionCode}&platform=HARMONY`
)
if (data.latestVersionCode <= currentVersionCode) {
@ -32,18 +33,29 @@ export class UpdateSDK {
return { hasUpdate: true, info: data }
}
static async openAppMarket(context: common.UIAbilityContext, url?: string): Promise<void> {
if (!url) {
return
}
await context.openLink(url, { appLinkingOnly: false })
}
static async checkRnUpdate(
appKey: string,
bundleName: string,
currentBundleVersion: number
currentBundleVersion: number,
packageName?: string
): Promise<RnUpdateResult> {
const data = await HttpClient.get<RnBundleInfo>(
`/api/v1/rn/update/check?appKey=${appKey}&bundleName=${bundleName}&bundleVersion=${currentBundleVersion}`
`/api/v1/rn/update/check?appKey=${appKey}&bundleName=${bundleName}&bundleVersion=${currentBundleVersion}${packageName ? `&packageName=${encodeURIComponent(packageName)}` : ''}`
)
if (data.bundleVersion <= currentBundleVersion) {
return { hasUpdate: false }
}
if (packageName && data.packageMatched === false) {
return { hasUpdate: false, info: data }
}
return { hasUpdate: true, info: data }
}
@ -57,7 +69,7 @@ export class UpdateSDK {
request.downloadFile(context, {
url: downloadUrl,
filePath: destPath,
}, (err, task) => {
}, (err: BusinessError | null, task: request.DownloadTask) => {
if (err) { reject(err); return }
task.on('complete', resolve)
task.on('fail', (error: number) => reject(new Error(`Download failed: ${error}`)))