Skip to main content
The Permutive SDK must be initialized before you can track events or use any SDK features. This guide shows you how to properly initialize the SDK.
Prerequisites:
  • SDK dependencies added to your project (Installation Guide)
  • Workspace ID and API Key from your Permutive dashboard
  • Your project enabled for Android by Permutive
The Permutive object should be created only once as a singleton. Initialize in your Application class:
import android.app.Application
import com.permutive.android.Permutive
import java.util.UUID

class MyApplication : Application() {

    // Create a single instance using lazy initialization
    val permutive by lazy {
        Permutive(
            context = this,
            workspaceId = UUID.fromString("YOUR_WORKSPACE_ID"),
            apiKey = UUID.fromString("YOUR_API_KEY")
        )
    }

    override fun onCreate() {
        super.onCreate()
        // SDK will initialize when first accessed
    }
}

​
Important Considerations

Creating multiple Permutive instances will result in undefined behavior. Always use a singleton pattern.
Good:
class MyApplication : Application() {
    val permutive by lazy { Permutive(...) }  // Single instance
}
Bad:
class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        val permutive = Permutive(...)  // NEW instance every time - DON'T!
    }
}
  • Initialization is fast - No significant impact on app startup
  • No main thread blocking - Network calls happen asynchronously
  • Start tracking immediately - No need to wait for initialization to complete
We strongly recommend that you do not instantiate the Permutive object when receiving a push notification, but rather when the user interacts with the push notification.
This prevents unnecessary SDK initialization from background processes.

​
Troubleshooting

Symptoms:
D/Permutive: Error fetching configuration - please check that your workspace id & API key is correct
Solutions:
  1. Verify credentials are correct UUIDs
  2. Ensure using workspaceId (not deprecated projectId)
  3. Contact your Customer Success Manager to verify Android is enabled
  4. Check device network connectivity
Causes:
  1. Invalid UUID format
  2. Context is null
  3. ProGuard/R8 stripping required classes
Solutions:
  1. Verify UUID format: "550e8400-e29b-41d4-a716-446655440000"
  2. Use Application context (not Activity)
  3. Check ProGuard rules are applied

​
Next Steps

Track Your First Page View

Start tracking user interactions

Verify Your Integration

Confirm everything is working

Identity Management

Track users across sessions

Issues

Solutions to common issues

​
API Reference

For complete API documentation, see the Javadocs. Key Classes:
  • Permutive - Main SDK class
  • Permutive.Builder - Builder for Java
  • Alias - User identity alias
  • AliasProvider - Automatic alias provider interface