Android SDK - 支持推荐人短链接

关注
Avatar
Jared Ornstead
Updated

创建推荐人短链接

生成可共享的推荐人短链接，启用用户对用户的归因， 并追踪来自自然推荐的应用安装。

版本要求： 此功能需要 SDK 版本 12.1.1 或更高。短链接在创建后 30 天内 保持活动状态。

概述

什么是推荐人短链接

短链接将冗长、参数繁多的 Singular Link 转换为紧凑、 安全的 URL，便于通过 SMS、社交媒体或应用内邀请进行共享。

动态创建短链接，以便用户可以与朋友共享， 邀请他们下载并使用您的应用。每个短链接都会追踪 推荐人用户，使您能够测量病毒式增长并将新安装归因于 特定的推荐者。

实施要求

必需组件

在创建推荐人短链接之前，请收集以下要素：

  • Singular Link： 一个基础追踪链接，将 用户引导至您的应用下载。设置说明请参见 Singular Links FAQ
  • 动态参数： 用于为链接添加上下文的 可选自定义参数。可在 追踪链接参数 中查看可用选项
  • 推荐人信息： 共享链接的用户的姓名和 ID， 以便将新安装归因于推荐人

SDK 方法

createReferrerShortLink

使用自定义参数以及成功和错误状态的回调处理程序， 生成推荐人短链接。

方法签名： 

Singular.createReferrerShortLink(
    String baseLink,
    String referrerName,
    String referrerId,
    JSONObject parameters,
    ShortLinkHandler handler
)

参数：

  • baseLink： 原始 Singular 追踪链接 URL
  • referrerName： 推荐用户的显示名称
  • referrerId： 推荐用户的唯一标识符
  • parameters： 包含附加动态参数的 JSONObject （可选）
  • handler： 带有 onSuccess 和 onError 方法的回调接口（必需）

ShortLinkHandler 定义了两个抽象 方法（onSuccess(String link) 和 onError(String error)），因此它不是 Kotlin SAM 接口。始终将其实现为定义了两个方法的对象表达式 （Kotlin）或匿名类（Java）。 null handler 或未初始化的 SDK 会导致调用被静默丢弃 — 请在调用此方法之前验证 Singular.init() 已运行。

onError 在验证失败时（例如， 无效的基础链接），可能在任何网络请求之前同步触发。 在您的回调中实现防御性的 null 检查， 以便它可以在调用线程或后台线程上运行。

使用示例

使用自定义参数创建短链接，并在成功回调中实现共享 逻辑。

Kotlin Java 
import org.json.JSONObject
import org.json.JSONException

// Create custom parameters for the link
val params = JSONObject()
try {
    params.put("channel", "sms")
    params.put("campaign_id", "summer_promo_2025")
    params.put("referral_type", "friend_invite")
} catch (e: JSONException) {
    Log.e("ShortLink", "Error creating parameters: ${e.message}")
}

// Generate the short referrer link
Singular.createReferrerShortLink(
    "https://sample.sng.link/D52wc/cuvk?pcn=test",  // Base Singular Link
    "John Doe",                                      // Referrer name
    "user_12345",                                    // Referrer ID
    params,                                          // Custom parameters
    object : ShortLinkHandler {
        override fun onSuccess(shortLinkURL: String) {
            Log.d("ShortLink", "Generated: $shortLinkURL")

            // Share the short link via Android Share Sheet
            val shareIntent = Intent(Intent.ACTION_SEND).apply {
                type = "text/plain"
                putExtra(Intent.EXTRA_TEXT,
                    "Join me on this awesome app! $shortLinkURL")
            }
            startActivity(Intent.createChooser(shareIntent, "Share via"))
        }

        override fun onError(error: String) {
            Log.e("ShortLink", "Error creating link: $error")

            // Handle error - retry or show user feedback
            Toast.makeText(
                applicationContext,
                "Failed to create share link. Please try again.",
                Toast.LENGTH_SHORT
            ).show()
        }
    }
)

实施最佳实践

错误处理

在 onError 回调中实现健壮的错误处理，以管理网络故障、无效参数或服务器问题。

  • 重试逻辑： 对短暂的网络错误实现指数 退避
  • 用户反馈： 当链接创建失败时显示 清晰的错误消息
  • 备用选项： 提供替代的共享方法 （例如，如果短链接创建失败，则共享完整的 Singular Link）
  • 验证： 在调用 createReferrerShortLink 之前验证参数，以便尽早发现问题

追踪和分析

利用推荐人信息构建病毒式循环并衡量自然增长。

最佳实践： 使用与您的内部用户识别系统 匹配的一致推荐人 ID。这使您能够：

  • 将新安装归因于特定的推荐人用户
  • 奖励成功推荐的用户
  • 追踪病毒系数和 K-factor 指标
  • 识别您最有价值的品牌倡导者

链接过期

在您的共享策略中规划 30 天的链接生命周期。

重要： 短链接在 30 天后过期。对于 长期活动或持续的共享功能，请定期生成新的短 链接，或使用完整的 Singular Link 作为备用。

常见使用案例

应用内推荐计划

让用户能够使用个性化的推荐链接直接从您的应用中邀请朋友。

  • 奖励系统： 追踪推荐并对成功邀请朋友注册的用户 给予奖励
  • 社交共享： 与 Android Share Sheet 集成， 支持 SMS、WhatsApp、电子邮件和社交媒体
  • 个人邀请： 在共享消息中包含推荐人姓名 以实现个性化

用户生成内容

当用户生成想要与他人共享的内容时，创建可共享的链接。

  • 内容归因： 追踪哪些内容驱动了 最多的应用安装
  • 创作者认可： 将新用户归因于内容 创作者以实现游戏化
  • 活动标记： 根据内容类型或类别添加 动态参数

活动邀请

生成独特的链接用于活动邀请，追踪哪些参与者 带来了新用户。

  • 活动上下文： 在链接参数中包含活动 ID 和详细 信息
  • 参与者追踪： 衡量活动之间的病毒式 传播
  • 网络效应： 识别转化率最高的活动