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

# SDK Initialization

> Initialize the Permutive SDK in your Android application

The Permutive SDK must be initialized before you can track events or use any SDK features. This guide shows you how to properly initialize the SDK.

<Info>
  **Prerequisites:**

  * SDK dependencies added to your project ([Installation Guide](/sdks/mobile/android/getting-started/installation))
  * **Workspace ID** and **API Key** from your Permutive dashboard
  * Your project enabled for Android by Permutive
</Info>

<Tabs>
  <Tab title="Basic Initialization">
    The Permutive object should be created **only once** as a singleton. Initialize in your Application class:

    <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 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()
              // 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 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>
  </Tab>

  <Tab title="With Identity">
    Set user identity during initialization:

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      import com.permutive.android.Alias

      // Single identity with default tag
      val permutive = Permutive(
          context = this,
          workspaceId = YOUR_WORKSPACE_ID,
          apiKey = YOUR_API_KEY,
          identity = "user_12345"
      )

      // Or with multiple aliases:
      val customAliases = listOf(
          Alias.create(
              tag = "email_sha256",
              identity = "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e",
              priority = 0
          ),
          Alias.create(
              tag = "internal_id",
              identity = "user_12345",
              priority = 1
          )
      )

      val permutive = Permutive(
          context = this,
          workspaceId = YOUR_WORKSPACE_ID,
          apiKey = YOUR_API_KEY,
          customAliases = customAliases
      )
      ```

      ```java Java theme={"dark"}
      import com.permutive.android.Alias;

      // Single identity
      Permutive permutive = new Permutive.Builder()
          .context(this)
          .workspaceId(YOUR_WORKSPACE_ID)
          .apiKey(YOUR_API_KEY)
          .identity("user_12345")
          .build();

      // Multiple aliases
      Permutive permutive = new Permutive.Builder()
          .context(this)
          .workspaceId(YOUR_WORKSPACE_ID)
          .apiKey(YOUR_API_KEY)
          .customAlias(Alias.create("email_sha256", "f660ab912ec121d...", 0))
          .customAlias(Alias.create("internal_id", "user_12345", 1))
          .build();
      ```
    </CodeGroup>

    See [Identity Management](/sdks/mobile/android/core-concepts/identity-management) for details.
  </Tab>

  <Tab title="With AAID Provider">
    Use alias providers for automatic identity management:

    <CodeGroup>
      ```kotlin Kotlin theme={"dark"}
      import com.permutive.android.aaid.AaidAliasProvider

      val permutive = Permutive(
          context = this,
          workspaceId = YOUR_WORKSPACE_ID,
          apiKey = YOUR_API_KEY,
          aliasProviders = listOf(AaidAliasProvider(this))
      )
      ```

      ```java Java theme={"dark"}
      import com.permutive.android.aaid.AaidAliasProvider;

      Permutive permutive = new Permutive.Builder()
          .context(this)
          .workspaceId(YOUR_WORKSPACE_ID)
          .apiKey(YOUR_API_KEY)
          .aliasProvider(new AaidAliasProvider(this))
          .build();
      ```
    </CodeGroup>

    <Note>
      AAID requires the `google-ads` add-on and `AD_ID` permission. See [AAID Integration](/sdks/mobile/android/integrations/aaid-provider).
    </Note>
  </Tab>
</Tabs>

## Important Considerations

<AccordionGroup>
  <Accordion title="Singleton Pattern" icon="warning">
    <Warning>
      Creating multiple Permutive instances will result in undefined behavior. Always use a singleton pattern.
    </Warning>

    **Good:**

    ```kotlin theme={"dark"}
    class MyApplication : Application() {
        val permutive by lazy { Permutive(...) }  // Single instance
    }
    ```

    **Bad:**

    ```kotlin theme={"dark"}
    class MyActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            val permutive = Permutive(...)  // NEW instance every time - DON'T!
        }
    }
    ```
  </Accordion>

  <Accordion title="Performance" icon="gauge-high">
    * **Initialization is fast** - No significant impact on app startup
    * **No main thread blocking** - Network calls happen asynchronously
    * **Start tracking immediately** - No need to wait for initialization to complete
  </Accordion>

  <Accordion title="Push Notifications" icon="bell">
    <Tip>
      We **strongly** recommend that you do **not** instantiate the Permutive object when receiving a push notification, but rather when the user interacts with the push notification.
    </Tip>

    This prevents unnecessary SDK initialization from background processes.
  </Accordion>

  <Accordion title="Consent Management" icon="shield-check">
    As a data controller, you may need to receive consent from the user before tracking data against them. The Permutive SDK assumes that at the time it is initialized, this consent has already been granted.

    <Info>
      **Coming Soon:** GDPR Compliance documentation is being developed. Contact your Customer Success Manager for immediate assistance.
    </Info>
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error fetching configuration">
    **Symptoms:**

    ```
    D/Permutive: Error fetching configuration - please check that your workspace id & API key is correct
    ```

    **Solutions:**

    1. Verify credentials are correct UUIDs
    2. Ensure using `workspaceId` (not deprecated `projectId`)
    3. Contact your Customer Success Manager to verify Android is enabled
    4. Check device network connectivity
  </Accordion>

  <Accordion title="App crashes on initialization">
    **Causes:**

    1. Invalid UUID format
    2. Context is null
    3. ProGuard/R8 stripping required classes

    **Solutions:**

    1. Verify UUID format: `"550e8400-e29b-41d4-a716-446655440000"`
    2. Use Application context (not Activity)
    3. Check ProGuard rules are applied
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Track Your First Page View" icon="file" href="/sdks/mobile/android/getting-started/quick-start#step-3-track-your-first-page-view">
    Start tracking user interactions
  </Card>

  <Card title="Verify Your Integration" icon="circle-check" href="/sdks/mobile/android/getting-started/verification">
    Confirm everything is working
  </Card>

  <Card title="Identity Management" icon="user" href="/sdks/mobile/android/core-concepts/identity-management">
    Track users across sessions
  </Card>

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

## API Reference

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

**Key Classes:**

* `Permutive` - Main SDK class
* `Permutive.Builder` - Builder for Java
* `Alias` - User identity alias
* `AliasProvider` - Automatic alias provider interface