> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Permutive Android SDK and optional add-ons

The Android SDK is comprised of the core SDK, and optional add-on libraries integrating with other 3rd party SDKs.

## Requirements

| Requirement | Version                    |
| ----------- | -------------------------- |
| Android API | 21+ (Android 5.0 Lollipop) |
| Compile SDK | 34+                        |
| Java        | 8+ (JVM target 1.8)        |
| Kotlin      | 1.6+ (if using Kotlin)     |

You'll also need your **Workspace ID** and **API Key** from your Permutive dashboard.

## Latest Versions

| Package    | Version |
| ---------- | ------- |
| Core       | 1.11.3  |
| Google Ads | 2.2.0   |
| AppNexus   | 1.7.0   |

For API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html).

## Installation

<Steps>
  <Step title="Add the Repository">
    Ensure you have Maven Central in your project's `settings.gradle.kts`:

    ```kotlin theme={"dark"}
    dependencyResolutionManagement {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```
  </Step>

  <Step title="Add Dependencies">
    Add the Permutive SDK to your app module's `build.gradle.kts` or `build.gradle`:

    <CodeGroup>
      ```kotlin build.gradle.kts theme={"dark"}
      dependencies {
          // Core SDK (required)
          implementation("com.permutive.android:core:1.11.3")

          // Optional add-ons
          implementation("com.permutive.android:google-ads:2.2.0")  // Google Ad Manager
          implementation("com.permutive.android:appnexus:1.7.0")    // Xandr / AppNexus
      }
      ```

      ```groovy build.gradle theme={"dark"}
      dependencies {
          // Core SDK (required)
          implementation "com.permutive.android:core:1.11.3"

          // Optional add-ons
          implementation "com.permutive.android:google-ads:2.2.0"  // Google Ad Manager
          implementation "com.permutive.android:appnexus:1.7.0"    // Xandr / AppNexus
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Sync Gradle">
    Sync your project with Gradle files to download the dependencies.
  </Step>
</Steps>

## Optional Add-Ons

<Tabs>
  <Tab title="Google Ads">
    The Google Ads add-on provides:

    * Automatic AAID (Android Advertising ID) identification
    * Helper methods for Google Ad Manager targeting
    * Automatic contextual cohort integration (v2.2.0+)

    ```kotlin theme={"dark"}
    implementation("com.permutive.android:google-ads:2.2.0")
    ```

    **Requirements:**

    * Google Play Services Ads dependency (included transitively)
    * `AD_ID` permission for Android API 31+

    <Card title="Google Ad Manager Integration" icon="google" href="/sdks/mobile/android/integrations/google-ad-manager">
      Learn how to integrate with Google Ad Manager
    </Card>
  </Tab>

  <Tab title="Xandr/AppNexus">
    The AppNexus add-on provides:

    * Helper methods for Xandr/AppNexus ad targeting
    * Automatic impression tracking
    * Automatic contextual cohort integration (v1.7.0+)

    ```kotlin theme={"dark"}
    implementation("com.permutive.android:appnexus:1.7.0")
    ```

    **Requirements:**

    * Xandr SDK dependency (must be added separately)

    <Card title="Xandr Integration" icon="rectangle-ad" href="/sdks/mobile/android/integrations/appnexus-xandr">
      Learn how to integrate with Xandr/AppNexus
    </Card>
  </Tab>
</Tabs>

## Version Compatibility

### Android API Levels

| SDK Version     | Minimum Android API | Target Android API |
| --------------- | ------------------- | ------------------ |
| 1.11.x          | 21 (Android 5.0)    | 34 (Android 14)    |
| 1.10.x          | 21 (Android 5.0)    | 34 (Android 14)    |
| 1.8.0 - 1.9.x   | 21 (Android 5.0)    | 34 (Android 14)    |
| 1.7.x and below | 16 (Android 4.1)    | 33 (Android 13)    |

### Add-On Compatibility

| Add-On           | Minimum Core Version | Notes                               |
| ---------------- | -------------------- | ----------------------------------- |
| google-ads 2.2.0 | 1.10.0               | Contextual cohorts support          |
| google-ads 2.1.0 | 1.8.0                | Minimum API 23 required             |
| appnexus 1.7.0   | 1.10.0               | Contextual cohorts support          |
| appnexus 1.6.x   | 1.8.0+               | Compatible with older core versions |

## ProGuard / R8

If you're using code minification, the SDK includes consumer ProGuard rules automatically. No additional configuration is required.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Gradle cannot find the Permutive SDK">
    **Cause:** Maven Central repository not configured.

    **Solution:** Add Maven Central to your `settings.gradle.kts`:

    ```kotlin theme={"dark"}
    dependencyResolutionManagement {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```
  </Accordion>

  <Accordion title="Duplicate class errors">
    **Cause:** Multiple SDK versions in dependencies.

    **Solution:** Force version resolution:

    ```kotlin theme={"dark"}
    configurations.all {
        resolutionStrategy {
            force("com.permutive.android:core:1.11.3")
            force("com.permutive.android:google-ads:2.2.0")
        }
    }
    ```

    Check dependencies with: `./gradlew app:dependencies`
  </Accordion>

  <Accordion title="ProGuard/R8 stripping required classes">
    **Cause:** Minification removing SDK classes.

    **Solution:** The SDK includes consumer ProGuard rules automatically. If issues persist, contact support.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialize the SDK" icon="gear" href="/sdks/mobile/android/getting-started/initialization">
    Set up Permutive in your Application class
  </Card>

  <Card title="Quick Start Guide" icon="rocket" href="/sdks/mobile/android/getting-started/quick-start">
    Track your first page view
  </Card>

  <Card title="Verification" icon="circle-check" href="/sdks/mobile/android/getting-started/verification">
    Verify your integration is working
  </Card>

  <Card title="Issues" icon="wrench" href="/sdks/mobile/android/troubleshooting/common-errors">
    Solutions to common issues
  </Card>
</CardGroup>