Android SDK Functions
Complete reference for the Told Android SDK API.
init
Initialize the SDK. Must be called before any other function, typically in your Application.onCreate().
Told.init(
configuration = ToldConfiguration(
sourceId = "YOUR_SOURCE_ID",
applicationId = applicationContext.packageName,
appVersion = "${BuildConfig.VERSION_NAME}_${BuildConfig.VERSION_CODE}",
environment = ToldEnvironment.Production,
),
completion = { success ->
Log.d("Told", "Init: $success")
}
)
| Parameter | Type | Description |
|---|---|---|
configuration | ToldConfiguration | SDK configuration (see below) |
completion | ((Boolean) -> Unit)? | Callback receiving true on success (optional) |
ToldConfiguration
| Parameter | Type | Description |
|---|---|---|
sourceId | String | Your source ID from the Told dashboard |
applicationId | String | Your app's package name |
appVersion | String | Your app version |
environment | ToldEnvironment | ToldEnvironment.Production or ToldEnvironment.Development |
language | String? | Override device language (optional, auto-detected if null) |
preview | Boolean | Enable preview mode (optional, defaults to false) |
ToldEnvironment
| Environment | Server URL | Widget URL |
|---|---|---|
ToldEnvironment.Production | https://api.told.club/graphql | https://widget.told.club |
ToldEnvironment.Development | https://testapi.told.club/graphql | https://testwidget.told.club |
identify
Update the current user's information. Call this when the user logs in or when their profile changes.
Told.identify(properties: Map<String, Any>)
Example:
Told.identify(mapOf(
"id" to "user_123",
"name" to "Jane Doe",
"email" to "[email protected]"
))
Set language
Override automatic language detection by passing language in the properties:
Told.identify(mapOf("language" to "en"))
trackEvent
Send a custom event for triggering surveys:
Told.trackEvent(eventName: String, properties: Map<String, Any> = emptyMap())
| Parameter | Type | Description |
|---|---|---|
eventName | String | Name of the event |
properties | Map<String, Any> | Additional event properties (optional, defaults to emptyMap()) |
Example:
Told.trackEvent("purchase_completed", mapOf("amount" to 49.99))
registerNavController
Register a Jetpack Navigation controller to automatically track screen changes. Use this for Compose or Fragment-based navigation.
val navController: NavHostController = rememberNavController()
LaunchedEffect(key1 = navController) {
Told.registerNavController(navController = navController)
}
| Parameter | Type | Description |
|---|---|---|
navController | NavController | The Jetpack Navigation controller to monitor |
The destination name sent to Told is the fully qualified name of your destination (e.g., com.myapp.MyDestination). This name must match the trigger configuration in the Told dashboard.
registerActivityCallback
For activity-based navigation (no NavController), register to listen for activity changes:
Told.registerActivityCallback()
Call this once during your application's lifecycle. If you use NavController, prefer registerNavController instead.
unregisterActivityCallback
Manually unregister the activity callback:
Told.unregisterActivityCallback()
Useful if you switch between NavController and activity-based navigation.
start
Manually start a specific survey by ID:
Told.start(surveyId: String, withDelay: Duration = 0.seconds)
| Parameter | Type | Description |
|---|---|---|
surveyId | String | The survey ID from the Told dashboard |
withDelay | Duration | Delay before showing the survey (optional, defaults to 0.seconds) |
Example:
import kotlin.time.Duration.Companion.seconds
Told.start(surveyId = "SURVEY_ID", withDelay = 2.seconds)
reset
Reset the user to anonymous state. Call this when the user logs out. This is a suspend function.
suspend fun reset(newConfiguration: ToldConfiguration? = null): Boolean
| Parameter | Type | Description |
|---|---|---|
newConfiguration | ToldConfiguration? | Optionally apply a new configuration after reset (optional) |
Returns: Boolean — true if the reset succeeded.
Example:
lifecycleScope.launch {
val success = Told.reset()
}
setPreview
Toggle preview/test mode. This is a suspend function.
suspend fun setPreview(preview: Boolean)
| Parameter | Type | Description |
|---|---|---|
preview | Boolean | true to enable preview mode, false to disable |
Example:
lifecycleScope.launch {
Told.setPreview(true)
}
debugWidget
Log diagnostic information about your source and surveys to Logcat (tag: Told):
Told.debugWidget()