Complete Installation & Setup

Overview

This guide covers complete installation of the Stringboot Android SDK, including analytics integration for A/B testing. Follow all steps to unlock the full capabilities of dynamic strings, translations, and experiments.

A/B Testing Setup is Included: This guide includes analytics handler and device ID configuration required for experiments. These are core features, not optional add-ons.

Step 1: Add Maven Repository

Add Maven Central to your project’s settings.gradle.kts:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()  // Stringboot SDK is hosted on Maven Central
    }
}

Step 2: Add SDK Dependency

In your app’s build.gradle.kts:

build.gradle.kts

dependencies {
    implementation("com.stringboot:stringboot-android-sdk:1.2.0")
}

All transitive dependencies (Room, Retrofit, OkHttp, Coroutines) are included automatically. Latest Version: Check Maven Central

Step 3: Sync Project

Click Sync Now in Android Studio or run:

./gradlew build

Step 4: Secure API Credentials

Security Best Practice: Never hardcode API tokens in source code or manifest files.

Add to gradle.properties

Create or edit gradle.properties in your project root and add to .gitignore:

gradle.properties

# Add these lines
STRINGBOOT_API_URL=https://api.stringboot.com
STRINGBOOT_API_TOKEN=your_api_token_here

Configure Build Script

In app/build.gradle.kts, configure manifest placeholders:

build.gradle.kts

android {
    defaultConfig {
        // Read from gradle.properties or environment variables
        val apiUrl = project.findProperty("STRINGBOOT_API_URL")?.toString()
            ?: System.getenv("STRINGBOOT_API_URL")
            ?: error("STRINGBOOT_API_URL not configured. Add to gradle.properties")

        val apiToken = project.findProperty("STRINGBOOT_API_TOKEN")?.toString()
            ?: System.getenv("STRINGBOOT_API_TOKEN")
            ?: error("STRINGBOOT_API_TOKEN not configured. Add to gradle.properties")

        // Make available to AndroidManifest.xml
        manifestPlaceholders["STRINGBOOT_API_URL"] = apiUrl
        manifestPlaceholders["STRINGBOOT_API_TOKEN"] = apiToken
    }
}

Step 5: Configure AndroidManifest.xml

Add required permissions and SDK configuration:

AndroidManifest.xml

<application
        <!-- Stringboot SDK Configuration -->
        <meta-data
            android:name="com.stringboot.api_url"
            android:value="${STRINGBOOT_API_URL}" />
        <meta-data
            android:name="com.stringboot.api_token"
            android:value="${STRINGBOOT_API_TOKEN}" />
        <meta-data
            android:name="com.stringboot.default_locale"
            android:value="en" />
        <meta-data
            android:name="com.stringboot.cache_size"
            android:value="1000" />
</application>

Step 6: Analytics Handler (Required for A/B Testing)

Why Analytics Integration is Required

The analytics handler enables:

Experiment tracking: Know which users see which variants
Results analysis: Measure impact of string changes
Data-driven decisions: Use analytics platforms for statistical analysis

Firebase Analytics
Mixpanel
Amplitude
Custom Analytics

Add Firebase Dependency

build.gradle.kts

dependencies {
    implementation("com.stringboot:stringboot-android-sdk:1.2.0")
    implementation("com.google.firebase:firebase-analytics-ktx:21.5.0")
}

Implement Analytics Handler

StringbootApplication.kt

import com.google.firebase.analytics.FirebaseAnalytics
import com.google.firebase.analytics.ktx.analytics
import com.google.firebase.ktx.Firebase
import com.stringboot.sdk.analytics.StringbootAnalyticsHandler
import com.stringboot.sdk.models.ExperimentAssignment

class StringbootApplication : Application() {

    private lateinit var firebaseAnalytics: FirebaseAnalytics

    override fun onCreate() {
        super.onCreate()

        // Initialize Firebase
        firebaseAnalytics = Firebase.analytics

        // Create analytics handler
        val analyticsHandler = object : StringbootAnalyticsHandler {
            override fun onExperimentsAssigned(experiments: Map<String, ExperimentAssignment>) {
                experiments.forEach { (key, assignment) ->
                    // Set user property for each experiment
                    firebaseAnalytics.setUserProperty(
                        "stringboot_exp_$key",
                        assignment.variantName
                    )

                    StringbootLogger.i("Experiment: $key → ${assignment.variantName}")
                }
            }
        }

        // Initialize Stringboot with analytics
        StringbootExtensions.autoInitialize(
            context = this,
            analyticsHandler = analyticsHandler
        )
    }
}

