SDKs
Help centerCommunityDevelopersAcademyStatus

Identify users at sign-in (iOS)

The logged in signal is how your iOS 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 to create one. Once the contact is known, marketers can target re-engagement and loyalty journeys, and the rest of the user's session is attributed to that contact. For details on how Connect processes identification records, see How behavior signals are processed in Connect.

Language: Swift. The ConnectIdentity API is not available in Objective-C.

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.

Everything else on the call (signalType, 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 — this is what Connect uses internally to identify a contact. 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

identity.log() 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 the helper 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.

ConnectSDKManager.shared.logUserLoggedIn(
    identifierName: "Customer ID",
    identifierValue: user.customerId,
    additionalParameters: ["loginMethod": "email"]
)

ConnectSDKManager.shared.logUserLoggedIn(
    identifierName: "Email Address",
    identifierValue: user.email,
    additionalParameters: ["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.

Before you begin

The identity signal interface is available as soon as the Connect SDK is initialized. No push configuration is required.

Implementation considerations

Authentication timing

The logged in signal must fire after authentication is confirmed — not when the user submits the login 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 iOS apps:

  • Values returned directly from your authentication service
  • Keychain (persistent, survives app reinstall)
  • UserDefaults (persistent, cleared on reinstall)
  • In-memory session state

Wire format

Pass every signal field as a top-level key in additionalParameters — both the required field and any optional fields. The dictionary 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.

Configuration

Method

ConnectSDK.shared.identity.log(
    identifierName:
    identifierValue:
    signalType:
    additionalParameters:
)

Sends the logged in signal, associating a named identifier with a value.

Parameters

The first two parameters identify the user. The remaining two describe the event.

  • identifierName (String, required) — The contact attribute name this identifier maps to. Must match exactly as it appears in Connect — case sensitive.
  • identifierValue (String, required) — The value of the identifier.
  • signalType (String, required) — Pass "loggedIn".
  • additionalParameters ([String: String], required) — The signal fields, all as top-level keys. See Supported fields below.

Supported fields in additionalParameters

Required

  • loginMethod — any string identifying the authentication method (for example, email, password, passwordless, sso).

Optional

  • name — short label for this signal instance.
  • description — longer human-readable note describing the event.
  • screenViewName — name of the screen where the sign-in occurred.

Basic example

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

ConnectSDKManager.shared.logUserLoggedIn(
    identifierName: "Email Address",
    identifierValue: user.email,
    additionalParameters: ["loginMethod": "email"]
)

This records the Logged In signal in Connect.

Complete implementation example

Add a logUserLoggedIn(...) method to your ConnectSDKManager (introduced in Integrate the Connect SDK into a native iOS app (Swift)). Keeping identity calls on the manager gives you one place to evolve them as your app grows.

extension ConnectSDKManager {

    @discardableResult
    func logUserLoggedIn(
        identifierName: String,
        identifierValue: String,
        additionalParameters: [String: String]
    ) -> Bool {
        let trimmedName = identifierName.trimmingCharacters(in: .whitespaces)
        let trimmedValue = identifierValue.trimmingCharacters(in: .whitespaces)

        return ConnectSDK.shared.identity.log(
            identifierName: trimmedName,
            identifierValue: trimmedValue,
            signalType: "loggedIn",
            additionalParameters: additionalParameters
        )
    }
}

The hardcoded signalType: "loggedIn" is what records this as the Logged In signal in Connect. The helper returns the SDK's Bool result so callers can react to a failed send; @discardableResult lets callers ignore it when they don't need to.

Call it from your authentication handler once the session is confirmed:

authService.signIn(email: email, password: password) { result in
    switch result {
    case .success(let user):
        ConnectSDKManager.shared.logUserLoggedIn(
            identifierName: "Email Address",
            identifierValue: user.email,
            additionalParameters: [
                "loginMethod": "email",
                "name": "App sign-in",
                "description": "User authenticated in the iOS app.",
                "screenViewName": "AuthViewController"
            ]
        )
        self.navigateToDashboard()
    case .failure(let error):
        self.showError(error)
    }
}

For the full helper — including push setup and identity — see ConnectSDKManager.swift in the sample app on GitHub.

Troubleshooting

Signal not appearing in Connect?

  • Verify identifierName and identifierValue are not empty or whitespace-only. The SDK trims both inputs and silently skips signals where either is empty — logUserLoggedIn(...) returns false in that case.
  • Confirm additionalParameters includes loginMethod.
  • Confirm the signal fires after authentication is confirmed, not on form submit.
  • Use the SDK debug log to verify the signal is being sent. This requires the debug build of the SDK (for example, the AcousticConnectDebug CocoaPod or the ConnectDebug-SP Swift Package); release builds do not emit these logs. To enable debug logging, add CONNECT_DEBUG, TLF_DEBUG, and EODebug environment variables with a value of 1 to your scheme. Look for a Flushing <Connect.ConnectIdentityMessage: ...> line followed by a Status Code: 200 from the collector.

Contact not created or updated?

  • Verify the identifierName value matches a contact attribute defined in Connect.
  • The SDK accepts only string values for identifierValue and for every entry in additionalParameters. 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.

Updated 15 days ago