Identity Management

Identity management allows you to track users across different sessions, devices, and platforms by associating multiple identifiers (aliases) with a single user profile.

Single Identity

Multiple Identities

AAID Provider

Overview

In the Android SDK, you can set aliases using the setIdentity() method or configure automatic identity providers like AAID at initialization.

Key Concepts

Alias

Identity Resolution

Priority System

Setting Identity

Single Identity
Multiple Identities
At Initialization

For apps with only one type of user identifier:

// Set identity when user logs in
fun onUserLoggedIn(userId: String) {
    permutive.setIdentity(userId)
}

// Set identity when user logs in
public void onUserLoggedIn(String userId) {
    permutive.setIdentity(userId);
}

When using the single-parameter setIdentity(), the alias tag is automatically set to "default".

With Priority and Expiry

fun onUserLoggedIn(userId: String) {
    val expiryDate = Calendar.getInstance().apply {
        add(Calendar.YEAR, 1)  // Expire in 1 year
    }.time

    permutive.setIdentity(
        identity = userId,
        priority = 0,  // Highest priority
        expiry = expiryDate
    )
}

public void onUserLoggedIn(String userId) {
    Calendar calendar = Calendar.getInstance();
    calendar.add(Calendar.YEAR, 1);
    Date expiryDate = calendar.getTime();

    permutive.setIdentity(userId, 0, expiryDate);
}

For apps tracking multiple types of identifiers (email, internal ID, ad ID, etc.):

import com.permutive.android.Alias

fun setupUserIdentities(userId: String, emailHash: String, adId: String?) {
    val aliases = buildList {
        // Highest priority: hashed email (never expires)
        add(Alias.create(
            tag = "email_sha256",
            identity = emailHash,
            priority = 0
        ))

        // Medium priority: internal user ID (expires in 1 year)
        val oneYearLater = Calendar.getInstance().apply {
            add(Calendar.YEAR, 1)
        }.time
        add(Alias.create(
            tag = "internal_id",
            identity = userId,
            priority = 1,
            expiry = oneYearLater
        ))

        // Lower priority: advertising ID (expires in 30 days)
        adId?.let { id ->
            val thirtyDaysLater = Calendar.getInstance().apply {
                add(Calendar.DAY_OF_YEAR, 30)
            }.time
            add(Alias.create(
                tag = "ad_id",
                identity = id,
                priority = 2,
                expiry = thirtyDaysLater
            ))
        }
    }

    permutive.setIdentity(aliases)
}

import com.permutive.android.Alias;

public void setupUserIdentities(String userId, String emailHash, String adId) {
    List<Alias> aliases = new ArrayList<>();

    // Highest priority: hashed email
    aliases.add(Alias.create("email_sha256", emailHash, 0));

    // Medium priority: internal user ID
    Calendar oneYearLater = Calendar.getInstance();
    oneYearLater.add(Calendar.YEAR, 1);
    aliases.add(Alias.create("internal_id", userId, 1, oneYearLater.getTime()));

    // Lower priority: advertising ID
    if (adId != null) {
        Calendar thirtyDaysLater = Calendar.getInstance();
        thirtyDaysLater.add(Calendar.DAY_OF_YEAR, 30);
        aliases.add(Alias.create("ad_id", adId, 2, thirtyDaysLater.getTime()));
    }

    permutive.setIdentity(aliases);
}

You can provide aliases when creating the Permutive instance:

val customAliases = listOf(
    Alias.create(
        tag = "email_sha256",
        identity = "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e",
        priority = 0
    ),
    Alias.create(
        tag = "internal_id",
        identity = "user_12345",
        priority = 1
    )
)

val permutive = Permutive(
    context = this,
    workspaceId = YOUR_WORKSPACE_ID,
    apiKey = YOUR_API_KEY,
    customAliases = customAliases
)

Permutive permutive = new Permutive.Builder()
    .context(this)
    .workspaceId(YOUR_WORKSPACE_ID)
    .apiKey(YOUR_API_KEY)
    .customAlias(Alias.create("email_sha256", "f660ab912ec121d...", 0))
    .customAlias(Alias.create("internal_id", "user_12345", 1))
    .build();

Security Best Practices

Always hash personally identifiable information like email addresses before sending to Permutive.

Correct - Hashed
Incorrect - Plain Text

import java.security.MessageDigest

fun hashEmail(email: String): String {
    val normalized = email.trim().lowercase()
    val bytes = MessageDigest.getInstance("SHA-256").digest(normalized.toByteArray())
    return bytes.joinToString("") { "%02x".format(it) }
}

// Usage
val emailHash = hashEmail("user@example.com")
permutive.setIdentity(
    listOf(Alias.create("email_sha256", emailHash, priority = 0))
)

// DON'T DO THIS - sending PII
permutive.setIdentity(
    listOf(Alias.create("email", "user@example.com", priority = 0))  // WRONG!
)

Standard Tag Names

Identifier Type	Recommended Tag	Notes
SHA-256 hashed email	`email_sha256`	Most common
Internal user ID	`internal_id` or `user_id`	Your system’s ID
Advertising ID	`aaid` (Android)	Use AaidAliasProvider
Customer ID	`customer_id`	E-commerce systems
Subscriber ID	`subscriber_id`	Subscription services

Automatic Identity Providers

AAID (Android Advertising ID)

From v1.12.0, the AAID and IP address can be collected automatically when enabled in your workspace config - no provider code required. See the v1.12 Migration Guide. If you opt into automatic collection, you generally don’t need the manual AaidAliasProvider setup below.