Step 7: Device ID Configuration (Required for A/B Testing)

Why Device ID is Required

Consistent assignments: Same device always gets same variant
Cross-session persistence: Experiments persist across app restarts
Accurate results: Users don’t switch between variants randomly

Auto-Generated (Default)
Firebase Installation ID
Custom Device ID

SDK-Generated UUID (Recommended)

By default, the SDK generates a persistent UUID per app installation:

StringbootApplication.kt

class StringbootApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // SDK automatically generates and persists a UUID
        StringbootExtensions.autoInitialize(
            context = this,
            analyticsHandler = analyticsHandler
            // providedDeviceId not specified - SDK generates UUID
        )
    }
}

Characteristics:

Persists across app launches
Unique per app installation
Automatically managed by SDK
Use this unless you have a specific reason to use custom ID

Step 8: Complete SDK Initialization

Here’s the complete Application class with all components:

StringbootApplication.kt

package com.yourapp

import android.app.Application
import androidx.lifecycle.ProcessLifecycleOwner
import com.google.firebase.analytics.FirebaseAnalytics
import com.google.firebase.analytics.ktx.analytics
import com.google.firebase.ktx.Firebase
import com.stringboot.sdk.StringProvider
import com.stringboot.sdk.StringbootExtensions
import com.stringboot.sdk.analytics.StringbootAnalyticsHandler
import com.stringboot.sdk.models.ExperimentAssignment
import com.stringboot.sdk.utils.StringbootLogger
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

class StringbootApplication : Application() {

    private val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
    private lateinit var firebaseAnalytics: FirebaseAnalytics

    override fun onCreate() {
        super.onCreate()

        // Initialize Firebase Analytics
        firebaseAnalytics = Firebase.analytics

        // Create analytics handler for experiments
        val analyticsHandler = object : StringbootAnalyticsHandler {
            override fun onExperimentsAssigned(experiments: Map<String, ExperimentAssignment>) {
                experiments.forEach { (key, assignment) ->
                    // Set user property in Firebase
                    firebaseAnalytics.setUserProperty(
                        "stringboot_exp_$key",
                        assignment.variantName
                    )

                    StringbootLogger.i("📊 Experiment: $key → ${assignment.variantName}")
                }
            }
        }

        // Auto-initialize SDK from manifest configuration
        val success = StringbootExtensions.autoInitialize(
            context = this,
            providedDeviceId = null,  // Let SDK generate UUID (or provide custom)
            analyticsHandler = analyticsHandler
        )

        if (success) {
            StringbootLogger.i("✅ Stringboot initialized successfully")

            // Preload current language for instant access
            runBlocking {
                val locale = StringProvider.deviceLocale()
                StringProvider.preloadLanguage(locale, maxStrings = 500)
                StringbootLogger.i("📦 Preloaded $locale strings into memory")
            }

            // Refresh from network in background
            applicationScope.launch {
                val locale = StringProvider.deviceLocale()
                StringProvider.refreshFromNetwork(locale)
                StringbootLogger.i("🔄 Background sync complete for $locale")
            }
        } else {
            StringbootLogger.w("⚠️ Stringboot auto-initialization failed")

            // Fallback: offline-only mode
            try {
                StringProvider.initialize(
                    context = this,
                    cacheSize = 1000,
                    api = null  // No network access
                )
                StringbootLogger.i("✅ Stringboot initialized in offline mode")
            } catch (e: Exception) {
                StringbootLogger.e("❌ Fallback initialization failed: ${e.message}", e)
            }
        }
    }
}

Step 9: Verify Setup

Test SDK Initialization

Run your app with debug logging enabled
Check Logcat for Stringboot initialization messages:

I/Stringboot: ✅ Stringboot initialized successfully
I/Stringboot: 📦 Preloaded en strings into memory
I/Stringboot: 🔄 Background sync complete for en

Test String Retrieval

Add a test in your MainActivity:

MainActivity.kt

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Test string retrieval
        val testString = StringProvider.get("welcome_message", "en")
        Log.i("StringbootTest", "String value: $testString")

        // Should NOT see "??welcome_message??" (means string loaded)
    }
}

Test Experiment Assignment

If you have experiments running:

// Check device ID
val deviceId = StringProvider.getDeviceId()
Log.i("StringbootTest", "Device ID: $deviceId")

