Identify contacts

identify joins your external_id (the identifier you use in your own database) to a Spotzee contact and updates that contact’s traits. Until you call it, the SDK records activity against a persisted anonymous ID it minted on first use.

Identify a known contact

identify is a suspend function. Call it from a coroutine (typically lifecycleScope in a Fragment or Activity, or a long-lived CoroutineScope you manage in your DI container).

import com.spotzee.android.Spotzee
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch

class SignInActivity : AppCompatActivity() {

    fun onSignIn(userId: String, email: String) {
        lifecycleScope.launch {
            MainApplication.analytics.identify(
                id = userId,
                email = email,
                phone = "+61491570006",
                traits = mapOf(
                    "first_name" to "Sam",
                    "last_name" to "Patel",
                    "plan" to "starter",
                    "lifetime_value" to 199.50,
                )
            )
        }
    }
}

id is your external_id. email, phone, and traits are all optional. Pass only what you have.

How traits flow

Anything in the traits map lands in the contact’s custom data. Read Define custom contact attributes to review discovered attribute paths; project admins can set their visibility there. A few traits map to specific behaviour:

email and phone: top-level fields the email and SMS channels read from. Pass them as arguments to identify rather than nesting them in traits so the SDK puts them in the right place.
timezone and locale: use track(event, properties, user) inline updates to set these top-level fields. Values in the traits map remain custom attributes.

The trait map accepts Map<String, Any>. Values serialise to JSON: strings, numbers, booleans, lists, nested maps.

The Identity overload

To set the anonymous ID explicitly, use the Identity overload:

import com.spotzee.android.Identity

lifecycleScope.launch {
    val identity = Identity(
        anonymousId = MainApplication.analytics.anonymousId,
        externalId = "u_42",
        phone = null,
        email = "sam@example.com",
        traits = mapOf(
            "plan" to "starter",
        )
    )
    MainApplication.analytics.identify(identity = identity)
}

Anonymous to known: automatic alias

The first identify after an anonymous session aliases the anonymous ID to your external_id. All prior anonymous activity now belongs to the known contact. Subsequent track and identify calls carry both IDs automatically. For server-flow contexts where you already know the anonymous ID, call alias directly:

lifecycleScope.launch {
    MainApplication.analytics.alias(
        anonymousId = "anon_xyz",
        externalId = "u_42"
    )
}

The SDK guards against repeated aliasing: once externalId is set on the singleton, identify skips the auto-alias path. Calling alias directly always sends the request.

When to call identify

On sign-up. First call after the user creates an account.
On sign-in. So a user switching devices gets joined back to their record.
When traits change. Updating profile data, plan, lifetime value, billing state. Identify is upsert: pass only the traits that changed.

Avoid calling identify on every Activity resume with the same data. The platform deduplicates server-side, but the network call is wasted.

Worked example: link anonymous browse to checkout

class ProductActivity : AppCompatActivity() {

    fun onProductView(sku: String) {
        // Track is fire-and-forget. Fires against the persisted anonymous ID.
        MainApplication.analytics.track(
            event = "Product viewed",
            properties = mapOf("sku" to sku)
        )
    }

    fun onSignInComplete(userId: String, email: String) {
        // Sign-up. Anonymous events are aliased to u_42.
        lifecycleScope.launch {
            MainApplication.analytics.identify(
                id = userId,
                email = email,
                traits = mapOf("plan" to "starter")
            )

            // Subsequent track carries both IDs. The "Product viewed" event from
            // above now belongs to u_42's history.
            MainApplication.analytics.track(
                event = "Checkout started",
                properties = mapOf("cart_total" to 89.95)
            )
        }
    }
}

Reset on sign-out

MainApplication.analytics.reset()

reset clears the cached externalId and the persisted anonymous ID. The next call mints a new anonymous ID. Subsequent activity is anonymous until the next identify.

Get started

Build

Configure

SDKs

Integrate

Reporting

Tools

API conventions

Recipes

Identify contacts

Identify a known contact

How traits flow

The Identity overload

Anonymous to known: automatic alias

When to call identify

Worked example: link anonymous browse to checkout

Reset on sign-out

Next steps

Track events

Define custom contact attributes

​Identify a known contact

​How traits flow

​The Identity overload

​Anonymous to known: automatic alias

​When to call identify

​Worked example: link anonymous browse to checkout

​Reset on sign-out

​Next steps

Track events

Define custom contact attributes

Identify a known contact

How traits flow

The Identity overload

Anonymous to known: automatic alias

When to call identify

Worked example: link anonymous browse to checkout

Reset on sign-out

Next steps