Use the Google Ads add-on for automatic AAID identification:

Add Dependency

dependencies {
    implementation("com.permutive.android:core:1.12.1")
    implementation("com.permutive.android:google-ads:2.2.0")
}

Add Permission

In your AndroidManifest.xml:

<manifest>
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
</manifest>

From Android 13 (API 33+), the AD_ID permission is required to access the advertising ID.

Configure SDK

import com.permutive.android.aaid.AaidAliasProvider

val permutive = Permutive(
    context = this,
    workspaceId = YOUR_WORKSPACE_ID,
    apiKey = YOUR_API_KEY,
    aliasProviders = listOf(AaidAliasProvider(this))
)

import com.permutive.android.aaid.AaidAliasProvider;

Permutive permutive = new Permutive.Builder()
    .context(this)
    .workspaceId(YOUR_WORKSPACE_ID)
    .apiKey(YOUR_API_KEY)
    .aliasProvider(new AaidAliasProvider(this))
    .build();

The AAID will be automatically retrieved and set with the tag "aaid".

Common Patterns

class AuthActivity : AppCompatActivity() {

    private val permutive by lazy {
        (application as MyApplication).permutive
    }

    fun onLoginSuccess(userId: String, email: String) {
        val emailHash = hashEmail(email)

        val aliases = listOf(
            Alias.create("email_sha256", emailHash, priority = 0),
            Alias.create("internal_id", userId, priority = 1)
        )

        permutive.setIdentity(aliases)
        navigateToHome()
    }

    private fun hashEmail(email: String): String {
        val normalized = email.trim().lowercase()
        val bytes = MessageDigest.getInstance("SHA-256")
            .digest(normalized.toByteArray())
        return bytes.joinToString("") { "%02x".format(it) }
    }
}

Logout Flow

fun onLogout() {
    // Clear all persistent data
    lifecycleScope.launch(Dispatchers.IO) {
        permutive.clearPersistentData()
            .onSuccess {
                withContext(Dispatchers.Main) {
                    navigateToLogin()
                }
            }
            .onFailure { error ->
                Log.e("Permutive", "Failed to clear data", error)
            }
    }
}

Guest to Logged-In Transition

class UserManager(private val permutive: Permutive) {

    // User starts as guest (anonymous)
    fun onAppLaunch() {
        // SDK automatically creates anonymous ID
    }

    // User logs in or signs up
    fun onUserAuthenticated(userId: String, email: String) {
        val emailHash = hashEmail(email)

        // Permutive merges guest data with authenticated profile
        permutive.setIdentity(
            listOf(
                Alias.create("email_sha256", emailHash, priority = 0),
                Alias.create("internal_id", userId, priority = 1)
            )
        )
    }
}

Expiry

Aliases can expire automatically, useful for GDPR compliance, ad IDs, and session identifiers.

// Never expire (default)
Alias.create(tag = "email_sha256", identity = emailHash, expiry = Alias.NEVER_EXPIRE)

// Expire in 30 days
val expiry30Days = Calendar.getInstance().apply {
    add(Calendar.DAY_OF_YEAR, 30)
}.time
Alias.create(tag = "session_id", identity = sessionId, expiry = expiry30Days)

Troubleshooting

Identity not resolving

Problem: Setting identity doesn’t seem to merge user data.Solutions:

Check network connectivity
Verify alias has been used in other sessions/devices
Enable debug logging: permutive.setDeveloperMode(true)
Look for “Identified user with aliases” in logs

User identity split

Problem: Same user appears as two different users.Solution: Use consistent alias tags and values. When user logs in on multiple devices, use the same alias (e.g., hashed email).

PII concerns

Problem: Worried about sending personally identifiable information.Solution:

Always hash emails and other PII with SHA-256
Normalize data before hashing (lowercase, trim whitespace)
Never send raw email addresses, phone numbers, or names

Best Practices

Do
Don't

Hash PII (especially email addresses) before setting as identity
Use meaningful tag names that describe the identifier type
Set priorities based on reliability and persistence
Use expiry dates for temporary or less reliable identifiers
Set identity as early as possible in the user journey
Test identity resolution with debug logging enabled

AAID Provider

Automatic advertising ID tracking

Cohorts & Activations

Understanding user segments

Triggers Provider

React to cohort changes

Issues

Solutions to common issues

Get Started

Products

Deployment

Governance

Identity Management

Single Identity

Multiple Identities

AAID Provider

Overview

Key Concepts

Setting Identity

With Priority and Expiry

Security Best Practices

Standard Tag Names

Automatic Identity Providers

AAID (Android Advertising ID)

Common Patterns

Expiry

Troubleshooting

Best Practices

AAID Provider

Cohorts & Activations

Triggers Provider

Issues

Single Identity

Multiple Identities

AAID Provider

​Overview

​Key Concepts

​Setting Identity

​With Priority and Expiry

​Security Best Practices

​Standard Tag Names

​Automatic Identity Providers

​AAID (Android Advertising ID)

​Common Patterns

​Expiry

​Troubleshooting

​Best Practices

​Related Documentation

AAID Provider

Cohorts & Activations

Triggers Provider

Issues

Overview

Key Concepts

Setting Identity

With Priority and Expiry

Security Best Practices

Standard Tag Names

Automatic Identity Providers

AAID (Android Advertising ID)

Common Patterns

Expiry

Troubleshooting

Best Practices

Related Documentation