Identify users at sign-in (React Native)

The logged in signal is how your React Native 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: TypeScript and JavaScript

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

Availability: Pro, Premium, and Ultimate

Requires: Connect React Native SDK version 19.0.9

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' to record this as a Logged In event. additionalParameters is descriptive metadata about how the user logged in; it is stored alongside the signal but does not affect contact matching.

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. The attribute is often named Customer ID, but in loyalty-driven apps it can be a loyalty number; either way, it points at the same contactKey in your Connect audience.
2. Email address or phone number. Both are standard channels in Connect and are well-suited for identification when no customer ID is available. Map to the corresponding contact attribute in your Connect audience — commonly named something like "Email Address" or "Phone Number", but the exact name varies by audience.

Populate multiple attributes at sign-in

logIdentity() populates one contact attribute per call. To set more than one — for example, both a customer ID and an email address on the same contact — call it once per attribute, back-to-back, immediately after sign-in is confirmed. Connect attributes both signals to the same session and resolves them to the same contact.

await AcousticConnectRN.logIdentity(
  'Customer ID',
  user.customerId,
  'loggedIn',
  { loginMethod: 'email' }
)

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

Use this pattern only at the sign-in moment itself, when the two calls fire back-to-back in the same authenticated user context. Do not use it to update an attribute later in the user's session, after sign-out, or across a sign-out / sign-in cycle: the session is not tied to your app's auth state, and a later call could resolve to a different contact than you expect.

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 and OAuth flows, the signal cannot fire until after the callback completes and the session is established server-side.

Recommended approach: Fire the signal on the post-authentication screen or after the session is confirmed. For SSO and OAuth flows, trigger the signal after the callback completes — not during the external provider interaction.

Data sources for identifier value

Several sources of identification are available in React Native apps:

• Values returned directly from your authentication service
• AsyncStorage (persistent, cleared only on uninstall)
• In-memory session state (for example, React context or a state management store)

Wire format

Pass every signal field as a top-level key in additionalParameters. The object is flat; do not nest values.

Contact mapping

The 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 that wraps ConnectSDK.shared.identity.log on iOS and Connect.logIdentificationEvent on Android. Signature, parameters, and return behavior are identical on both platforms, and both read ConnectConfig.json as the same, shared source of truth for the underlying config.

Configuration

The identity signal interface is available as soon as the Connect SDK is initialized.

Method

import AcousticConnectRN from 'react-native-acoustic-connect'

AcousticConnectRN.logIdentity(
  identifierName: string,
  identifierValue: string,
  signalType?: string,
  additionalParameters?: Record<string, string>
): Promise<boolean>

Sends the logged in signal, associating a named identifier with a value. Returns a Promise — await it so that any upstream error handling can react to a false result.

Parameters

Returns Promise<boolean>. Resolves to true if the signal was dispatched, false if either identifier field is blank after trimming. Never rejects.

Supported fields in additionalParameters

Required

• loginMethod — any string identifying the authentication method, for example 'email', 'passwordless', or 'sso'.

Optional

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

Basic example

The example below uses email as the identifier because it is universally available. In a production app, prefer a customer ID returned by your authentication service — see Choosing an identifier above.

import AcousticConnectRN from 'react-native-acoustic-connect'

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

This records the Logged In signal in Connect.

Complete implementation example

Call logIdentity() from your authentication handler once the session is confirmed:

import AcousticConnectRN from 'react-native-acoustic-connect'

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

    await AcousticConnectRN.logIdentity(
      'Email Address',
      user.email,
      'loggedIn',
      {
        loginMethod: 'email',
        name: 'App sign-in',
        description: 'User authenticated in the React Native app.',
      }
    )

    navigateToDashboard()
  } catch (error) {
    showError(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 when the user actively signs in. This ensures Connect attributes every session to the known contact.

import AcousticConnectRN from 'react-native-acoustic-connect'

async function restoreSession() {
  const storedEmail = await AsyncStorage.getItem('userEmail')
  if (!storedEmail) return

  await AcousticConnectRN.logIdentity(
    'Email Address',
    storedEmail,
    'loggedIn',
    { loginMethod: 'session-restore' }
  )
}

Troubleshooting

Signal not appearing in Connect?

• Verify identifierName and identifierValue are not empty or whitespace-only. The SDK trims both and returns false without throwing if either is blank.
• Confirm additionalParameters includes loginMethod.
• Confirm the signal fires after authentication is confirmed, not on form submit.
• Enable SDK debug logging: set useRelease to false in ConnectConfig.json, rebuild, and inspect Logcat (Android) or the Xcode console (iOS) for signal dispatch and HTTP 200 responses.

Contact not created or updated?

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