Identify users at sign-in (Cordova)

The logged-in signal is how your Cordova app tells Connect who just authenticated. The SDK sends an identifier — typically a customer ID or email address — and Connect uses it to match the user to an existing contact or create one. Once the contact is known, marketers can target push notifications and re-engagement journeys to that person, and the rest of the session is attributed to their profile. For details on how Connect processes identification records, see How behavior signals are processed in Connect.

Language: JavaScript, with TypeScript definitions

Platforms: iOS and Android — the steps below apply to both. See Platform parity for details.

Availability: Pro, Premium, and Ultimate

How identification works

Two parameters do the identification work:

• identifierName — the contact attribute in Connect that the value should be matched against (for example, Customer ID or Email Address).
• identifierValue — the value itself.

signalType tells the backend which signal to record — pass 'loggedIn' (the default when omitted) to record this as a Logged In event. additionalParameters carries the signal's fields, including the required loginMethod — see Supported fields.

Choosing an identifier

Use the most stable identifier your authentication service returns:

1. Customer ID (preferred when available). If your Connect audience has a contact key attribute, use it — Connect matches incoming signals against this value to find or create the corresponding contact record.
2. Email address or phone number. Well-suited for identification when no customer ID is available. Map to the corresponding contact attribute in your Connect audience.

Populate multiple attributes at sign-in

logIdentity() populates one contact attribute per call. To set more than one, call it once per attribute, back-to-back, immediately after sign-in is confirmed:

await AcousticConnect.logIdentity('Customer ID', user.customerId, 'loggedIn', { loginMethod: 'email' });
await AcousticConnect.logIdentity('Email Address', user.email, 'loggedIn', { loginMethod: 'email' });

Use this pattern only at the sign-in moment itself. Don't use it to update an attribute later in the session, after sign-out, or across a sign-out/sign-in cycle.

Implementation considerations

Authentication timing

The logged-in signal must fire after authentication is confirmed — not when the user submits the sign-in form. For SSO/OAuth flows, fire it after the callback completes and the session is established.

Wire format

Pass every signal field as a top-level key in additionalParameters. The object is flat — the native bridge passes it straight through as a Record<string, string>; don't nest values.

Contact mapping

identifierName must match a contact attribute name exactly as it appears in Connect, including capitalization and spacing. To look up attribute names, in Connect go to Audience > Contacts > Attributes.

Platform parity

logIdentity() is a single bridge method. On iOS it dispatches to the native action logIdentificationEvent, which calls ConnectSDK.shared.identity.log(...) and then ConnectSDK.shared.flush(). On Android it calls Connect.logIdentificationEvent(...) and then Tealeaf.flushAll(false). Both flush immediately so Connect sees the signal without waiting for the next scheduled batch upload.

Configuration

The identity signal interface is available as soon as AcousticConnect.enable() has resolved.

Method

AcousticConnect.logIdentity(
  identifierName,        // string, required
  identifierValue,        // string, required
  signalType,             // string, optional — defaults to 'loggedIn'
  additionalParameters    // Record<string, string>, required — must include loginMethod
);
// returns Promise<void>

Parameters

Return value. Promise<void>. The promise rejects with { code, message } if identifierName or identifierValue is empty after trimming, or if the SDK isn't enabled yet — it does not resolve false on failure. Always wrap calls in try/catch or attach a .catch().

Supported fields in additionalParameters

Required

• loginMethod — any string identifying the authentication method, for example 'email', 'passwordless', or 'sso'. The backend requires this field and ignores the signal without it.

Optional

• name — short label for this signal instance.
• description — longer human-readable note describing the event.

Examples

Basic example

await AcousticConnect.logIdentity(
  'Email Address',
  user.email,
  'loggedIn',
  { loginMethod: 'email' }
);

Complete implementation example

async function handleSignIn(email, password) {
  try {
    const user = await authService.signIn(email, password);

    await AcousticConnect.logIdentity(
      'Email Address',
      user.email,
      'loggedIn',
      { loginMethod: 'email' }
    );

    navigateToDashboard();
  } catch (error) {
    console.error('logIdentity failed:', error);
  }
}

Returning users (silent sign-in on app launch)

If your app keeps the user signed in between sessions, fire the signal on app launch when you restore the session — not just on active sign-in:

document.addEventListener('deviceready', async function () {
  await AcousticConnect.enable(appKey, postURL);

  const storedEmail = localStorage.getItem('userEmail'); // or your storage of choice
  if (storedEmail) {
    await AcousticConnect.logIdentity('Email Address', storedEmail, 'loggedIn', {
      loginMethod: 'session-restore',
    });
  }
}, false);

Verify the signal

In the log

In Connect

Three options:

• Behavior studio > Signal management — select the Logged in signal type and find your signal in the list. Entries are clickable — open one to inspect its content. If the signal is formatted incorrectly, an error message appears.

• Audience > Contacts — search for the email address or customer ID you used. A new contact will be created if one didn't exist. Open the contact and check its activity feed for the signal.

• Behavior studio > Session intelligence (Premium and Ultimate) — find your session and inspect all signals recorded in it.

Troubleshooting

Signal not appearing in Connect?

• Verify identifierName and identifierValue are not empty or whitespace-only — the call rejects if either is blank after trimming.
• Confirm you called AcousticConnect.enable() first and awaited it. On iOS specifically, calling logIdentity() before enable() resolves rejects with ACOUSTIC_INTERNAL_ERROR ("SDK is not ready").
• Check the log entries in Verify the signal above — if the signal appears in the log but not in Connect, the issue is likely a collector mismatch or identifierName case error.

Contact not created or updated?

• Verify identifierName matches a contact attribute defined in Connect exactly, including capitalization and spacing.
• All values in additionalParameters must be strings. If the matching Connect attribute is typed as number, Boolean, or date, pass a string representation (for example, '42', 'true', or an ISO 8601 date string).