Kotlin Examples

Complete examples for using the yLnk API with Kotlin.

Setup

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

class YLnkAPI(private val apiKey: String) {
    private val baseUrl = "https://api.ylnk.cc/v2/external/client"
    private val client = HttpClient()
    private val json = Json { ignoreUnknownKeys = true }

    private suspend fun request(
        method: HttpMethod,
        endpoint: String,
        body: Any? = null,
        params: Map<String, String> = emptyMap()
    ): Map<String, Any> {
        val url = buildString {
            append(baseUrl)
            append(endpoint)
            if (params.isNotEmpty()) {
                append("?")
                append(params.entries.joinToString("&") { "${it.key}=${it.value}" })
            }
        }

        val response = client.request(url) {
            this.method = method
            headers {
                append("X-API-Key", apiKey)
                append("Content-Type", "application/json")
            }
            if (body != null) {
                setBody(json.encodeToString(body))
            }
        }

        val result: Map<String, Any> = json.decodeFromString(response.bodyAsText())
        return result["data"] as Map<String, Any>
    }
}

Create Short Link

@Serializable
data class CreateLinkRequest(
    val originalUrl: String,
    val title: String? = null,
    val customUrl: String? = null,
    val category: String? = null,
    val categoryTitle: String? = null,
    val categoryValue: String? = null
)

suspend fun createShortLink(
    originalUrl: String,
    title: String? = null,
    customUrl: String? = null
): Map<String, Any> {
    val request = CreateLinkRequest(originalUrl, title, customUrl)
    return api.request(HttpMethod.Post, "/short-links", request)
}

// Usage
val link = createShortLink(
    originalUrl = "https://example.com/very/long/url",
    title = "My Link",
    customUrl = "my-link"
)
println("Created: ${link["shortUrl"]}")

Update Short Link

@Serializable
data class UpdateLinkRequest(
    val id: String,
    val title: String? = null,
    val shortUrl: String? = null,
    val isActive: Boolean
)

suspend fun updateShortLink(
    id: String,
    title: String? = null,
    isActive: Boolean = true
): Map<String, Any> {
    val request = UpdateLinkRequest(id, title, null, isActive)
    return api.request(HttpMethod.Put, "/short-links/$id", request)
}

// Usage
val updated = updateShortLink("abc123", title = "Updated Title", isActive = true)

List Short Links

suspend fun listShortLinks(
    page: Int = 1,
    size: Int = 10,
    search: String? = null,
    status: String? = null
): Map<String, Any> {
    val params = buildMap {
        put("page", page.toString())
        put("size", size.toString())
        search?.let { put("search", it) }
        status?.let { put("status", it) }
    }
    return api.request(HttpMethod.Get, "/short-links", params = params)
}

// Usage
val links = listShortLinks(page = 1, size = 20, search = "example", status = "active")
val total = links["totalElements"] as Int
println("Total: $total")

Get Short Link

suspend fun getShortLink(id: String): Map<String, Any> {
    return api.request(HttpMethod.Get, "/short-links/$id")
}

// Usage
val link = getShortLink("abc123")
val clicks = link["visitCount"] as Int
println("Clicks: $clicks")

Get Analytics Details

suspend fun getAnalyticsDetails(shortUrl: String): Map<String, Any> {
    val params = mapOf("shortUrl" to shortUrl)
    return api.request(HttpMethod.Get, "/analytics/details", params = params)
}

// Usage
val details = getAnalyticsDetails("abc123")
val clicks = details["visitCount"] as Int
println("Total clicks: $clicks")

Get Click Traffic

suspend fun getClickTraffic(shortUrl: String): Map<String, Any> {
    val params = mapOf("shortUrl" to shortUrl)
    return api.request(HttpMethod.Get, "/analytics/click-traffic-platforms", params = params)
}

// Usage
val traffic = getClickTraffic("abc123")
val clicksByCountry = traffic["clicksTraffic"] as Map<String, Int>
val topPlatforms = traffic["topPlatforms"] as Map<String, Int>
println("Clicks by country: $clicksByCountry")
println("Top platforms: $topPlatforms")

Get Visit Logs

suspend fun getVisitLogs(
    shortUrl: String,
    startDate: String,
    endDate: String,
    page: Int = 1,
    pageSize: Int = 10
): Map<String, Any> {
    val params = mapOf(
        "shortUrl" to shortUrl,
        "startDate" to startDate,
        "endDate" to endDate,
        "page" to page.toString(),
        "pageSize" to pageSize.toString()
    )
    return api.request(HttpMethod.Get, "/analytics/visit-logs", params = params)
}

// Usage
val logs = getVisitLogs("abc123", "2024-01-01", "2024-01-31", page = 1, pageSize = 20)
val total = logs["totalElements"] as Int
println("Total visits: $total")
val content = logs["content"] as List<Map<String, Any>>
content.forEach { log ->
    println("${log["countryName"]}: ${log["browserName"]} on ${log["osName"]}")
}

Filter Visit Logs by UTM

suspend fun filterVisitLogs(
    shortUrl: String,
    startDate: String,
    endDate: String,
    utmSource: String? = null,
    utmMedium: String? = null,
    utmCampaign: String? = null
): Int {
    val params = buildMap {
        put("shortUrl", shortUrl)
        put("startDate", startDate)
        put("endDate", endDate)
        utmSource?.let { put("utmSource", it) }
        utmMedium?.let { put("utmMedium", it) }
        utmCampaign?.let { put("utmCampaign", it) }
    }
    val result = api.request(HttpMethod.Get, "/analytics/filter-visit-logs", params = params)
    return result as Int
}

// Usage
val count = filterVisitLogs(
    shortUrl = "abc123",
    startDate = "2024-01-01",
    endDate = "2024-01-31",
    utmSource = "google",
    utmMedium = "cpc",
    utmCampaign = "summer-sale"
)
println("Matching visits: $count")