Skip to main content

Quick Start

Features

Integrations

Issues

​
Overview

The Permutive Android SDK enables user segmentation, personalization, and ad targeting in your Android application. Track user behavior, manage identities across devices, and deliver targeted advertising through integrations with major ad platforms. Current Version: 1.10.0 (Core) | 2.2.0 (Google Ads) | 1.7.0 (AppNexus)
What’s New in 1.10.0: Contextual Cohorts for real-time content-based targeting, plus Dagger dependency injection support.

​
Getting Started

New to the Permutive Android SDK? Start here.

Quick Start Guide

Get up and running with your first page view in minutes

Installation

Detailed installation and dependency setup

Initialization

SDK initialization patterns and configuration

Verification

Verify your integration is working correctly

​
Core Concepts

Understand the fundamental concepts of the Permutive SDK.

Identity Management

Track users across devices and sessions

Event Properties

Structure and validate event data

Cohorts and Activations

Understanding user segmentation

Contextual Data

Content-based real-time targeting

​
Features

Detailed guides for specific SDK features.

Page Tracking

Track pageviews and user engagement (recommended approach)

Event Tracking

Track custom events

Video Tracking

Track video content viewing

Video Ad Tracking

Track video advertisement engagement

Triggers Provider

React to cohort changes in real-time

​
Integrations

Connect Permutive with ad platforms and other services.

View All Integrations

Google Ad Manager, Xandr, and more

AAID Provider

Automatic advertising ID tracking

​
Common Tasks

PageTracker is the recommended approach for tracking user interactions as it integrates with Permutive’s standard events and provides richer insights.
class ArticleActivity : AppCompatActivity() {

    private lateinit var pageTracker: PageTracker

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        pageTracker = permutive.trackPage(
            title = "Article Title",
            url = Uri.parse("https://example.com/article"),
            eventProperties = EventProperties.from(
                "category" to "sports",
                "author" to "John Doe"
            )
        )
    }

    override fun onPause() {
        super.onPause()
        pageTracker.pause()
    }

    override fun onResume() {
        super.onResume()
        pageTracker.resume()
    }

    override fun onDestroy() {
        super.onDestroy()
        pageTracker.close()
    }
}

val emailHash = hashEmail(userEmail)
permutive.setIdentity(
    listOf(
        Alias.create("email_sha256", emailHash, priority = 0),
        Alias.create("internal_id", userId, priority = 1)
    )
)

val trigger = triggersProvider.triggerAction("premium_user") { isInCohort ->
    if (isInCohort) {
        showPremiumFeatures()
    }
}

// Don't forget to close!
override fun onDestroy() {
    super.onDestroy()
    trigger.close()
}

val adRequest = AdManagerAdRequest.Builder()
    .addPermutiveTargeting(permutive)
    .build()

adView.loadAd(adRequest)

​
Requirements

RequirementVersion
Android API21+ (Android 5.0 Lollipop)
Compile SDK34+
Java8+ (JVM target 1.8)
Kotlin1.6+ (if using Kotlin)
dependencies {
    // Core SDK (required)
    implementation("com.permutive.android:core:1.10.0")

    // Optional add-ons
    implementation("com.permutive.android:google-ads:2.2.0")
    implementation("com.permutive.android:appnexus:1.7.0")
}

​
Key Concepts

- **Cohorts**: All segments a user belongs to - **Activations**: Cohorts configured for specific ad platforms
- **Behavioral**: Based on user history (e.g., "sports enthusiast") - **Contextual**: Based on current content (e.g., viewing sports article right now)
Multiple identifiers (email, user ID, ad ID) linked to single user profile for cross-device tracking.

​
Additional Resources

Best practices, patterns, and how-tos.
Coming Soon: Architecture Patterns, Testing Strategies, GDPR Compliance, and Performance Optimization guides are being developed.

​
FAQ

PageTracker is the recommended approach for most use cases. It automatically tracks Pageview events, measures engagement time and scroll depth, and enables contextual cohorts when URLs are provided.EventTracker is for specialized cases where you need to track custom events that don’t fit the page model.
Enable developer mode in your code:
permutive.setDeveloperMode(true)
Or via ADB:
adb shell setprop log.tag.Permutive VERBOSE
adb logcat -s Permutive
Use hashed emails (SHA-256), internal user IDs, or mobile advertising IDs. Never send plain text PII. See the Identity Management guide for details.
Events typically appear within 5 minutes. If you see “Accepted: 1 / 1” in your debug logs, the event was successfully sent.

​
Getting Help

​
Privacy & Compliance

Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage.