# Android

## Overview

The Blitzllama Android SDK enables you to deliver in-product surveys directly inside your Android app. By integrating the SDK, you can collect targeted user feedback at critical moments in the user journey.

**Key Features:**

* Quickly embed surveys via triggers you define in your app.
* Identify and track users to ensure they don’t receive duplicate surveys unnecessarily.
* Personalize surveys with user attributes and event properties (optional).
* Localize surveys by setting different languages (optional).

**Requirements:**

* Android 5.0 (API level 21) and above.
* Java 8 compatibility (source and target).
* Access to the Blitzllama dashboard (to retrieve your API key and manage triggers).

## Getting Started

### Before You Begin

1. **Obtain Your API Key:**\
   Log in to the Blitzllama dashboard, navigate to Connections Tab, click Android, and find your `API_KEY`.<br>

   <figure><img src="/files/G9rEA3JfgbJZoDKsWC4U" alt=""><figcaption></figcaption></figure>
2. **Confirm Minimum SDK:**\
   The SDK officially supports API level 21 and above. If your `minSdk` is below 21, override the library in your `AndroidManifest`:

```java
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.myapp"
    xmlns:tools="http://schemas.android.com/tools">

  <uses-sdk tools:overrideLibrary="com.blitzllama.androidSDK" />
    ...
```

## Quick Start (5 Minutes)

### 1. SDK Installation

Add the SDK to your `app/build.gradle` and enable Java 8 (if not already):

```java
// app/build.gradle
dependencies {
    implementation 'com.blitzllama:Blitzllama:1.9.1'
}

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"
  }
}
```

{% hint style="info" %}
We recommend using AppCompatActivity while using the SDK, otherwise the surveys won't show up `HomeActivity extends AppCompatActivity{ }`
{% endhint %}

### 2. Update AndroidManifest

Declare your Blitzllama API key:

{% code title="AndroidManifest.xml" %}

```xml
<application>
    <meta-data 
    android:name="blitz_api_key"  
    android:value="API_KEY" />
</application>
```

{% endcode %}

### 3. Initialize the SDK

Create or update your `Application` class and extend `BlitzLlamaSDK`:

{% tabs %}
{% tab title="Java" %}

```java
public class MyApplication extends BlitzLlamaSDK {
    @Override
    public void onCreate() {
        super.onCreate();
        BlitzLlamaSDK.init(this);
    }
}        
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        BlitzLlamaSDK.init(this);
        }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
NOTE: If you are registering the activity lifecycle in your application class, please make sure to call the SDK's init function below that.
{% endhint %}

### 4. Create a User

Ensure you create a user with a unique ID before triggering surveys:

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.getSdkManager(this).createUser("user_id");
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
BlitzLlamaSDK.getSdkManager(this).createUser("user_id")
```

{% endtab %}
{% endtabs %}

### 5. Trigger a Survey

Add a trigger event to display surveys:

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.getSdkManager(this).triggerEvent("trigger_name")
```

{% endtab %}

{% tab title="Kotlin" %}

```
BlitzLlamaSDK.getSdkManager(this).triggerEvent("trigger_name")�
```

{% endtab %}
{% endtabs %}

You’re now ready to collect targeted user feedback with Blitzllama's in-app surveys! 🚀  Read further to check other capabilities of Blitzllama and customize to your requirement.

***

## Triggers and Event Properties

### What are Triggers?

**Triggers** are events in your app (e.g., button presses, screen loads) that prompt a survey if configured in the Blitzllama dashboard.

### Adding Trigger Properties (Optional)

You can attach properties to a trigger event to provide additional context, such as screen names or user actions. These properties help refine your targeting.&#x20;

```java
HashMap<String, Object> eventProperties = new HashMap<String, Object>();
mapValues.put("event Key", "event Value");
mapValues.put("event Key1", "event Value1");

BlitzLlamaSDK.getSdkManager(this).triggerEvent("trigger_name",eventProperties)
```

Event schemas can be changed on the dashboard. You can use these properties to more filter users in the survey, as shown in the below screenshot.

![](/files/yFfwVi3cufc0xRrZDJHA)

**Why Use Trigger Properties?**

* Filter users more precisely in the Blitzllama dashboard.
* Understand user context when surveys are triggered.

{% hint style="success" %}
You can also use **backend events** to launch in-app surveys. Check out <https://documentation.blitzllama.com/connections/backend-trigger> for more details.
{% endhint %}

## Personalizing and Localizing Surveys

### Setting User Attributes

Attributes help you segment and target specific user groups (e.g., plan type, user role). Allowed `data_type` values are "string", "number", "date", "boolean".

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.getSdkManager(this).setUserAttribute("attribute_name","attribute_value", "data_type");
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
BlitzLlamaSDK.getSdkManager(this).setUserAttribute("attribute_name","attribute_value", "data_type")
```

