@cloudcare/cocos-sdk 0.1.0-alpha.4 → 0.1.0-alpha.5

package/README.md

@@ -18,6 +18,42 @@ Guance Cloud Application Monitoring collects and analyzes RUM, Log, Trace, and S
 
 Cocos Creator 3.0–3.6.2 is supported on a best-effort basis because the stable native build extension API starts at 3.6.3. Web, mini-game, and desktop targets are not currently supported.
 
+## iOS dependency manager
+
+CocoaPods remains the default. To use Swift Package Manager, add
+`cocos-sdk.config.json` to your **Cocos project root** (beside `assets`):
+
+```json
+{
+  "ios": {
+    "dependencyManager": "spm"
+  }
+}
+```
+
+Alternatively, save this setting when installing the extension:
+
+```sh
+npx @cloudcare/cocos-sdk install --ios-dependency-manager spm
+```
+
+Rebuild the native iOS project in Creator after changing the configuration. The
+extension links the local `FTCocosBridge` package and Xcode resolves the pinned
+iOS SDK from Git. Fresh SPM projects do not require `pod install`; open the
+`.xcodeproj`. If the host uses CocoaPods for other libraries, continue opening
+its `.xcworkspace`.
+
+When switching an existing installation, the extension removes its managed SDK
+Pod entries and runs `pod install` if Pods were previously installed. Other Pods
+are preserved. Manually declared SDK Pods or other Pods that depend on the same
+native SDK must be migrated first to avoid duplicate linking. Set the value to
+`cocoapods` to switch back, then run `pod install` as usual.
+
+Creator 3 CMake regeneration restores the package integration automatically during
+Xcode builds. If you regenerate the project by running CMake separately, rerun
+Creator's native build integration before opening Xcode. Hybrid examples use the
+same configuration with their existing `native:install` command.
+
 ## Examples
 
 [Guance Cloud SDK Cocos Creator Demo](https://github.com/GuanceCloud/datakit-cocos/tree/main/examples)

package/bin/cli.cjs

@@ -28,6 +28,16 @@ const container = creatorMajor === 2 ? 'packages' : 'extensions';
 const destination = path.join(projectRoot, container, 'guance-cocos-sdk');
 const legacyDestination = path.join(projectRoot, container, 'ft-cocos-sdk');
 const extensionSource = path.join(packageRoot, 'extensions', `creator${creatorMajor}`);
+const manager = readOption(rawArguments, '--ios-dependency-manager');
+if (manager !== undefined && !['spm', 'cocoapods'].includes(manager)) {
+  fail('Invalid --ios-dependency-manager. Expected spm or cocoapods.');
+}
+const configFile = path.join(projectRoot, 'cocos-sdk.config.json');
+const config = readJson(configFile) || {};
+if (manager !== undefined) {
+  config.ios = { ...config.ios, dependencyManager: manager };
+  fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+}
 
 copyDirectory(extensionSource, destination);
 copyDirectory(path.join(packageRoot, 'native'), path.join(destination, 'native'));
@@ -119,6 +129,7 @@ function printHelp() {
     'Options:',
     '  --project <path>  Cocos project root (defaults to the current directory)',
     '  --creator <2|3>   Override automatic Cocos Creator version detection',
+    '  --ios-dependency-manager <spm|cocoapods>  Save the iOS dependency manager in cocos-sdk.config.json',
     '  -h, --help        Show this help',
     '',
   ].join('\n'));

package/dist/creator2/core/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of the installed Cocos SDK package. */
-export declare const FT_COCOS_SDK_VERSION = "0.1.0-alpha.4";
+export declare const FT_COCOS_SDK_VERSION = "0.1.0-alpha.5";
 /** Global-context key used to report the Cocos SDK package version. */
 export declare const FT_COCOS_SDK_VERSION_KEY = "sdk_package_cocos";
 /** Event attribute used to identify data emitted through a framework bridge. */

package/dist/creator2/core/version.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FT_COCOS_SDK_BRIDGE_INFO = exports.FT_COCOS_SDK_BRIDGE_INFO_KEY = exports.FT_COCOS_SDK_VERSION_KEY = exports.FT_COCOS_SDK_VERSION = void 0;
 /** Version of the installed Cocos SDK package. */
-exports.FT_COCOS_SDK_VERSION = '0.1.0-alpha.4';
+exports.FT_COCOS_SDK_VERSION = '0.1.0-alpha.5';
 /** Global-context key used to report the Cocos SDK package version. */
 exports.FT_COCOS_SDK_VERSION_KEY = 'sdk_package_cocos';
 /** Event attribute used to identify data emitted through a framework bridge. */

package/dist/creator3/core/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of the installed Cocos SDK package. */
-export declare const FT_COCOS_SDK_VERSION = "0.1.0-alpha.4";
+export declare const FT_COCOS_SDK_VERSION = "0.1.0-alpha.5";
 /** Global-context key used to report the Cocos SDK package version. */
 export declare const FT_COCOS_SDK_VERSION_KEY = "sdk_package_cocos";
 /** Event attribute used to identify data emitted through a framework bridge. */

package/dist/creator3/core/version.js

@@ -1,5 +1,5 @@
 /** Version of the installed Cocos SDK package. */
