Creating links

Lander.createLink creates a Lander short link from the app, for example when someone taps Share on a product or Invite a friend. The link works like one made in the dashboard: it opens your app on the right screen, or sends people without the app to the store or your website.

Create a linkCopy Anchor Link

private fun shareProduct(id: String, name: String) {
    lifecycleScope.launch {
        try {
            val link = Lander.createLink(
                path = "/product/$id",
                params = mapOf("productId" to id),
                title = name,
                channel = "share",
            )
            val send = Intent(Intent.ACTION_SEND)
                .setType("text/plain")
                .putExtra(Intent.EXTRA_TEXT, link.url)
            startActivity(Intent.createChooser(send, "Share"))
        } catch (e: LanderException) {
            Toast.makeText(this@ProductActivity, "Could not create a link: ${e.message}", Toast.LENGTH_SHORT).show()
        }
    }
}

link.url is the shareable URL, for example https://acme.golander.link/x7Kp2Qa. createLink suspends while the request runs, off the main thread, so call it from a coroutine such as lifecycleScope.

When someone opens that link, your app receives a LanderLink with path == "/product/123" and params == mapOf("productId" to "123"). See Receiving links.

From JavaCopy Anchor Link

Build a LanderLinkOptions and pass a callback, called on the main thread:

LanderLinkOptions options = new LanderLinkOptions.Builder()
        .path("/product/" + id)
        .param("productId", id)
        .title(name)
        .channel("share")
        .build();

Lander.createLink(options, new LanderCallback<LanderShortLink>() {
    @Override
    public void onSuccess(LanderShortLink link) {
        share(link.getUrl());
    }

    @Override
    public void onError(Exception error) {
        // A LanderException for API and network failures.
    }
});

Kotlin can pass a LanderLinkOptions too: Lander.createLink(options).

ParametersCopy Anchor Link

suspend fun createLink(
    path: String = "/",
    params: Map<String, Any> = emptyMap(),
    title: String? = null,
    campaign: String? = null,
    channel: String? = null,
    tags: List<String> = emptyList(),
    iosFallbackUrl: String? = null,
    androidFallbackUrl: String? = null,
    webFallbackUrl: String? = null,
    ogTitle: String? = null,
    ogDescription: String? = null,
    ogImageUrl: String? = null,
    expiresAt: Date? = null,
): LanderShortLink

What you cannot choose from the app:

• The slug is always random (7 characters).
• The domain is the project's default domain.
• The environment follows the key: a pk_test_ key creates test links, a pk_live_ key creates live links.

The resultCopy Anchor Link

createLink returns a LanderShortLink:

toString() returns the URL, so "Check this out: $link" reads naturally.

ErrorsCopy Anchor Link

createLink checks two things before it sends anything, and throws an IllegalArgumentException when:

• path does not start with /.
• A params value is not a String, Number or Boolean (or is a non finite number).

It throws IllegalStateException before Lander.initialize. Everything else is checked by the API. Failures throw a LanderException:

e.isRetryable is true for network errors, timeouts, invalid_response, 408, 429 (except link_quota_exceeded) and 5xx responses. e.retryAfter is a kotlin.time.Duration; Java reads getRetryAfterMillis().

Retries never create two linksCopy Anchor Link

The SDK retries network errors, timeouts, 408, 429 and 5xx responses up to 3 attempts in total, with a short backoff (and waits at least as long as a Retry-After header asks). It waits at most 10 seconds in total between attempts, so a share button never hangs on a long Retry-After: the LanderException comes back with retryAfter instead. link_quota_exceeded is not retried. Every attempt carries the same Idempotency-Key, and Lander replays the first successful response for a repeated key, so a retry after a lost response returns the same link instead of creating a second one.

The install ID is sent along, which is how the API applies the per install rate limit.

Next stepsCopy Anchor Link