Skip to content

API.md

Latest commit

 

History

History
516 lines (359 loc) · 10.7 KB

API.md

File metadata and controls

516 lines (359 loc) · 10.7 KB

LinkForty Android SDK - API Reference

Complete API reference for the LinkForty Android SDK.

Table of Contents

LinkForty

Main singleton class providing the SDK interface.

Singleton Access

LinkForty.shared

Throws LinkFortyError.NotInitialized if initialize() has not been called.

Methods

initialize(context, config, attributionWindowHours, deviceId)

Initializes the SDK with configuration and reports the install.

suspend fun initialize(
    context: Context,
    config: LinkFortyConfig,
    attributionWindowHours: Int = 168,
    deviceId: String? = null
): InstallResponse

Parameters:

  • context: Android Context (stored as applicationContext)
  • config: SDK configuration (required)
  • attributionWindowHours: Attribution window in hours (default: 168 = 7 days)
  • deviceId: Optional device identifier for attribution (e.g., GAID)

Returns: InstallResponse with attribution data

Throws: LinkFortyError if initialization fails

Example:

val config = LinkFortyConfig(
    baseURL = "https://go.yourdomain.com",
    apiKey = "your-api-key"
)
val response = LinkForty.initialize(context, config)
Log.d("LinkForty", "Install ID: ${response.installId}")

handleDeepLink(uri)

Handles a deep link URI (App Link or custom scheme).

fun handleDeepLink(uri: Uri)

Parameters:

  • uri: The deep link URI to handle

Example:

intent.data?.let { uri ->
    LinkForty.shared.handleDeepLink(uri)
}

onDeferredDeepLink(callback)

Registers a callback for deferred deep links (install attribution).

fun onDeferredDeepLink(callback: DeferredDeepLinkCallback)

Parameters:

  • callback: Lambda invoked with deep link data (or null for organic installs)

Example:

LinkForty.shared.onDeferredDeepLink { deepLinkData ->
    if (deepLinkData != null) {
        Log.d("LinkForty", "Attributed: ${deepLinkData.shortCode}")
    } else {
        Log.d("LinkForty", "Organic install")
    }
}

onDeepLink(callback)

Registers a callback for direct deep links (when app opens from a link).

fun onDeepLink(callback: DeepLinkCallback)

Parameters:

  • callback: Lambda invoked with URI and parsed deep link data

Example:

LinkForty.shared.onDeepLink { uri, deepLinkData ->
    Log.d("LinkForty", "Opened from: $uri")
    deepLinkData?.deepLinkPath?.let { navigateToPath(it) }
}

createLink(options)

Creates a short link programmatically.

suspend fun createLink(options: CreateLinkOptions): CreateLinkResult

Parameters:

Returns: CreateLinkResult with the shareable URL, short code, and link ID

Throws:

  • LinkFortyError.NotInitialized if SDK not initialized
  • LinkFortyError.MissingApiKey if no API key configured

Note: Requires an API key. If templateId is provided, uses POST /api/links. Otherwise, uses POST /api/sdk/v1/links.

Example:

val result = LinkForty.shared.createLink(
    CreateLinkOptions(
        deepLinkParameters = mapOf("route" to "VIDEO_VIEWER"),
        title = "Check this out!",
        utmParameters = UTMParameters(source = "app", campaign = "share")
    )
)
Log.d("LinkForty", "Share: ${result.url}")

trackEvent(name, properties)

Tracks a custom event.

suspend fun trackEvent(
    name: String,
    properties: Map<String, Any>? = null
)

Parameters:

  • name: Event name (e.g., "purchase", "signup")
  • properties: Optional event properties (must be JSON-serializable)

Throws: LinkFortyError if tracking fails

Example:

LinkForty.shared.trackEvent("purchase", mapOf("product_id" to "123", "amount" to 29.99))

trackRevenue(amount, currency, properties)

Tracks a revenue event.

suspend fun trackRevenue(
    amount: BigDecimal,
    currency: String,
    properties: Map<String, Any>? = null
)

Parameters:

  • amount: Revenue amount (must be non-negative)
  • currency: Currency code (e.g., "USD", "EUR")
  • properties: Optional additional properties

Throws: LinkFortyError if tracking fails

Example:

LinkForty.shared.trackRevenue(
    amount = BigDecimal("29.99"),
    currency = "USD",
    properties = mapOf("product_id" to "123")
)

flushEvents()

Flushes the event queue, attempting to send all queued events.

suspend fun flushEvents()

clearEventQueue()

Clears the event queue without sending events.

fun clearEventQueue()

Properties

queuedEventCount

Returns the number of events currently queued.

val queuedEventCount: Int

Attribution Data Methods

getInstallId()

Returns the install ID if available, null if not initialized.

fun getInstallId(): String?

getInstallData()

Returns the install attribution data if available.

fun getInstallData(): DeepLinkData?

