> ## 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.

# Quick Start Guide

> Get up and running with the Permutive Android SDK in minutes

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.

<Info>
  **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)
</Info>

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

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

      ```groovy build.gradle theme={"dark"}
      dependencies {
          implementation "com.permutive.android:core:1.11.3"
      }
      ```
    </CodeGroup>

    Sync your project with Gradle files.
  </Step>

  <Step title="Initialize the SDK">
    Initialize Permutive in your `Application` class. The Permutive object should be created **once** as a singleton.

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      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
          }
      }
      ```

      ```java Java theme={"dark"}
      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;
          }
      }
      ```
    </CodeGroup>

    <Warning>
      Create only **one** instance of the Permutive object. Creating multiple instances will result in undefined behavior.
    </Warning>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      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()
          }
      }
      ```

      ```java Java theme={"dark"}
      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();
          }
      }
      ```
    </CodeGroup>

    <Tip>
      **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.
    </Tip>
  </Step>

  <Step title="Verify Your Integration">
    Enable debug logging to verify events are being tracked:

    <Tabs>
      <Tab title="Via Code">
        ```kotlin theme={"dark"}
        override fun onCreate() {
            super.onCreate()
            permutive.setDeveloperMode(true)
        }
        ```
      </Tab>

      <Tab title="Via ADB">
        ```bash theme={"dark"}
        adb shell setprop log.tag.Permutive VERBOSE
        adb logcat -s Permutive
        ```
      </Tab>
    </Tabs>

    **What to look for in logs:**

    ```
    D/Permutive: Starting Permutive v1.11.3
    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)
    ```

    <Check>
      If you see "Accepted: 1 / 1" and the Pageview event, your integration is working!
    </Check>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Page Tracking Guide" icon="file" href="/sdks/mobile/android/features/page-tracking">
    Learn how to track user engagement with content
  </Card>

  <Card title="Identity Management" icon="user" href="/sdks/mobile/android/core-concepts/identity-management">
    Connect user behavior across sessions and devices
  </Card>

  <Card title="Google Ad Manager" icon="google" href="/sdks/mobile/android/integrations/google-ad-manager">
    Integrate with GAM for personalized advertising
  </Card>

  <Card title="Xandr/AppNexus" icon="rectangle-ad" href="/sdks/mobile/android/integrations/appnexus-xandr">
    Integrate with Xandr ad platform
  </Card>

  <Card title="Video Tracking" icon="video" href="/sdks/mobile/android/features/video-tracking">
    For video streaming or CTV applications
  </Card>

  <Card title="Verification Guide" icon="circle-check" href="/sdks/mobile/android/getting-started/verification">
    Comprehensive verification and troubleshooting
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error fetching configuration - please check that your workspace id & API key is correct">
    **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
  </Accordion>

  <Accordion title="Events showing as 'Rejected'">
    **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
  </Accordion>

  <Accordion title="No logs appearing">
    **Cause:** Debug logging not enabled.

    **Solution:** Enable developer mode or use ADB commands shown in Step 4.
  </Accordion>
</AccordionGroup>

<Card title="More Troubleshooting" icon="wrench" href="/sdks/mobile/android/troubleshooting/common-errors">
  See the complete troubleshooting guide for solutions to more issues
</Card>