// Look for experiment logs
// I/Stringboot: 📊 Experiment: cta-test → variant-a

Verify Analytics Integration

Check your analytics platform (Firebase/Mixpanel/Amplitude)
Look for user properties like stringboot_exp_cta_test
Value should be variant name: control, variant-a, etc.

Common Setup Issues

Build fails with 'STRINGBOOT_API_TOKEN not configured'

Cause: API token not in gradle.propertiesSolution:

Create gradle.properties in project root (next to settings.gradle.kts)
Add STRINGBOOT_API_TOKEN=your_token_here
Add gradle.properties to .gitignore
Sync project

Analytics handler not called

Possible causes:

No experiments running in dashboard
Analytics handler not passed to autoInitialize()
Device not assigned to any experiments

Solutions:

Create test experiment in dashboard
Verify analyticsHandler parameter is set
Check device ID is being sent with requests

Strings show '??key??' pattern

Causes:

API token invalid
No network connectivity
Strings not created in dashboard

Solutions:

Verify API token in dashboard
Check internet permission in manifest
Ensure strings exist for your app

Device ID changes on each launch

Cause: Using non-persistent ID or regenerating UUIDSolution:

Use default SDK-generated UUID (it persists automatically)
If using custom ID, store it in SharedPreferences
Don’t generate new UUID on each launch

Next Steps

Now that setup is complete, learn how to use the three core features:

Dynamic Strings

Update app copy without releases

Translations

Multi-language support and switching

A/B Testing

Run experiments to optimize messaging

Additional Resources

Best Practices

Production-ready patterns

Advanced Usage

FAQ management, caching, optimization

Core Concepts

Architecture and offline behavior

Troubleshooting

Common issues and solutions

Questions? Contact [email protected]

Overview

Android SDK

iOS SDK

Web SDK

Dashboard

Advanced

Complete Installation & Setup

Overview

Step 1: Add Maven Repository

Step 2: Add SDK Dependency

Step 3: Sync Project

Step 4: Secure API Credentials

Add to gradle.properties

Configure Build Script

Step 5: Configure AndroidManifest.xml

Step 6: Analytics Handler (Required for A/B Testing)

Why Analytics Integration is Required

Add Firebase Dependency

Implement Analytics Handler

Step 7: Device ID Configuration (Required for A/B Testing)

Why Device ID is Required

SDK-Generated UUID (Recommended)

Step 8: Complete SDK Initialization

Step 9: Verify Setup

Test SDK Initialization

Test String Retrieval

Test Experiment Assignment

Verify Analytics Integration

Common Setup Issues

Next Steps

Dynamic Strings

Translations

A/B Testing

Additional Resources

Best Practices

Advanced Usage

Core Concepts

Troubleshooting

Overview

Android SDK

iOS SDK

Web SDK

Dashboard

Advanced

​Overview

​Step 1: Add Maven Repository

​Step 2: Add SDK Dependency

​Step 3: Sync Project

​Step 4: Secure API Credentials

​Add to gradle.properties

​Configure Build Script

​Step 5: Configure AndroidManifest.xml

​Step 6: Analytics Handler (Required for A/B Testing)

​Why Analytics Integration is Required

​Add Firebase Dependency

​Implement Analytics Handler

​Step 7: Device ID Configuration (Required for A/B Testing)

​Why Device ID is Required

​SDK-Generated UUID (Recommended)

​Step 8: Complete SDK Initialization

​Step 9: Verify Setup

​Test SDK Initialization

​Test String Retrieval

​Test Experiment Assignment

​Verify Analytics Integration

​Common Setup Issues

​Next Steps

Dynamic Strings

Translations

A/B Testing

​Additional Resources

Best Practices

Advanced Usage

Core Concepts

Troubleshooting

Overview

Step 1: Add Maven Repository

Step 2: Add SDK Dependency

Step 3: Sync Project

Step 4: Secure API Credentials

Add to gradle.properties

Configure Build Script

Step 5: Configure AndroidManifest.xml

Step 6: Analytics Handler (Required for A/B Testing)

Why Analytics Integration is Required

Add Firebase Dependency

Implement Analytics Handler

Step 7: Device ID Configuration (Required for A/B Testing)

Why Device ID is Required

SDK-Generated UUID (Recommended)

Step 8: Complete SDK Initialization

Step 9: Verify Setup

Test SDK Initialization

Test String Retrieval

Test Experiment Assignment

Verify Analytics Integration

Common Setup Issues

Next Steps

Additional Resources