isFirstLaunch()

Returns whether this is the first launch.

fun isFirstLaunch(): Boolean

Data Management Methods

clearData()

Clears all stored SDK data.

fun clearData()

reset()

Resets the SDK to uninitialized state. Does NOT clear stored data — call clearData() first if needed.

fun reset()

LinkFortyConfig

Configuration for the LinkForty SDK.

Constructor

data class LinkFortyConfig(
    val baseURL: String,
    val apiKey: String? = null,
    val debug: Boolean = false,
    val attributionWindowHours: Int = 168
)

Parameters:

  • baseURL: Backend URL (must be HTTPS except localhost/127.0.0.1/10.0.2.2)
  • apiKey: API key (optional for self-hosted)
  • debug: Enable debug logging (default: false)
  • attributionWindowHours: Attribution window in hours (default: 168 = 7 days, max: 2160 = 90 days)

Methods

validate()

Validates the configuration. Throws LinkFortyError.InvalidConfiguration if validation fails.

fun validate()

DeepLinkData

Deep link data model containing parsed link information.

Properties

val shortCode: String             // Link short code (required)
val iosURL: String?               // iOS deep link URL
val androidURL: String?           // Android deep link URL
val webURL: String?               // Fallback web URL
val utmParameters: UTMParameters? // UTM tracking parameters
val customParameters: Map<String, String>? // Custom query parameters
val deepLinkPath: String?         // Deep link path for in-app routing
val appScheme: String?            // App URI scheme
val clickedAt: String?            // ISO 8601 click timestamp
val linkId: String?               // Link UUID from the backend

Methods

clickedAtDate()

Parses clickedAt as a java.time.Instant.

fun clickedAtDate(): Instant?

InstallResponse

Response from install attribution API.

Properties

val installId: String             // Unique install ID
val attributed: Boolean           // Whether install was attributed
val confidenceScore: Double       // Confidence score (0-100)
val matchedFactors: List<String>  // Matched fingerprint factors
val deepLinkData: DeepLinkData?   // Deep link data if attributed

CreateLinkOptions

Options for creating a short link programmatically.

Constructor

data class CreateLinkOptions(
    val templateId: String? = null,
    val templateSlug: String? = null,
    val deepLinkParameters: Map<String, String>? = null,
    val title: String? = null,
    val description: String? = null,
    val customCode: String? = null,
    val utmParameters: UTMParameters? = null
)

CreateLinkResult

Result of creating a short link.

Properties

val url: String       // Full shareable URL
val shortCode: String // Generated short code
val linkId: String    // Link UUID

UTMParameters

UTM parameters for campaign tracking.

Properties

val source: String?   // Campaign source
val medium: String?   // Campaign medium
val campaign: String? // Campaign name
val term: String?     // Campaign term
val content: String?  // Campaign content

Computed Properties

val hasAnyParameter: Boolean // True if any parameter is set

LinkFortyError

Sealed class of errors thrown by the SDK.

Subclasses

class NotInitialized : LinkFortyError
class AlreadyInitialized : LinkFortyError
class InvalidConfiguration(detail: String) : LinkFortyError
class NetworkError(cause: Throwable) : LinkFortyError
class InvalidResponse(statusCode: Int?, responseMessage: String?) : LinkFortyError
class DecodingError(cause: Throwable) : LinkFortyError
class EncodingError(cause: Throwable) : LinkFortyError
class InvalidEventData(detail: String) : LinkFortyError
class InvalidDeepLinkUrl(detail: String) : LinkFortyError
class MissingApiKey : LinkFortyError

Example

try {
    LinkForty.shared.trackEvent("test")
} catch (e: LinkFortyError) {
    when (e) {
        is LinkFortyError.NotInitialized -> Log.e("LinkForty", "Not initialized")
        is LinkFortyError.NetworkError -> Log.e("LinkForty", "Network error", e.cause)
        is LinkFortyError.InvalidEventData -> Log.e("LinkForty", "Invalid event: ${e.message}")
        else -> Log.e("LinkForty", "Error: ${e.message}")
    }
}

Type Aliases

DeferredDeepLinkCallback

typealias DeferredDeepLinkCallback = (DeepLinkData?) -> Unit

DeepLinkCallback

typealias DeepLinkCallback = (Uri, DeepLinkData?) -> Unit

Thread Safety

All SDK methods are thread-safe. Callbacks are executed on the main thread. Internal state is protected by Kotlin Mutex.

Coroutines Support

The SDK uses Kotlin coroutines for all asynchronous operations:

lifecycleScope.launch {
    val response = LinkForty.initialize(context, config)
    LinkForty.shared.trackEvent("test")
    LinkForty.shared.flushEvents()
}

Offline Support

Events are automatically queued when offline and sent when connectivity is restored. The queue has a maximum size of 100 events.

For more information, see the full documentation or LinkForty Docs.