Integrate the Connect SDK into a Cordova app

Edit the root index.html — the Vite template, not www/index.html. Add connect-config.js after cordova.js:

<script src="cordova.js"></script>
<script src="js/connect-config.js"></script>

In a Debug build with "useRelease": false in ConnectConfig.json (the default), verbose native logging from the SDK's Connect, Tealeaf, and EOCore modules is written to the Xcode console. To enable it, add the following environment variables to your scheme under Run → Arguments → Environment Variables:

A Release-configuration build won't produce verbose output, even with useRelease: false. For verbose logs, run a Debug build.

Verbose logging is on by default when useRelease is false.

Run the app, then filter the Xcode console by Connect: to isolate the key SDK lifecycle events. Look for these entries to confirm the SDK is running:

The following entries are expected and safe to ignore:

Run the app, then filter Logcat by the tags ConnectPlugin, Tealeaf, EOCore, and Connect to isolate SDK output. Look for this entry to confirm the SDK is running:

The following entries are expected and safe to ignore:

pod install / npx cordova build ios fails: command not found: pod

CocoaPods isn't installed. Run sudo gem install cocoapods && pod repo update. On Apple Silicon, an outdated ffi gem can also break pod install — if gem install cocoapods itself fails, try sudo gem install ffi.

Undefined symbols / "Framework not found Pods_App" at build time

You opened platforms/ios/App.xcodeproj instead of the CocoaPods-generated workspace. Always open platforms/ios/App.xcworkspace after npx cordova prepare ios / npx cordova build ios.

CocoaPods platform-compatibility error naming AcousticConnect / AcousticConnectDebug

Your project's deployment-target is below the plugin's minimum of 15.1. Remove any config.xml override below 15.1, or raise it to at least 15.1.

CocoaPods LD_RUNPATH_SEARCH_PATHS override warnings

npx cordova prepare may produce warnings like:

[!] The `App [Debug]` target overrides the `LD_RUNPATH_SEARCH_PATHS` build setting defined in `Pods-App.debug.xcconfig`. This can lead to problems with the CocoaPods installation.

cordova-ios generates project.pbxproj with a hardcoded LD_RUNPATH_SEARCH_PATHS value that doesn't include $(inherited), so CocoaPods' xcconfig paths are silently overridden. Any manual fix in Xcode Build Settings is overwritten on the next npx cordova prepare. Apply the fix via an after_prepare hook instead so it persists across prepares:

module.exports = function (context) {
  const platforms = context.opts.platforms;
  if (platforms.length > 0 && !platforms.includes('ios')) return;

  const path = require('path');
  const fs   = require('fs');

  const pbxprojPath = path.join(
    context.opts.projectRoot,
    'platforms', 'ios', '<YourApp>.xcodeproj', 'project.pbxproj'
  );
  if (!fs.existsSync(pbxprojPath)) return;

  let src = fs.readFileSync(pbxprojPath, 'utf8');
  const PATTERN     = /LD_RUNPATH_SEARCH_PATHS = "(?!\$\(inherited\))([^"]+)";/g;
  const REPLACEMENT = 'LD_RUNPATH_SEARCH_PATHS = "$(inherited) $1";';
  if (!PATTERN.test(src)) return;

  PATTERN.lastIndex = 0;
  fs.writeFileSync(pbxprojPath, src.replace(PATTERN, REPLACEMENT), 'utf8');
};

Register it in config.xml under the iOS platform block:

<platform name="ios">
  <hook type="after_prepare" src="hooks/after_prepare_ld_runpath.js" />
</platform>

The hook patches the pbxproj on the first prepare and skips cleanly on subsequent runs.

"Unsupported Swift Version" dialog on opening the workspace

After running npx cordova prepare ios and opening the .xcworkspace, Xcode may present an "Unsupported Swift Version" dialog for the Connect plugin. This happens because cordova-ios doesn't set SWIFT_VERSION in the generated project.

Dismiss the dialog, then set the version manually: select the project in the Xcode navigator, go to Build Settings, search for Swift Language Version, and set it to Swift 5.

Manifest merger failed: minSdkVersion too low

The plugin requires API 26. If your project's minSdkVersion is lower, raise it in config.xml (<preference name="android-minSdkVersion" value="26" />) or your platform override.

ConnectConfig.json not found

npx cordova prepare fails with this error until you add ConnectConfig.json at your Cordova project root — the plugin doesn't generate it for you. See Initial setup, step 2.

SDK initializes but no session appears in Connect

Two common causes:

• Collector mismatch. PostMessageUrl points to a different collector node than the one where your app is registered. Verify the app key and collector URL in your Connect account, update ConnectConfig.json, and rebuild.
• App closed before flush. The SDK flushes session data when the app goes to background. If the app or emulator is closed immediately, the flush may not complete. Put the app in the background and wait a few seconds before closing.