{% endtab %}
{% endtabs %}

Set User Email or Name:

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.getSdkManager(this).setUserEmail("user_email_address");
BlitzLlamaSDK.getSdkManager(this).setUserName("user_name");
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
BlitzLlamaSDK.getSdkManager(this).setUserEmail("user_email_address")
BlitzLlamaSDK.getSdkManager(this).setUserName("user_name")
```

{% endtab %}
{% endtabs %}

### Setting Survey Language

To display surveys in the user's preferred language, set the survey language using an ISO 639-1 code (e.g., `"en"` for English, `"es"` for Spanish).&#x20;

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.getSdkManager(this).setSurveyLanguage("language_code");
```

{% endtab %}

{% tab title="Kotlin" %}

```
BlitzLlamaSDK.getSdkManager(this).setSurveyLanguage("language_code")
```

{% endtab %}
{% endtabs %}

**Why Set Survey Language?**

* Improve user experience by displaying surveys in the user's native language.
* Supports better localization for global apps.

## User Management

### Logout

When a user logs out, call the logout method to clear their session and ensure subsequent events are not tied to the previous user’s data.

{% tabs %}
{% tab title="Java" %}

```java
BlitzLlamaSDK.logout();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
BlitzLlamaSDK.logout()
```

{% endtab %}
{% endtabs %}

**Why Logout?**

* Prevents mixing user data between sessions.
* Ensures a clean state when switching users.

## Advanced Features

### Survey Completion Callback

Receive a callback when a user completes a survey. This can be useful for analytics or triggering follow-up actions.

**Example:**

```java
import com.blitzllama.androidSDK.common.OnSurveyCompletionListener;
..
..

HashMap<String, Object> eventProperties = new HashMap<String, Object>();
mapValues.put("event Key", "event Value");

OnSurveyCompletionListener listener = result -> {
            Log.d("result",result.toString());
};

BlitzLlamaSDK.getSdkManager(this).triggerEvent("trigger_name",eventProperties,listener)
```

#### Sample Callback data&#x20;

```json
{
    "group_id": "g-d8ee8...",
    "survey_id": "s-d8ee8...",
     "event_name": "trigger name"
}
```

## **Performance Impact**

Every release we extensively test our SDK in multiple sample apps across devices and Android versions for crashes and performance issues. The performance impact is negligible and below are the stats for the latest SDK version.

* **Load times:** All calls are async and hence does not impact app or screen load times.
* **App size:** Blitzllama SDK AAR size is 150kb and it's size impact on an Android app is about 200kb.
* **CPU usage:** A negligible increase of 1-5% CPU usage only when the micro survey is on-screen. &#x20;

## FAQ & Troubleshooting

* **Survey not showing up?**
  * Ensure `createUser` is called before `triggerEvent`.
  * Check that the event name matches exactly what’s configured in the Blitzllama dashboard.
* **Survey not showing up on the home screen or the first app page?**
  * This might be a race condition, please pass a callback function as the second argument to `createUser` function.

```java
import com.blitzllama.androidSDK.SdkInitialisationSuccessCallback
..
..
val clbk = object : SdkInitialisationSuccessCallback{
    override fun onSuccess() {
        BlitzLlamaSDK.getSdkManager(this@HomeActivity).triggerEvent("MainActivity")
    }

    override fun onFailure() {
        BlitzLlamaSDK.getSdkManager(this@HomeActivity).triggerEvent("MainActivity")
    }
}

BlitzLlamaSDK.getSdkManager(this).createUser("user_id", clbk);
```

* **Switching users?**
  * Call `BlitzLlamaSDK.logout()` before creating a new user to avoid mixing sessions.

* **How to create triggers?**\
  There are two methods to create a trigger:

  1\. Add new trigger\_name in your app and it will automatically be created if it doesn't exist and then be available for selection in the dashboard. &#x20;

  2.: To add a trigger into your app, first create a trigger on the Blitzllama dashboard with a trigger\_name, then use the same trigger\_name in the following function.&#x20;

  Make sure to create a user before triggering a survey.

* **Need more help?**
  * Reach out over the support chat or email <tech@blitzllama.com>.

### Next Steps

1. **Start with adding 5 triggers** for the most critical user actions in the app.
2. **Create your first survey** on the Blitzllama dashboard.
3. **Customize the UI/UX** of the survey on the Blitzllama dashboard.


---

# 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://documentation.blitzllama.com/sdk/android.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.