Skip to main content
Get up and running with the Permutive Android SDK. This guide will help you install the SDK, initialize it, and track your first page view.
Prerequisites:
  • Minimum Android API level 21 (Android 5.0)
  • Your Permutive Workspace ID and API Key (available from your Permutive dashboard)
  • Your project enabled for Android by Permutive (contact your Customer Success Manager if unsure)
1

Add the Dependency

Add the Permutive SDK to your app’s build.gradle.kts or build.gradle file:
dependencies {
    implementation("com.permutive.android:core:1.10.0")
}
Sync your project with Gradle files.
2

Initialize the SDK

Initialize Permutive in your Application class. The Permutive object should be created once as a singleton.
import android.app.Application
import com.permutive.android.Permutive
import java.util.UUID

class MyApplication : Application() {

    // Create a single instance of Permutive 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()
        // The SDK will initialize when first accessed
    }
}
Create only one instance of the Permutive object. Creating multiple instances will result in undefined behavior.
3

Track Your First Page View

Track a page view from an Activity using PageTracker. PageTracker is the recommended approach as it integrates with Permutive’s standard events and enables richer insights.
import androidx.appcompat.app.AppCompatActivity
import android.net.Uri
import android.os.Bundle
import com.permutive.android.EventProperties
import com.permutive.android.PageTracker

class MainActivity : AppCompatActivity() {

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

    private lateinit var pageTracker: PageTracker

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Track a page view with PageTracker
        trackMainScreen()
    }

    private fun trackMainScreen() {
        pageTracker = permutive.trackPage(
            title = "Home Screen",
            url = Uri.parse("app://main"),
            eventProperties = EventProperties.from(
                "screen_name" to "MainActivity",
                "session_start" to true
            )
        )
    }

    override fun onPause() {
        super.onPause()
        // Pause tracking when screen is not visible
        pageTracker.pause()
    }

    override fun onResume() {
        super.onResume()
        // Resume tracking when screen is visible
        pageTracker.resume()
    }

    override fun onDestroy() {
        super.onDestroy()
        // Always close the tracker when done
        pageTracker.close()
    }
}
Why PageTracker? PageTracker automatically tracks Pageview events with proper structure, measures engagement time and scroll depth, integrates seamlessly with Permutive’s insights platform, enables contextual cohorts when URLs are provided, and associates related events with the page context.
4

Verify Your Integration

Enable debug logging to verify events are being tracked:
override fun onCreate() {
    super.onCreate()
    permutive.setDeveloperMode(true)
}
What to look for in logs:
D/Permutive: Starting Permutive v1.10.0
D/Permutive: Fetched configuration information
D/Permutive: Page started (id: <viewId>):
    title: Home Screen
    url: app://main
D/Permutive: Published events with names (Pageview) (Accepted: 1 / 1)
If you see “Accepted: 1 / 1” and the Pageview event, your integration is working!

​
Next Steps

Page Tracking Guide

Learn how to track user engagement with content

Identity Management

Connect user behavior across sessions and devices

Google Ad Manager

Integrate with GAM for personalized advertising

Xandr/AppNexus

Integrate with Xandr ad platform

Video Tracking

For video streaming or CTV applications

Verification Guide

Comprehensive verification and troubleshooting

​
Troubleshooting

Cause: Invalid credentials or Android not enabled for your workspace.Solution:
  1. Verify your Workspace ID and API Key are correct
  2. Ensure you’re using workspaceId (not the deprecated projectId)
  3. Contact your Customer Success Manager to verify Android is enabled
Cause: Event schema doesn’t match what’s configured in your Permutive dashboard.Solution:
  1. Ensure the event name matches exactly (case-sensitive)
  2. Verify property names and types match your schema
  3. Check logs for detailed validation errors
Cause: Debug logging not enabled.Solution: Enable developer mode or use ADB commands shown in Step 4.

More Troubleshooting

See the complete troubleshooting guide for solutions to more issues