-export const FT_COCOS_SDK_VERSION = '0.1.0-alpha.4';
+export const FT_COCOS_SDK_VERSION = '0.1.0-alpha.5';
 /** Global-context key used to report the Cocos SDK package version. */
 export const FT_COCOS_SDK_VERSION_KEY = 'sdk_package_cocos';
 /** Event attribute used to identify data emitted through a framework bridge. */

package/extensions/creator2/install-native.cjs

@@ -22,6 +22,7 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   buildRoot = path.resolve(buildRoot);
   extensionRoot = path.resolve(extensionRoot);
   if (!fs.existsSync(buildRoot)) return;
+  const dependencyManager = readIosDependencyManager(buildRoot, extensionRoot);
   const nativeSource = path.join(extensionRoot, 'native');
   if (!fs.existsSync(nativeSource)) {
     logger.warn(`[cocos-sdk] Native bridge not found at ${nativeSource}`);
@@ -47,7 +48,11 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   const iosApplicationProjects = xcodeProjects
     .map((projectFile) => ({ projectFile, target: findIosApplicationTarget(projectFile) }))
     .filter((project) => project.target);
-  if (podfiles.length === 0) {
+  if (dependencyManager === 'spm' && iosApplicationProjects.length > 0) {
+    migrateManagedPods(podfiles, logger);
+    copyDirectory(path.join(nativeSource, 'ios'), path.join(buildNative, 'FTCocosBridge'));
+  }
+  if (dependencyManager === 'cocoapods' && podfiles.length === 0) {
     iosApplicationProjects.forEach(({ projectFile, target }) => {
       const projectDirectory = path.dirname(path.dirname(projectFile));
       const podfile = path.join(projectDirectory, 'Podfile');
@@ -57,12 +62,17 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   }
   iosApplicationProjects.forEach(({ projectFile, target }) => {
     patchCocos2IosConfiguration(projectFile, target);
+    if (dependencyManager === 'spm') {
+      require('./install-spm.cjs').installSwiftPackage(projectFile, path.join(buildNative, 'FTCocosBridge'), 'FTCocosBridge', target);
+    } else if (fs.readFileSync(projectFile, 'utf8').includes('XCLocalSwiftPackageReference')) {
+      require('./install-spm.cjs').removeSwiftPackages(projectFile);
+    }
   });
   gradleFiles.forEach((file) => patchGradle(file, buildNative));
   gradlePropertiesFiles.forEach(patchGradleProperties);
-  podfiles.forEach((file) => patchPodfile(file, buildNative));
+  if (dependencyManager === 'cocoapods') podfiles.forEach((file) => patchPodfile(file, buildNative));
   logger.info(
-    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${podfiles.length} iOS project files).`,
+    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${dependencyManager === 'spm' ? iosApplicationProjects.length : podfiles.length} iOS project files; iOS: ${dependencyManager}).`,
   );
 }
 
@@ -252,7 +262,7 @@ function patchGradle(file, nativeRoot) {
     "    maven { url 'https://mvnrepo.guance.com/repository/maven-releases' }",
     '}',
     'dependencies {',
-    "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha02'",
+    "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha03'",
     "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:1.1.3'",
     "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay:0.1.9-alpha03'",
     "    implementation 'com.google.code.gson:gson:2.10.1'",
@@ -298,6 +308,10 @@ function replaceIndentedMarkedBlock(contents, begin, end, block) {
 
 function findIosApplicationTarget(projectFile) {
   const contents = fs.readFileSync(projectFile, 'utf8');
+  if (contents.includes('COCOS_SDK_XCODE_PROJECT')) {
+    const { readProject, applicationTarget } = require('./install-spm.cjs');
+    return applicationTarget(readProject(projectFile))?.[1].name || null;
+  }
   const nativeTarget = /\/\* ([^*]+) \*\/ = \{\s*isa = PBXNativeTarget;([\s\S]*?)\n\s*\};/g;
   const targets = [];
   let match;
@@ -382,4 +396,58 @@ function escapeGroovy(value) { return value.replace(/\\/g, '\\\\').replace(/'/g,
 function escapeRuby(value) { return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'"); }
 function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
-module.exports = { installNative };
+function readIosDependencyManager(buildRoot, extensionRoot) {
+  for (const start of [buildRoot, extensionRoot]) {
+    let directory = path.resolve(start);
+    while (true) {
+      const file = path.join(directory, 'cocos-sdk.config.json');
+      if (fs.existsSync(file)) {
+        const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const manager = config.ios?.dependencyManager ?? 'cocoapods';
+        if (!['spm', 'cocoapods'].includes(manager)) {
+          throw new Error(`[cocos-sdk] Invalid ios.dependencyManager in ${file}: expected spm or cocoapods.`);
+        }
+        return manager;
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return 'cocoapods';
+}
+
+function migrateManagedPods(podfiles, logger) {
+  for (const file of podfiles) {
+    const original = fs.readFileSync(file, 'utf8');
+    let next = original;
+    for (const [begin, end] of [
+      [POD_BEGIN, POD_END], [LEGACY_POD_BEGIN, LEGACY_POD_END], [LEGACY_BEGIN, LEGACY_END],
+      ['# COCOS_HYBRID_SAMPLE_BEGIN', '# COCOS_HYBRID_SAMPLE_END'],
+    ]) next = next.replace(markedPattern(begin, end), '');
+    if (/^\s*pod\s+['"](?:FTCocosBridge|HybridSampleHost|GuanceSDK)(?:\/[^'"]*)?['"]/m.test(next)) {
+      throw new Error(`[cocos-sdk] Remove the manually declared native SDK Pod from ${file} before switching to SPM.`);
+    }
+    if (next !== original) fs.writeFileSync(file, next);
+    const directory = path.dirname(file);
+    const existingLock = path.join(directory, 'Podfile.lock');
+    const hasSDKPods = fs.existsSync(existingLock)
+      && /^\s*- (?:FTCocosBridge|HybridSampleHost|GuanceSDK)(?:\/|\s|:)/m.test(fs.readFileSync(existingLock, 'utf8'));
+    if (next === original && !hasSDKPods) continue;
+    if (fs.existsSync(path.join(directory, 'Podfile.lock')) || fs.existsSync(path.join(directory, 'Pods'))) {
+      logger.info('[cocos-sdk] Updating existing Pods integration for the SPM switch.');
+      try {
+        execFileSync('pod', ['install'], { cwd: directory, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+      } catch (error) {
+        fs.writeFileSync(file, original);
+        throw new Error(`[cocos-sdk] Unable to update existing Pods in ${directory}: ${error.message}`);
+      }
+      const lock = path.join(directory, 'Podfile.lock');
+      if (fs.existsSync(lock) && /^\s*- GuanceSDK(?:\/|\s|:)/m.test(fs.readFileSync(lock, 'utf8'))) {
+        throw new Error(`[cocos-sdk] Another Pod still depends on the native SDK in ${lock}; migrate that dependency before using SPM.`);
+      }
+    }
+  }
+}
+
+module.exports = { installNative, readIosDependencyManager };

package/extensions/creator2/install-spm.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const { execFileSync } = require('child_process');
+
+function readProject(file) {
+  // plutil understands both Xcode's OpenStep format and XML plists, without Ruby/gems.
+  return JSON.parse(execFileSync('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file], {
+    encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  }));
+}
+
+function writeProject(file, project) {
+  const next = `// !$*UTF8*$!\n// COCOS_SDK_XCODE_PROJECT\n${serialize(project)}\n`;
+  if (fs.readFileSync(file, 'utf8') !== next) fs.writeFileSync(file, next);
+}
+
+function serialize(value, depth = 0) {
+  const indent = '\t'.repeat(depth);
+  if (Array.isArray(value)) {
+    return `(\n${value.map((entry) => `${indent}\t${serialize(entry, depth + 1)},\n`).join('')}${indent})`;
+  }
+  if (value && typeof value === 'object') {
+    return `{\n${Object.entries(value).sort(([a], [b]) => a === 'isa' ? -1 : b === 'isa' ? 1 : a.localeCompare(b)).map(([key, entry]) => (
+      `${indent}\t${serialize(key)} = ${serialize(entry, depth + 1)};\n`
+    )).join('')}${indent}}`;
+  }
+  const text = String(value);
+  return /^[A-Za-z0-9_./]+$/.test(text) ? text : JSON.stringify(text);
+}
+
+function applicationTarget(project, preferredName) {
+  const targets = Object.entries(project.objects).filter(([, object]) => (
+    object.isa === 'PBXNativeTarget' && object.productType === 'com.apple.product-type.application'
+  ));
+  return targets.find(([, object]) => object.name === preferredName)
+    || targets.find(([, object]) => /(?:^|[-_.])(?:mobile|ios)$/i.test(object.name))
+    || targets[0];
+}
+
+function add(list, value) {
+  if (!list.includes(value)) list.push(value);
+}
+
+function identifier(value) {
+  return createHash('sha256').update(`cocos-sdk:${value}`).digest('hex').slice(0, 24).toUpperCase();
+}
+
+function installSwiftPackage(projectFile, packageDirectory, productName, targetName) {
+  if (!fs.existsSync(path.join(packageDirectory, 'Package.swift'))) {
+    throw new Error(`[cocos-sdk] Missing Swift package: ${packageDirectory}`);
+  }
+  const project = readProject(projectFile);
+  const selected = applicationTarget(project, targetName);
+  if (!selected) throw new Error(`[cocos-sdk] No application target in ${projectFile}`);
+  const [targetID, target] = selected;
+  const objects = project.objects;
+  const root = objects[project.rootObject];
+  const projectDirectory = path.resolve(path.dirname(path.dirname(projectFile)), root.projectDirPath || '.');
+  const relativePath = path.relative(projectDirectory, packageDirectory).split(path.sep).join('/');
+  const packageID = identifier(`package:${productName}`);
+  const productID = identifier(`product:${targetID}:${productName}`);
+  const buildID = identifier(`framework:${targetID}:${productName}`);
+  const existing = (target.packageProductDependencies || []).find((id) => (
+    id !== productID && objects[id]?.productName === productName
+  ));
+  if (existing) throw new Error(`[cocos-sdk] ${productName} is already managed manually in ${target.name}; remove that reference before automatic installation.`);
+
+  objects[packageID] = { isa: 'XCLocalSwiftPackageReference', relativePath };
+  objects[productID] = { isa: 'XCSwiftPackageProductDependency', productName };
+  objects[buildID] = { isa: 'PBXBuildFile', productRef: productID };
+  add(root.packageReferences ||= [], packageID);
+  add(target.packageProductDependencies ||= [], productID);
+  let phaseID = (target.buildPhases || []).find((id) => objects[id]?.isa === 'PBXFrameworksBuildPhase');
+  if (!phaseID) {
+    phaseID = identifier(`frameworks:${targetID}`);
+    objects[phaseID] = { isa: 'PBXFrameworksBuildPhase', buildActionMask: '2147483647', files: [], runOnlyForDeploymentPostprocessing: '0' };
+    add(target.buildPhases ||= [], phaseID);
+  }
+  add(objects[phaseID].files ||= [], buildID);
+  const configurations = objects[target.buildConfigurationList]?.buildConfigurations || [];
+  for (const configID of configurations) {
+    const settings = objects[configID].buildSettings ||= {};
+    const flags = settings.OTHER_LDFLAGS;
+    if (Array.isArray(flags)) {
+      add(flags, '$(inherited)');
+      add(flags, '-ObjC');
+    } else {
+      const parts = [flags || '$(inherited)'];
+      if (!String(flags || '').includes('$(inherited)')) add(parts, '$(inherited)');
+      if (!/(?:^|\s)-ObjC(?:\s|$)/.test(flags || '')) add(parts, '-ObjC');
+      settings.OTHER_LDFLAGS = parts.join(' ');
+    }
+    if (Number(settings.IPHONEOS_DEPLOYMENT_TARGET || 0) < 12) settings.IPHONEOS_DEPLOYMENT_TARGET = '12.0';
+    settings.CLANG_ENABLE_MODULES = 'YES';
+  }
+  preserveCmakeIntegration(projectFile, project, { packageDirectory, productName, targetName: target.name });
+  writeProject(projectFile, project);
+}
+
+const RESTORE_BEGIN = '# COCOS_SDK_SPM_RESTORE_BEGIN';
+const RESTORE_END = '# COCOS_SDK_SPM_RESTORE_END';
+const restorePattern = /\n?# COCOS_SDK_SPM_RESTORE_BEGIN[\s\S]*?# COCOS_SDK_SPM_RESTORE_END\n?/g;
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function preserveCmakeIntegration(projectFile, project, entry) {
+  const objects = project.objects;
+  const zeroCheck = Object.values(objects).find((object) => object.name === 'ZERO_CHECK');
+  if (!zeroCheck) return;
+  // CMake's SYMROOT/OBJROOT overrides select Xcode's legacy build locations,
+  // which reject packages. Keep CONFIGURATION_BUILD_DIR (engine archives).
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  const state = fs.existsSync(stateFile)
+    ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { packages: [], buildLocations: {} };
+  for (const [id, object] of Object.entries(objects)) {
+    if (object.isa !== 'XCBuildConfiguration') continue;
+    for (const key of ['SYMROOT', 'OBJROOT']) {
+      if (object.buildSettings?.[key] === undefined) continue;
+      (state.buildLocations[id] ||= {})[key] = object.buildSettings[key];
+      delete object.buildSettings[key];
+    }
+  }
+  const relativeDirectory = path.relative(path.dirname(projectFile), entry.packageDirectory);
+  state.packages = state.packages.filter((item) => item.productName !== entry.productName);
+  state.packages.push({ ...entry, packageDirectory: relativeDirectory });
+  state.packages.sort((a, b) => a.productName.localeCompare(b.productName));
+  const helper = path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs');
+  if (path.resolve(helper) !== path.resolve(__filename)) fs.copyFileSync(__filename, helper);
+  const restore = [
+    RESTORE_BEGIN,
+    `${process.versions.electron ? 'ELECTRON_RUN_AS_NODE=1 ' : ''}${shellQuote(process.execPath)} ${shellQuote(helper)} --restore`,
+    RESTORE_END,
+  ].join('\n');
+  for (const id of zeroCheck.buildPhases || []) {
+    const phase = objects[id];
+    if (phase?.isa !== 'PBXShellScriptBuildPhase') continue;
+    phase.shellScript = `${(phase.shellScript || '').replace(restorePattern, '').trimEnd()}\n${restore}\n`;
+  }
+  const serialized = `${JSON.stringify(state, null, 2)}\n`;
+  if (!fs.existsSync(stateFile) || fs.readFileSync(stateFile, 'utf8') !== serialized) fs.writeFileSync(stateFile, serialized);
+}
+
+function removeSwiftPackages(projectFile) {
+  const project = readProject(projectFile);
+  const objects = project.objects;
+  const removed = new Set();
+  for (const productName of ['FTCocosBridge', 'HybridSampleHost']) {
+    const packageID = identifier(`package:${productName}`);
+    if (!objects[packageID]) continue;
+    removed.add(packageID);
+    for (const [id, object] of Object.entries(objects)) {
+      if (object.isa !== 'PBXNativeTarget') continue;
+      removed.add(identifier(`product:${id}:${productName}`));
+      removed.add(identifier(`framework:${id}:${productName}`));
+    }
+  }
+  if (!removed.size) return;
+  for (const id of removed) delete objects[id];
+  for (const object of Object.values(objects)) {
+    for (const key of ['packageReferences', 'packageProductDependencies', 'files']) {
+      if (Array.isArray(object[key])) object[key] = object[key].filter((id) => !removed.has(id));
+    }
+    if (object.isa === 'PBXShellScriptBuildPhase') object.shellScript = (object.shellScript || '').replace(restorePattern, '');
+  }
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    for (const [id, settings] of Object.entries(state.buildLocations)) {
+      if (objects[id]) Object.assign(objects[id].buildSettings ||= {}, settings);
+    }
+    fs.unlinkSync(stateFile);
+    fs.rmSync(path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs'), { force: true });
+  }
+  writeProject(projectFile, project);
+}
+
+module.exports = { installSwiftPackage, removeSwiftPackages, readProject, applicationTarget };
+
+if (require.main === module && process.argv[2] === '--restore') {
+  const directory = path.dirname(__filename);
+  const state = JSON.parse(fs.readFileSync(path.join(directory, 'cocos-sdk-spm.json'), 'utf8'));
+  for (const item of state.packages) {
+    installSwiftPackage(path.join(directory, 'project.pbxproj'), path.resolve(directory, item.packageDirectory), item.productName, item.targetName);
+  }
+}

package/extensions/creator3/install-native.cjs

@@ -22,6 +22,7 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   buildRoot = path.resolve(buildRoot);
   extensionRoot = path.resolve(extensionRoot);
   if (!fs.existsSync(buildRoot)) return;
+  const dependencyManager = readIosDependencyManager(buildRoot, extensionRoot);
   const nativeSource = path.join(extensionRoot, 'native');
   if (!fs.existsSync(nativeSource)) {
     logger.warn(`[cocos-sdk] Native bridge not found at ${nativeSource}`);
@@ -47,7 +48,11 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   const iosApplicationProjects = xcodeProjects
     .map((projectFile) => ({ projectFile, target: findIosApplicationTarget(projectFile) }))
     .filter((project) => project.target);
-  if (podfiles.length === 0) {
+  if (dependencyManager === 'spm' && iosApplicationProjects.length > 0) {
+    migrateManagedPods(podfiles, logger);
+    copyDirectory(path.join(nativeSource, 'ios'), path.join(buildNative, 'FTCocosBridge'));
+  }
+  if (dependencyManager === 'cocoapods' && podfiles.length === 0) {
     iosApplicationProjects.forEach(({ projectFile, target }) => {
       const projectDirectory = path.dirname(path.dirname(projectFile));
       const podfile = path.join(projectDirectory, 'Podfile');
@@ -57,12 +62,17 @@ function installNative(buildRoot, extensionRoot, logger = console) {
   }
   iosApplicationProjects.forEach(({ projectFile, target }) => {
     patchCocos2IosConfiguration(projectFile, target);
+    if (dependencyManager === 'spm') {
+      require('./install-spm.cjs').installSwiftPackage(projectFile, path.join(buildNative, 'FTCocosBridge'), 'FTCocosBridge', target);
+    } else if (fs.readFileSync(projectFile, 'utf8').includes('XCLocalSwiftPackageReference')) {
+      require('./install-spm.cjs').removeSwiftPackages(projectFile);
+    }
   });
   gradleFiles.forEach((file) => patchGradle(file, buildNative));
   gradlePropertiesFiles.forEach(patchGradleProperties);
-  podfiles.forEach((file) => patchPodfile(file, buildNative));
+  if (dependencyManager === 'cocoapods') podfiles.forEach((file) => patchPodfile(file, buildNative));
   logger.info(
-    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${podfiles.length} iOS project files).`,
+    `[cocos-sdk] Installed native bridge (${gradleFiles.length} Android, ${dependencyManager === 'spm' ? iosApplicationProjects.length : podfiles.length} iOS project files; iOS: ${dependencyManager}).`,
   );
 }
 
@@ -252,7 +262,7 @@ function patchGradle(file, nativeRoot) {
     "    maven { url 'https://mvnrepo.guance.com/repository/maven-releases' }",
     '}',
     'dependencies {',
-    "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha02'",
+    "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.7.6-alpha03'",
     "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:1.1.3'",
     "    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay:0.1.9-alpha03'",
     "    implementation 'com.google.code.gson:gson:2.10.1'",
@@ -298,6 +308,10 @@ function replaceIndentedMarkedBlock(contents, begin, end, block) {
 
 function findIosApplicationTarget(projectFile) {
   const contents = fs.readFileSync(projectFile, 'utf8');
+  if (contents.includes('COCOS_SDK_XCODE_PROJECT')) {
+    const { readProject, applicationTarget } = require('./install-spm.cjs');
+    return applicationTarget(readProject(projectFile))?.[1].name || null;
+  }
   const nativeTarget = /\/\* ([^*]+) \*\/ = \{\s*isa = PBXNativeTarget;([\s\S]*?)\n\s*\};/g;
   const targets = [];
   let match;
@@ -382,4 +396,58 @@ function escapeGroovy(value) { return value.replace(/\\/g, '\\\\').replace(/'/g,
 function escapeRuby(value) { return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'"); }
 function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
-module.exports = { installNative };
+function readIosDependencyManager(buildRoot, extensionRoot) {
+  for (const start of [buildRoot, extensionRoot]) {
+    let directory = path.resolve(start);
+    while (true) {
+      const file = path.join(directory, 'cocos-sdk.config.json');
+      if (fs.existsSync(file)) {
+        const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const manager = config.ios?.dependencyManager ?? 'cocoapods';
+        if (!['spm', 'cocoapods'].includes(manager)) {
+          throw new Error(`[cocos-sdk] Invalid ios.dependencyManager in ${file}: expected spm or cocoapods.`);
+        }
+        return manager;
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return 'cocoapods';
+}
+
+function migrateManagedPods(podfiles, logger) {
+  for (const file of podfiles) {
+    const original = fs.readFileSync(file, 'utf8');
+    let next = original;
+    for (const [begin, end] of [
+      [POD_BEGIN, POD_END], [LEGACY_POD_BEGIN, LEGACY_POD_END], [LEGACY_BEGIN, LEGACY_END],
+      ['# COCOS_HYBRID_SAMPLE_BEGIN', '# COCOS_HYBRID_SAMPLE_END'],
+    ]) next = next.replace(markedPattern(begin, end), '');
+    if (/^\s*pod\s+['"](?:FTCocosBridge|HybridSampleHost|GuanceSDK)(?:\/[^'"]*)?['"]/m.test(next)) {
+      throw new Error(`[cocos-sdk] Remove the manually declared native SDK Pod from ${file} before switching to SPM.`);
+    }
+    if (next !== original) fs.writeFileSync(file, next);
+    const directory = path.dirname(file);
+    const existingLock = path.join(directory, 'Podfile.lock');
+    const hasSDKPods = fs.existsSync(existingLock)
+      && /^\s*- (?:FTCocosBridge|HybridSampleHost|GuanceSDK)(?:\/|\s|:)/m.test(fs.readFileSync(existingLock, 'utf8'));
+    if (next === original && !hasSDKPods) continue;
+    if (fs.existsSync(path.join(directory, 'Podfile.lock')) || fs.existsSync(path.join(directory, 'Pods'))) {
+      logger.info('[cocos-sdk] Updating existing Pods integration for the SPM switch.');
+      try {
+        execFileSync('pod', ['install'], { cwd: directory, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+      } catch (error) {
+        fs.writeFileSync(file, original);
+        throw new Error(`[cocos-sdk] Unable to update existing Pods in ${directory}: ${error.message}`);
+      }
+      const lock = path.join(directory, 'Podfile.lock');
+      if (fs.existsSync(lock) && /^\s*- GuanceSDK(?:\/|\s|:)/m.test(fs.readFileSync(lock, 'utf8'))) {
+        throw new Error(`[cocos-sdk] Another Pod still depends on the native SDK in ${lock}; migrate that dependency before using SPM.`);
+      }
+    }
+  }
+}
+
+module.exports = { installNative, readIosDependencyManager };

package/extensions/creator3/install-spm.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const { execFileSync } = require('child_process');
+
+function readProject(file) {
+  // plutil understands both Xcode's OpenStep format and XML plists, without Ruby/gems.
+  return JSON.parse(execFileSync('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file], {
+    encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  }));
+}
+
+function writeProject(file, project) {
+  const next = `// !$*UTF8*$!\n// COCOS_SDK_XCODE_PROJECT\n${serialize(project)}\n`;
+  if (fs.readFileSync(file, 'utf8') !== next) fs.writeFileSync(file, next);
+}
+
+function serialize(value, depth = 0) {
+  const indent = '\t'.repeat(depth);
+  if (Array.isArray(value)) {
+    return `(\n${value.map((entry) => `${indent}\t${serialize(entry, depth + 1)},\n`).join('')}${indent})`;
+  }
+  if (value && typeof value === 'object') {
+    return `{\n${Object.entries(value).sort(([a], [b]) => a === 'isa' ? -1 : b === 'isa' ? 1 : a.localeCompare(b)).map(([key, entry]) => (
+      `${indent}\t${serialize(key)} = ${serialize(entry, depth + 1)};\n`
+    )).join('')}${indent}}`;
+  }
+  const text = String(value);
+  return /^[A-Za-z0-9_./]+$/.test(text) ? text : JSON.stringify(text);
+}
+
+function applicationTarget(project, preferredName) {
+  const targets = Object.entries(project.objects).filter(([, object]) => (
+    object.isa === 'PBXNativeTarget' && object.productType === 'com.apple.product-type.application'
+  ));
+  return targets.find(([, object]) => object.name === preferredName)
+    || targets.find(([, object]) => /(?:^|[-_.])(?:mobile|ios)$/i.test(object.name))
+    || targets[0];
+}
+
+function add(list, value) {
+  if (!list.includes(value)) list.push(value);
+}
+
+function identifier(value) {
+  return createHash('sha256').update(`cocos-sdk:${value}`).digest('hex').slice(0, 24).toUpperCase();
+}
+
+function installSwiftPackage(projectFile, packageDirectory, productName, targetName) {
+  if (!fs.existsSync(path.join(packageDirectory, 'Package.swift'))) {
+    throw new Error(`[cocos-sdk] Missing Swift package: ${packageDirectory}`);
+  }
+  const project = readProject(projectFile);
+  const selected = applicationTarget(project, targetName);
+  if (!selected) throw new Error(`[cocos-sdk] No application target in ${projectFile}`);
+  const [targetID, target] = selected;
+  const objects = project.objects;
+  const root = objects[project.rootObject];
+  const projectDirectory = path.resolve(path.dirname(path.dirname(projectFile)), root.projectDirPath || '.');
+  const relativePath = path.relative(projectDirectory, packageDirectory).split(path.sep).join('/');
+  const packageID = identifier(`package:${productName}`);
+  const productID = identifier(`product:${targetID}:${productName}`);
+  const buildID = identifier(`framework:${targetID}:${productName}`);
+  const existing = (target.packageProductDependencies || []).find((id) => (
+    id !== productID && objects[id]?.productName === productName
+  ));
+  if (existing) throw new Error(`[cocos-sdk] ${productName} is already managed manually in ${target.name}; remove that reference before automatic installation.`);
+
+  objects[packageID] = { isa: 'XCLocalSwiftPackageReference', relativePath };
+  objects[productID] = { isa: 'XCSwiftPackageProductDependency', productName };
+  objects[buildID] = { isa: 'PBXBuildFile', productRef: productID };
+  add(root.packageReferences ||= [], packageID);
+  add(target.packageProductDependencies ||= [], productID);
+  let phaseID = (target.buildPhases || []).find((id) => objects[id]?.isa === 'PBXFrameworksBuildPhase');
+  if (!phaseID) {
+    phaseID = identifier(`frameworks:${targetID}`);
+    objects[phaseID] = { isa: 'PBXFrameworksBuildPhase', buildActionMask: '2147483647', files: [], runOnlyForDeploymentPostprocessing: '0' };
+    add(target.buildPhases ||= [], phaseID);
+  }
+  add(objects[phaseID].files ||= [], buildID);
+  const configurations = objects[target.buildConfigurationList]?.buildConfigurations || [];
+  for (const configID of configurations) {
+    const settings = objects[configID].buildSettings ||= {};
+    const flags = settings.OTHER_LDFLAGS;
+    if (Array.isArray(flags)) {
+      add(flags, '$(inherited)');
+      add(flags, '-ObjC');
+    } else {
+      const parts = [flags || '$(inherited)'];
+      if (!String(flags || '').includes('$(inherited)')) add(parts, '$(inherited)');
+      if (!/(?:^|\s)-ObjC(?:\s|$)/.test(flags || '')) add(parts, '-ObjC');
+      settings.OTHER_LDFLAGS = parts.join(' ');
+    }
+    if (Number(settings.IPHONEOS_DEPLOYMENT_TARGET || 0) < 12) settings.IPHONEOS_DEPLOYMENT_TARGET = '12.0';
+    settings.CLANG_ENABLE_MODULES = 'YES';
+  }
+  preserveCmakeIntegration(projectFile, project, { packageDirectory, productName, targetName: target.name });
+  writeProject(projectFile, project);
+}
+
+const RESTORE_BEGIN = '# COCOS_SDK_SPM_RESTORE_BEGIN';
+const RESTORE_END = '# COCOS_SDK_SPM_RESTORE_END';
+const restorePattern = /\n?# COCOS_SDK_SPM_RESTORE_BEGIN[\s\S]*?# COCOS_SDK_SPM_RESTORE_END\n?/g;
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function preserveCmakeIntegration(projectFile, project, entry) {
+  const objects = project.objects;
+  const zeroCheck = Object.values(objects).find((object) => object.name === 'ZERO_CHECK');
+  if (!zeroCheck) return;
+  // CMake's SYMROOT/OBJROOT overrides select Xcode's legacy build locations,
+  // which reject packages. Keep CONFIGURATION_BUILD_DIR (engine archives).
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  const state = fs.existsSync(stateFile)
+    ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { packages: [], buildLocations: {} };
+  for (const [id, object] of Object.entries(objects)) {
+    if (object.isa !== 'XCBuildConfiguration') continue;
+    for (const key of ['SYMROOT', 'OBJROOT']) {
+      if (object.buildSettings?.[key] === undefined) continue;
+      (state.buildLocations[id] ||= {})[key] = object.buildSettings[key];
+      delete object.buildSettings[key];
+    }
+  }
+  const relativeDirectory = path.relative(path.dirname(projectFile), entry.packageDirectory);
+  state.packages = state.packages.filter((item) => item.productName !== entry.productName);
+  state.packages.push({ ...entry, packageDirectory: relativeDirectory });
+  state.packages.sort((a, b) => a.productName.localeCompare(b.productName));
+  const helper = path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs');
+  if (path.resolve(helper) !== path.resolve(__filename)) fs.copyFileSync(__filename, helper);
+  const restore = [
+    RESTORE_BEGIN,
+    `${process.versions.electron ? 'ELECTRON_RUN_AS_NODE=1 ' : ''}${shellQuote(process.execPath)} ${shellQuote(helper)} --restore`,
+    RESTORE_END,
+  ].join('\n');
+  for (const id of zeroCheck.buildPhases || []) {
+    const phase = objects[id];
+    if (phase?.isa !== 'PBXShellScriptBuildPhase') continue;
+    phase.shellScript = `${(phase.shellScript || '').replace(restorePattern, '').trimEnd()}\n${restore}\n`;
+  }
+  const serialized = `${JSON.stringify(state, null, 2)}\n`;
+  if (!fs.existsSync(stateFile) || fs.readFileSync(stateFile, 'utf8') !== serialized) fs.writeFileSync(stateFile, serialized);
+}
+
+function removeSwiftPackages(projectFile) {
+  const project = readProject(projectFile);
+  const objects = project.objects;
+  const removed = new Set();
+  for (const productName of ['FTCocosBridge', 'HybridSampleHost']) {
+    const packageID = identifier(`package:${productName}`);
+    if (!objects[packageID]) continue;
+    removed.add(packageID);
+    for (const [id, object] of Object.entries(objects)) {
+      if (object.isa !== 'PBXNativeTarget') continue;
+      removed.add(identifier(`product:${id}:${productName}`));
+      removed.add(identifier(`framework:${id}:${productName}`));
+    }
+  }
+  if (!removed.size) return;
+  for (const id of removed) delete objects[id];
+  for (const object of Object.values(objects)) {
+    for (const key of ['packageReferences', 'packageProductDependencies', 'files']) {
+      if (Array.isArray(object[key])) object[key] = object[key].filter((id) => !removed.has(id));
+    }
+    if (object.isa === 'PBXShellScriptBuildPhase') object.shellScript = (object.shellScript || '').replace(restorePattern, '');
+  }
+  const stateFile = path.join(path.dirname(projectFile), 'cocos-sdk-spm.json');
+  if (fs.existsSync(stateFile)) {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    for (const [id, settings] of Object.entries(state.buildLocations)) {
+      if (objects[id]) Object.assign(objects[id].buildSettings ||= {}, settings);
+    }
+    fs.unlinkSync(stateFile);
+    fs.rmSync(path.join(path.dirname(projectFile), 'cocos-sdk-spm.cjs'), { force: true });
+  }
+  writeProject(projectFile, project);
+}
+
+module.exports = { installSwiftPackage, removeSwiftPackages, readProject, applicationTarget };
+
+if (require.main === module && process.argv[2] === '--restore') {
+  const directory = path.dirname(__filename);
+  const state = JSON.parse(fs.readFileSync(path.join(directory, 'cocos-sdk-spm.json'), 'utf8'));
+  for (const item of state.packages) {
+    installSwiftPackage(path.join(directory, 'project.pbxproj'), path.resolve(directory, item.packageDirectory), item.productName, item.targetName);
+  }
+}

package/native/ios/FTCocosBridge.m

@@ -1,7 +1,14 @@
 #import "FTCocosBridge.h"
 #import "FTCocosReplayImageJobs.h"
 
-#import "FTMobileSDK.h"
+#import "FTMobileAgent.h"
+#import "FTSDKConfig.h"
+#import "FTRumConfig.h"
+#import "FTLoggerConfig.h"
+#import "FTMobileConfig.h"
+#import "FTExternalDataManager.h"
+#import "FTResourceMetricsModel.h"
+#import "FTResourceContentModel.h"
 #import "FTSessionReplay.h"
 #import <UIKit/UIKit.h>
 #import <objc/message.h>

package/native/ios/FTCocosBridge.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'FTCocosBridge'
-  s.version          = '0.1.0-alpha.4'
+  s.version          = '0.1.0-alpha.5'
   s.summary          = 'CloudCare Mobile SDK native bridge for Cocos Creator.'
   s.homepage         = 'https://github.com/GuanceCloud/datakit-cocos'
   s.license          = { :type => 'Apache-2.0' }
@@ -13,6 +13,6 @@ Pod::Spec.new do |s|
   # Cocos resolves FTCocosBridge by class name at runtime, so no direct symbol
   # reference would otherwise keep the Objective-C category/class in the app.
   s.user_target_xcconfig = { 'OTHER_LDFLAGS' => '$(inherited) -ObjC' }
-  s.dependency 'GuanceSDK/Agent', '1.6.8-alpha.2'
-  s.dependency 'GuanceSDK/FTSessionReplay', '1.6.8-alpha.2'
+  s.dependency 'GuanceSDK/Agent', '1.6.8-alpha.5'
+  s.dependency 'GuanceSDK/FTSessionReplay', '1.6.8-alpha.5'
 end

package/native/ios/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version:5.3
+import PackageDescription
+
+let package = Package(
+    name: "FTCocosBridge",
+    platforms: [.iOS(.v12)],
+    products: [.library(name: "FTCocosBridge", targets: ["FTCocosBridge"])],
+    dependencies: [
+        .package(url: "https://github.com/GuanceCloud/datakit-ios.git", .exact("1.6.8-alpha.5")),
+    ],
+    targets: [
+        .target(
+            name: "FTCocosBridge",
+            dependencies: [
+                .product(name: "GuanceSDK", package: "datakit-ios"),
+                .product(name: "GuanceSessionReplay", package: "datakit-ios"),
+            ],
+            path: ".",
+            exclude: ["FTCocosBridge.podspec"],
+            sources: ["FTCocosBridge.m", "FTCocosReplayImageJobs.m"],
+            publicHeadersPath: "include",
+            cSettings: [.headerSearchPath(".")],
+            linkerSettings: [.linkedFramework("UIKit")]
+        ),
+    ]
+)

package/native/ios/include/FTCocosBridge.h

@@ -0,0 +1,2 @@
+// Keep the public SPM header in sync with the CocoaPods/source integration.
+#import "../FTCocosBridge.h"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcare/cocos-sdk",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "description": "Observability SDK integration for Cocos Creator 2.4 and 3.x",
   "license": "Apache-2.0",
   "author": "Guance Cloud",