Android integration

This guide covers the complete Android integration of Amply SDK.

Basic Setup

1

Add Dependency

In your app's build.gradle.kts:

dependencies {
    implementation("tools.amply:sdk-android:0.1.7")
}

2

Initialize SDK

Initialize the SDK in your Application class:

import android.app.Application
import tools.amply.sdk.Amply
import tools.amply.sdk.config.amplyConfig

class MyApplication : Application() {

    lateinit var amply: Amply
        private set

    override fun onCreate() {
        super.onCreate()

        val config = amplyConfig {
            api {
                appId = "your.app.id"
                apiKeyPublic = "your_public_key"
                apiKeySecret = "your_secret_key"
            }
        }

        amply = Amply(config, this)
    }

    companion object {
        fun getAmply(context: Context): Amply {
            return (context.applicationContext as MyApplication).amply
        }
    }
}

3

Register Application Class

In your AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ... >
</application>

Configuration Options

Full Configuration

val config = amplyConfig {
    api {
        appId = "your.app.id"
        apiKeyPublic = "your_public_key"
        apiKeySecret = "your_secret_key"
    }

    // Optional: Default campaign configuration (JSON string)
    defaultConfig = """{"campaigns": []}"""

    // Optional: Override endpoints for development
    network {
        configBaseUrl = "https://config.amply.tools"
        backendBaseUrl = "https://api.amply.tools"
    }
}

Tracking Events

Basic Events

// Simple event
amply.track("screen_viewed")

// Event with properties
amply.track("button_clicked", mapOf(
    "button_id" to "purchase_btn",
    "screen" to "product_detail"
))

From Activities/Fragments

class MainActivity : AppCompatActivity() {

    private val amply by lazy { MyApplication.getAmply(this) }

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

        amply.track("main_screen_opened")
    }

    fun onPurchaseClicked() {
        amply.track("purchase_clicked", mapOf(
            "product_id" to "12345",
            "price" to 29.99
        ))
    }
}

From Compose

@Composable
fun PurchaseButton(amply: Amply) {
    Button(onClick = {
        amply.track("purchase_clicked")
    }) {
        Text("Purchase")
    }
}

Handling Deep Links

Register Listener

amply.registerDeepLinkListener { url, info ->
    Log.d("Amply", "Deep link received: $url")

    when {
        url.startsWith("myapp://promo/") -> {
            val promoId = url.removePrefix("myapp://promo/")
            openPromoScreen(promoId)
            true
        }
        url.startsWith("myapp://settings") -> {
            openSettings()
            true
        }
        else -> false // Not handled
    }
}

Handle in Activity

class DeepLinkActivity : AppCompatActivity() {

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

        intent?.data?.let { uri ->
            // Handle external deep links
            handleDeepLink(uri.toString())
        }
    }

    private fun handleDeepLink(url: String) {
        // Your navigation logic
    }
}

System Events

Listen for SDK system events:

amply.setSystemEventsListener { event ->
    Log.d("Amply", "System event: ${event.name}")

    when (event.name) {
        "SDK_INITIALIZED" -> onSdkReady()
        "CAMPAIGNS_LOADED" -> onCampaignsReady()
        "SESSION_START" -> onSessionStart()
    }
}

Rate & Review

The SDK supports triggering app store reviews via campaigns. On Android:

• Release builds (Play Store): Uses Google Play In-App Review API

• Debug builds: Shows a simulated dialog for testing

No additional code is needed - rate review actions are handled automatically when campaigns trigger them.

Retrieving Data

Get Dataset Snapshots

import tools.amply.sdk.datasets.DataSetType

// In a coroutine
lifecycleScope.launch {
    // Device data
    val deviceData = amply.getDataSetSnapshot(DataSetType.Device)
    Log.d("Amply", "Device: $deviceData")

    // Session data
    val sessionData = amply.getDataSetSnapshot(DataSetType.Session)
    Log.d("Amply", "Session: $sessionData")

    // Event data
    val eventData = amply.getDataSetSnapshot(
        DataSetType.TriggeredEvent("purchase_completed")
    )
    Log.d("Amply", "Event: $eventData")
}

Get Recent Events

lifecycleScope.launch {
    val events = amply.getRecentEvents(limit = 30)
    events.forEach { event ->
        Log.d("Amply", "${event.name} at ${event.timestamp}")
    }
}

Permissions

Advertising ID (Optional)

To collect Google Advertising ID, add to your build.gradle.kts:

dependencies {
    implementation("com.google.android.gms:play-services-ads-identifier:18.0.1")
}

The SDK will automatically collect the advertising ID when available.

Best Practices

• Initialize early — Initialize in Application.onCreate() for accurate session tracking

• Use a singleton — Keep one SDK instance throughout app lifecycle

• Track meaningfully — Focus on events that drive insights

• Test campaigns — Use debug builds to verify campaign behavior

• Handle deep links — Always provide fallback behavior

Troubleshooting

SDK Not Initializing

• Verify API keys are correct

• Check network connectivity

• Review logcat for error messages

Events Not Sending

• Ensure SDK is initialized before tracking

• Check if app has network permission

• Verify backend URL is accessible

Campaigns Not Triggering

• Use getDataSetSnapshot() to verify data

• Check targeting and triggering rules

• Ensure system events listener is registered