This page documents the public API of cordova-acoustic-connect. All methods are Promise-based and available in both JavaScript and TypeScript.

Language: JavaScript, with TypeScript definitions

Package: cordova-acoustic-connect

Availability: Pro, Premium, and Ultimate

Imports

The plugin exposes a single object, AcousticConnect, in two equivalent forms:

Global — installed on window via the plugin's <clobbers> entry. Available to any <script>-based Cordova app once deviceready fires, with no import needed.

document.addEventListener('deviceready', function () {
  AcousticConnect.enable(/* ... */);
}, false);

Module export — the same object is also exported via CommonJS/ES module (main/types in package.json), for apps that bundle their JavaScript.

const AcousticConnect = require('cordova-acoustic-connect');

All examples on this page use the global form, matching the rest of this SDK's Cordova documentation.

SDK lifecycle

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

Initializes and enables the Connect SDK. Must be called from the deviceready handler before any other plugin method.

AcousticConnect.enable(
  appKey: string,
  postURL: string,
  pushMode?: 'automatic' | 'manual',   // defaults to 'automatic'
  options?: {
    iosAppGroupIdentifier?: string,    // iOS only
    androidIconResName?: string        // Android only
  }
): Promise<void>

Return value. Promise<void>. Rejects with { code, message } if appKey or postURL is empty after trimming, if pushMode isn't 'automatic' or 'manual', or if the native SDK fails to start.

Example

document.addEventListener('deviceready', async function () {
  try {
    await AcousticConnect.enable(
      'your-app-key',
      'https://your-collector-url',
      'automatic'
    );
  } catch (error) {
    console.error('enable failed:', error);
  }
}, false);

disable()

Stops all data capture and push activity.

AcousticConnect.disable(): Promise<void>

Call enable() again to resume.

setLogLevel(level)

Sets the bridge's own log level.

AcousticConnect.setLogLevel(
  level: 'silent' | 'error' | 'warn' | 'info' | 'verbose'
): Promise<void>

Return value. Promise<void>. Rejects with { code, message } if level isn't one of the five supported values.

User identity

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

Logs an identity signal, associating the current session with a known Connect contact.

AcousticConnect.logIdentity(
  identifierName: string,
  identifierValue: string,
  signalType?: string,                        // defaults to 'loggedIn'
  additionalParameters?: Record<string, string>
): Promise<void>

Return value. Promise<void>. Rejects with { code, message } if identifierName or identifierValue is empty after trimming, or if the SDK isn't enabled yet.

Example

// Sign-in
await AcousticConnect.logIdentity('Email Address', '[email protected]', 'loggedIn', {
  loginMethod: 'email',
});

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

For complete guidance on each signal, see Identify users at sign-in and Identify users at registration.

Push notifications

Methods are namespaced under AcousticConnect.push.

Permission management

push.requestPermission()

Presents the OS-level push permission dialog, if the state is undetermined.

AcousticConnect.push.requestPermission(): Promise<{ granted: boolean, error?: string }>

Returns a PushPermissionResult. Always resolves — never rejects.

push.getPermissionState()

Reads the current notification permission state without prompting.

AcousticConnect.push.getPermissionState(): Promise<boolean | null>

Returns true (granted), false (denied), or null (not yet determined).

push.didReceiveAuthorization(granted, error?)

Forwards an externally-obtained permission result to the SDK — for example, if your app manages permissions through its own permission library rather than push.requestPermission().

AcousticConnect.push.didReceiveAuthorization(
  granted: boolean | null,
  error?: string
): Promise<boolean>

If granted is null or omitted, the call resolves false without reaching native code — the native SDKs on both platforms require a non-optional boolean.

Manual mode forwarders

These methods only apply when enable() was called with pushMode: 'manual'. In 'automatic' mode (the default), the SDK owns the native push delegate and these forwarders aren't needed.

push.didReceiveNotification(userInfo)

Forwards a received notification to the SDK so it can log a pushReceived signal.

AcousticConnect.push.didReceiveNotification(
  userInfo: Record<string, string | number | boolean>
): Promise<boolean>

Returns false in automatic mode.

push.didReceiveResponse(actionIdentifier, userInfo)

Forwards a notification response (tap or action) to the SDK.

AcousticConnect.push.didReceiveResponse(
  actionIdentifier: string,
  userInfo: Record<string, string | number | boolean>
): Promise<boolean>

Returns false in automatic mode.

For setup steps and mode selection, see Enable push notifications in a Cordova app (iOS) and Enable push notifications in a Cordova app (Android).

Type reference

PushPermissionResult

Result of a push.requestPermission() call.

AcousticError

Structured rejection returned by enable() and logIdentity().