# ALSDK Android Framework

This guide explains how to integrate the ALSDK SDK into your Android app. You can choose between manual integration (using the prebuilt AAR file) or adding the dependency via Gradle from a Maven repository. For easier updates and maintenance, we recommend using the Gradle dependency method.

## Prerequisites

* **Android Studio:** Version 4.0 or later
* **Minimum API Level:** 21 or later
* **ALSDK.aar:** The prebuilt SDK binary (if doing manual integration)
* (Optional) **Maven Repository:** Your ALSDK is hosted on Maven Central, JitPack, or another repository

## Integration Options

#### Manual Integration

1. **Download the SDK:**
   * Obtain the `ALSDK.aar` file from our release page.
2. **Add to Your Android Studio Project:**
   * Open your project in Android Studio.
   * Create a `libs` directory under your app module (if it doesn’t exist) and copy the `ALSDK.aar` file into that folder.
3. **Include the AAR in Your Gradle File:**
   * Open your module-level `build.gradle` file and add the following:

     ```gradle
     repositories {
         flatDir {
             dirs 'libs'
         }
     }

     dependencies {
         implementation(name: 'ALSDK', ext: 'aar')
     }
     ```
4. **Sync and Build:**
   * Sync your Gradle files and build your project to ensure the SDK is correctly integrated.

***

#### Gradle Dependency Integration

1. **Add the Repository:**
   * If your ALSDK is hosted on a remote repository (e.g., Maven Central or JitPack), make sure the repository is declared in your project’s root `build.gradle`:

     ```gradle
     allprojects {
         repositories {
             mavenCentral()
             // For JitPack:
             // maven { url 'https://jitpack.io' }
         }
     }
     ```
2. **Add the Dependency:**
   * In your app module’s `build.gradle`, add:

     ```gradle
     dependencies {
         implementation 'io.absolutelabs:ALSDK:1.0.12'
     }
     ```
   * Replace `com.example:ALSDK:1.0.12` with the actual group, artifact, and version of your SDK.
3. **Sync the Project:**
   * Sync your Gradle files so the dependency is downloaded and integrated automatically.

## SDK Setup

For the SDK to be active and functional in your Android app, follow these steps:

### SDK Initialization

Initialize in Your Application Class:

* Create or update your custom `Application` class to initialize the SDK:

  ```java
  // Java Example
  import android.app.Application;
  import io.absolutelabs.alsdk.ALSDK; // Adjust package name as needed

  public class MyApp extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          // Initialize ALSDK
          ALSDK.getInstance().initialize(this);
      }
  }
  ```
* For Kotlin:

  ```kotlin
  // Kotlin Example
  import android.app.Application
  import io.absolutelabs.alsdk.ALSDK // Adjust package name as needed

  class MyApp : Application() {
      override fun onCreate() {
          super.onCreate()
          // Initialize ALSDK
          ALSDK.getInstance().initialize(this)
      }
  }
  ```
* **Don’t Forget:** Declare your custom `Application` class in your `AndroidManifest.xml`:

  ```xml
  <application
      android:name=".MyApp"
      ... >
      <!-- Other configurations -->
  </application>
  ```

### App Detection (Package Queries)

Starting with Android 11 (API level 30), if your app detects the presence of other apps, you must declare the package names you intend to query:

* **Add Package Queries in `AndroidManifest.xml`:**

  ```xml
  <manifest ...>
      <queries>
          <package android:name="io.metamask.app" />
          <!-- Add other packages as needed -->
      </queries>
      ...
  </manifest>
  ```
* **Note:** Only list the package names required by your SDK for detecting other apps. Keeping the list lean (around 5 packages) is recommended.

## User ID Tracking

To reconcile visitor context and track user profiles, you can pass a user ID to the SDK:

* **Java Example:**

  ```java
  ALSDK.getInstance().setExternalId("userid@mail.com");
  ```
* **Kotlin Example:**

  ```kotlin
  ALSDK.getInstance().externalId = "userid@mail.com"
  ```

### Event Tracking

For accurate conversion reporting and analytics, the SDK provides a method to post custom events:

* **Java Example:**

  ```java
  ALSDK.getInstance().postCustomEvent("Order Successful", "ORDERID-12345");
  ```
* **Kotlin Example:**

  ```kotlin
  ALSDK.getInstance().postCustomEvent("Order Successful", "ORDERID-12345")
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.absolutelabs.io/features/insights/mobile-apps/alsdk-android-framework.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.