Quick Start Guide

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)

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.12.1")
}

dependencies {
    implementation "com.permutive.android:core:1.12.1"
}

Sync your project with Gradle files.

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
    }
}

import android.app.Application;
import com.permutive.android.Permutive;
import java.util.UUID;

public class MyApplication extends Application {

    private Permutive permutive;

    // Create a single instance of Permutive using double-checked locking
    public Permutive getPermutive() {
        if (permutive == null) {
            synchronized (this) {
                if (permutive == null) {
                    permutive = new Permutive.Builder()
                        .context(this)
                        .workspaceId(UUID.fromString("YOUR_WORKSPACE_ID"))
                        .apiKey(UUID.fromString("YOUR_API_KEY"))
                        .build();
                }
            }
        }
        return permutive;
    }
}

Create only one instance of the Permutive object. Creating multiple instances will result in undefined behavior.

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()
    }
}

import androidx.appcompat.app.AppCompatActivity;
import android.net.Uri;
import android.os.Bundle;
import com.permutive.android.EventProperties;
import com.permutive.android.PageTracker;
import com.permutive.android.Permutive;

public class MainActivity extends AppCompatActivity {

    private Permutive permutive;
    private PageTracker pageTracker;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        permutive = ((MyApplication) getApplication()).getPermutive();

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

    private void trackMainScreen() {
        EventProperties properties = new EventProperties.Builder()
            .with("screen_name", "MainActivity")
            .with("session_start", true)
            .build();

        pageTracker = permutive.trackPage(
            properties,
            "Home Screen",
            Uri.parse("app://main"),
            null  // referrer
        );
    }

    @Override
    protected void onPause() {
        super.onPause();
        // Pause tracking when screen is not visible
        pageTracker.pause();
    }

    @Override
    protected void onResume() {
        super.onResume();
        // Resume tracking when screen is visible
        pageTracker.resume();
    }

    @Override
    protected void 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.

Verify Your Integration

Enable debug logging to verify events are being tracked:

Via Code
Via ADB

override fun onCreate() {
    super.onCreate()
    permutive.setDeveloperMode(true)
}

adb shell setprop log.tag.Permutive VERBOSE
adb logcat -s Permutive

What to look for in logs:

D/Permutive: Starting Permutive v1.12.1
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

Error fetching configuration - please check that your workspace id & API key is correct

Cause: Invalid credentials or Android not enabled for your workspace.Solution:

Verify your Workspace ID and API Key are correct
Ensure you’re using workspaceId (not the deprecated projectId)
Contact your Customer Success Manager to verify Android is enabled

Events showing as 'Rejected'

Cause: Event schema doesn’t match what’s configured in your Permutive dashboard.Solution:

Ensure the event name matches exactly (case-sensitive)
Verify property names and types match your schema
Check logs for detailed validation errors

No logs appearing

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

Get Started

Products

Deployment

Governance

Next Steps

Page Tracking Guide

Identity Management

Google Ad Manager

Xandr/AppNexus

Video Tracking

Verification Guide

Troubleshooting

More Troubleshooting

​Next Steps

Page Tracking Guide

Identity Management

Google Ad Manager

Xandr/AppNexus

Video Tracking

Verification Guide

​Troubleshooting

More Troubleshooting

Next Steps

Troubleshooting