cordova-acoustic-connect

Cordova插件 声连接 （CDP + engagement）。封装原生的iOS和Android Connect sdk，并公开一个基于promise的JavaScript API， AcousticConnect，到你的Cordova应用程序。

需求

安装

npx cordova plugin add cordova-acoustic-connect-beta

配置

创建 ConnectConfig.json 在你的Cordova项目根目录下（被忽略了——永远不要提交真正的凭据）：

{
  "Connect": {
    "AppKey": "<your-app-key>",
    "PostMessageUrl": "<your-collector-url>",
    "useRelease": false,
    "iOSAppGroupIdentifier": "group.<your-bundle-id>",
    "iOSDevelopmentTeam": "<your-apple-team-id>",
    "AndroidVersion": "<optional-connect-android-sdk-version-override>",
    "iOSVersion": "<optional-connect-ios-sdk-version-override>",
    "PushEnabled": true,
    "iOSPushMode": "automatic",
    "AndroidNotificationIconResName": "<optional-drawable-name>",
    "KillSwitchEnabled": false,
    "KillSwitchUrl": "<optional-kill-switch-url>"
  }
}

杀死开关

这两个原生sdk都默认开启了终止开关(KillSwitchEnabled=true）; 这个插件强制关闭它，除非你选择通过 KillSwitchEnabled: true + KillSwitchUrl。

• iOS： ConnectPlugin.swift的 enable() 调用 applyKillSwitchConfig() 之前 和 后 ConnectSDK.shared.enable(...) - SDK可能会重新加载其绑定的plist默认值(KillSwitchEnabled=true)，因此配置的值被重新应用两次，以使其保持不变。
• 安卓： ConnectBasicConfig.properties 集合 KillSwitchEnabled 在资产加载时，但这并不是最后的定论-原生SDK的2-arg Tealeaf.enable(appKey, postMessageUrl) (这 handleEnable() 调用)有一个无条件设置的内部处理程序 KillSwitchEnabled=true 并计算自己的URL，一次，在被调用后约100ms。 ConnectPlugin.kt 通过重新应用配置的值 Connect.updateConfig(...) 300毫秒后 Connect.enable(...)，轻松通过窗口，因此值（on或off）实际上是固定的。0参数绑定的auto-init路径(tryBundledConfigInit)根本没有击中这个内部处理程序，所以properties-file值已经正确地应用在那里，而不需要重新应用。

设备上验证：with KillSwitchEnabled: true 和一个真实的 KillSwitchUrl， Android SDK日志 KillSwitchEnabled:true 和 Killswitch has enabled Tealeaf with following session id:... -真正的异步kill-switch检查运行并完成。

插件的 before_prepare Hook在每个节点上读取这个文件 cordova prepare / cordova build。 Connect.useRelease 是使用本机SDK变体的单一事实来源，以及本机SDK日志记录是否冗长：

• true → AcousticConnect （发布）pod在iOS上，发布连接工件在Android上。在Android上, ConnectPlugin.kt 也称 Connect.updateConfig("DisplayLogging", "false", EOCore.getInstance()) 之后 Connect.init() 原生（Tealeaf/EOCore/Connect） logcat输出被抑制，不管应用的Gradle构建类型。
• false (默认)→ AcousticConnectDebug iOS上的pod， Android上的详细本地logcat输出（SDK自己的默认值，保持不变）。Android总是使用相同的 connect-push-fcm Maven工件，不管 useRelease 没有单独的调试Maven构件。这个标志决定了Android从哪里解析Connect: with false github托管的Maven树(go-acoustic/Android_Maven，发布Connect测试版；它们不会到达Maven Central)在谷歌和Maven Central之后声明，仅限于 io.github.go-acoustic 集团;与 true 只使用Maven Central，拒绝所有测试版。它还会选择插件的默认Android版本： 11.1.30-beta β与 false, 11.1.17 发布与 true。

旗子通过 www/AcousticConnectNativeConfig.json (与iOS原生配置一起生成，捆绑到 assets/www/ （by Cordova） -故意不通过应用程序级别 EOCoreBasicConfig.properties 资产覆盖，因为Android的资产合并取代 整个 文件上的名称冲突和SDK的捆绑默认携带其他几个必需的密钥(例如。 PostMessageTimeInterval)，部分覆盖会悄无声息地下降，并在 enable() 时间。

Android在每次构建时都会读取新标记；iOS将CocoaPods的pod名称命名为 plugin.xml 当插件被安装后，所以修改 useRelease 你必须删除并重新添加插件才能生效：

npx cordova plugin rm co.acoustic.connect.push
npx cordova plugin add cordova-acoustic-connect-beta
npx cordova prepare ios

一个完整的 cordova platform rm ios && cordova platform add ios 是 不 这是必需的-早期版本的插件留下了陈旧 "[CP] Prepare AcousticConnectDebug xcframeworks" (或 AcousticConnect)脚本阶段落后于 ConnectNSE/ConnectNCE 调试↔释放开关后的目标，其参考 .xcfilelist 转换后不再存在，并且构建失败 Unable to load contents of file list: ...． 插件的 after_prepare hook现在在添加当前版本之前从以前的SDK变体中删除任何此类过时的阶段 plugin rm/add 以上的工作流程就足够了。

注意： useRelease 只控制本机SDK自己的logcat输出。插件桥自己的日志级别(ConnectPlugin.kt)分别通过 AcousticConnect.setLogLevel() 从JavaScript。

快速启动

document.addEventListener('deviceready', async function () {
  await AcousticConnect.enable(
    'your-app-key',
    'https://your-collector-url',
    'automatic'
  );

  await AcousticConnect.logIdentity('email', '[email protected]', 'loggedIn');
}, false);

AcousticConnect 可用作为CommonJS/ES模块导出和作为全局on window (安装通过插件的 <clobbers> 条目)，因此可以从plain访问它 <script>基于Cordova的应用程序或从 import/require。

API参考

AcousticConnect.enable(appKey, postURL, pushMode?, options?)

初始化并启用Connect SDK。必须从 deviceready 处理程序在任何其他插件方法之前。

• appKey: string
• postURL: string
• pushMode?: 'automatic' | 'manual' -默认为 'automatic'
• options?: { iosAppGroupIdentifier?: string, androidIconResName?: string }
• 返回 Promise<void>，拒绝 { code, message } 无效参数或本机SDK启动失败。

AcousticConnect.disable()

停止所有数据捕获和推送活动。返回 Promise<void>。

AcousticConnect.setLogLevel(level)

level: 'silent' | 'error' | 'warn' | 'info' | 'verbose'． 仅影响网桥日志记录。返回 Promise<void>。

AcousticConnect.logIdentity(identifierName, identifierValue, signalType?, additionalParameters?)

将身份信号记录到Connect SDK中。

• identifierName: string ——如。 'email'， 'userId'
• identifierValue: string ——如。 '[email protected]'
• signalType?: string -默认为 'loggedIn'
• additionalParameters?: Record<string, string>
• 返回 Promise<void>

常见的电话:

// Login
AcousticConnect.logIdentity('email', '[email protected]', 'loggedIn', { loginMethod: 'email' });

// Registration
AcousticConnect.logIdentity('email', '[email protected]', 'accountRegistered', { registrationMethod: 'email' });

分析

所有分析方法返回 Promise<void> 然后拒绝 { code, message } （ACOUSTIC_INVALID_ARGS 对于糟糕的论点)。已解决的承诺意味着SDK 排队 事件;这并不意味着收藏者拥有它。事件在设备上批处理并稍后发布，通常在应用程序进入后台时发布。

await AcousticConnect.setCurrentScreenName('checkout');
await AcousticConnect.logScreenViewContextLoad('checkout', 'cart');
await AcousticConnect.logCustomEvent('coupon_applied', { code: 'SPRING', amount: 10 });
await AcousticConnect.logClickEvent('btnPay', { method: 'card' });
await AcousticConnect.logTextChangeEvent('txtEmail', { text: email });   // masked

注意事项：

• 页面内的点击和输入不会被自动捕获。 原生SDK无法看到WebView中的DOM事件，所以调用 logClickEvent / logTextChangeEvent 你自己（或你自己的听众）。原生控件事件api没有被使用：在设备上，iOS拒绝每个视图使用它们，而Android报告整个WebView作为目标。
• logCustomEvent 和 logSignal 每个平台上的有效载荷形状不同。 iOS将它们嵌套在 data.value （自定义事件）和 signal.data.value (信号);Android则不然。Android也将每个自定义事件的值作为字符串传递，iOS则保留JSON类型。在查询数据时请记住这一点。
• logSignal 在Android上: 之前连接Android SDK版本 11.0.24-beta 在 顶级 有效负载（到达字符串和布尔值；嵌套在对象或数组中的数字不受影响）。观察到在 11.0.21-beta； 11.1.10-beta 发送它（在模拟器上检查），插件的默认值也是如此。只有当你干掉一个老家伙时才有意义 AndroidVersion：然后嵌套数值。

运行时配置项

await AcousticConnect.setConfigItem('DisplayLogging', true, 'EOCore');
const interval = await AcousticConnect.getConfigItem('PostMessageTimeInterval', 0, 'EOCore'); // number

setConfigItem(key, value, moduleName) 接受布尔值、字符串或有限数。 getConfigItem(key, defaultValue, moduleName) 返回类型的值 defaultValue，并在未设置项或不适合该类型时返回默认值 false 保持 false）.

一个可以解析的集合意味着SDK接受了该项，而不是它改变了行为：大多数项在SDK启动时被读取，所以在此之前设置它们 enable() 在你可以的地方。这两个调用都需要初始化SDK；在此之前, setConfigItem Android上的拒绝。

屏幕截图和隐私

默认情况下，本机SDK捕获视图层次结构和 截图 每个屏幕的。在iOS上，我们可以在每次测试中观察到这一点：屏幕图像的布局信息（类型10）加上屏幕视图本身。在Cordova应用程序中，页面是一个WebView，所以屏幕截图显示页面显示的内容，包括个人数据。

本地屏蔽规则(Masking 内部 AutoLayout)适用于 仅本地控件． 它们不会屏蔽WebView中的文本——WebView显示为一个控件。若要将页面内容排除在捕获之外，请关闭捕获：

{ "Connect": { "ScreenCaptureEnabled": false } }

Android上的布局。 Android SDK从WebView屏幕发送一个布局（类型10） 11.1.10-beta，比插件的默认值更老：在此之前，它等待页面内的Tealeaf web库的id，然后放弃布局。该插件还保留SDK的捕获设置(PrintScreen， LogViewLayoutOnScreenTransition， ScreenshotFormat 和其他人)在 ConnectBasicConfig.properties 因为那个文件取代了SDK自己的；没有它们，SDK拒绝每个布局捕获。该页面没有Tealeaf web库，因此布局将WebView列为一个控件 dcid: "dcid-none" 没有页面内容。

layoutConfig， layoutConfigIos 和 layoutConfigAndroid 携带SDK自己的屏幕规则：

{
  "Connect": {
    "layoutConfig": {
      "AutoLayout": { "GlobalScreenSettings": { "CaptureLayoutDelay": 500 } }
    },
    "layoutConfigIos": {
      "AutoLayout": { "GlobalScreenSettings": { "CaptureLayoutOn": 0 } }
    }
  }
}

• 在构建时，平台块会深度合并到共享块之上（对象合并，数组被替换）。只有 AutoLayout 和 AppendMapIds 使用;其他键被忽略，并给出警告。
• iOS 将块合并到SDK生效的规则上，因此部分块保留其余部分。
• 安卓 将块写入 ConnectLayoutConfig.json 在应用资产中，which 替换SDK的整个布局配置． 给它一个完整的块或省略它；构建在以下情况下发出警告 AutoLayout.GlobalScreenSettings 不见了。 钩子生成 ConnectLayoutConfig.json (和 ConnectBasicConfig.properties)在你的Cordova项目根目录中 cordova prepare，所以把两者都加到你的 .gitignore。
• 只有 CaptureLayoutOn: 0 在iOS上生效。不要假定该键的其他值表示“开”。

AcousticConnect.push

与推送相关的方法，命名空间位于 push：

在 automatic push模式（默认），SDK拥有原生推送委托和 didReceiveNotification/didReceiveResponse 不需要货代。它们存在的目的是 manual 模式，其中应用拥有自己的本机委托。

关闭推断

集 "PushEnabled": false 在 ConnectConfig.json 对于仅用于分析的应用：没有Firebase，也没有 google-services.json Android上没有推送权限、App Group或通知扩展，iOS上没有通知权限对话框。 iOSAppGroupIdentifier， iOSPushMode 和 AndroidNotificationIconResName 那就没有效果了。

• Android在构建时读取设置(build-extras.gradle)， iOS期间 cordova prepare 在运行时。更改后运行 cordova prepare 和重建。
• 切换一个有推送的iOS项目： cordova prepare 以 ConnectNSE 和 ConnectNCE 目标从Xcode项目中取出它们的目标从Podfile中取出 remote-notification 背景模式关闭 Info.plist （当另一个插件或 config.xml 声明它，因为插件需要它)。应用程序组和 aps-environment 当push打开时插件添加的权利被保留，因为其他插件可能会共享它们：删除平台并重新添加(cordova platform rm ios && cordova platform add ios)来做一个没有他们的项目。
• 随着推离， push.requestPermission()， push.getPermissionState()， push.didReceiveAuthorization()， push.didReceiveNotification() 和 push.didReceiveResponse() 拒绝与 { code: 'ACOUSTIC_PUSH_DISABLED' }； enable() 忽略了它 pushMode 论点。
• react-native-acoustic-connect 和 capacitor-acoustic-connect 有相同的开关，但push默认是关闭的；这里它是默认打开的，这样现有的应用程序就不会改变。

iOS推送设置（Xcode）

构建完成后，打开生成的 .xcworkspace 在Xcode中:

1. 选择项目→ 签名和功能 →设置团队。
2. 添加 推送通知 能力。

后台模式→远程通知权限由插件(plugin.xml 配置文件)，不需要手动切换。

Android推送设置

放下一个真实的 google-services.json 到你的Cordova项目根目录（被忽略了）。插件的 after_prepare hook将其复制到每个生成的Android项目中 cordova prepare。

故障排除

常见的构建/推送问题和修复： TROUBLESHOOTING.md。

许可证

在无担保程序的声学许可下许可。看到 许可证 完整的学期。