创建简短的推荐人链接
生成简短、可共享的推荐人链接,以实现用户到用户归因并跟踪来自有机推荐的应用程序安装。
版本要求:此功能需要 SDK 1.0.7 或更高版本。短链接在创建后 30 天内保持有效。
概述
什么是短推荐人链接
短链接将冗长、充满参数的奇异链接转换为简洁、安全的 URL,便于通过短信、社交媒体或应用程序内的邀请进行分享。
动态创建短链接,以便用户与朋友分享,邀请他们下载和使用您的应用程序。每个短链接都会跟踪推荐用户,使您能够衡量病毒式增长,并将新安装归功于特定的拥护者。
实施要求
所需组件
在创建推荐人短链接之前,请先收集这些元素:
SDK 方法
创建推荐人短链接
生成带有自定义参数和成功与错误状态回调处理程序的短链接。
方法签名:
static void createReferrerShortLink(
String baseLink,
String referrerName,
String referrerId,
Map<String, String> passthroughParams,
void Function(String? shortLinkURL, String? error) completionHandler
)
参数:
- baseLink:原始奇异追踪链接 URL
- referrerName:引用用户的显示名称:引用用户的显示名称
- referrerId:推荐用户的唯一标识符
- passthroughParams: 直通参数:包含附加动态参数的映射(如果没有,则传递空映射
-
completionHandler: 完成处理:带参数的回调函数
(String? shortLinkURL, String? error)
有关完整的方法文档,请参阅createReferrerShortLink 参考资料。
基本使用示例
使用自定义参数创建短链接,并在成功回调中实现共享逻辑。
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:share_plus/share_plus.dart';
class ReferralScreen extends StatelessWidget {
void handleShareReferral() {
// Create custom parameters for the link
final parameters = {
'channel': 'sms',
'campaign_id': 'summer_promo_2025',
'referral_type': 'friend_invite'
};
// 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
parameters, // Custom parameters
(shortLink, error) {
if (error != null) {
// Error occurred during link creation
print('Error creating short link: $error');
_showErrorDialog('Failed to create share link. Please try again.');
} else if (shortLink != null) {
// Success - short link was created
print('Generated short link: $shortLink');
// Share the link using share_plus package
shareLink(shortLink);
}
}
);
}
void shareLink(String shortLink) {
try {
Share.share(
'Join me on this awesome app! $shortLink',
subject: 'App Invitation'
);
print('Link shared successfully');
} catch (error) {
print('Error sharing link: $error');
_showErrorDialog('Failed to share link');
}
}
void _showErrorDialog(String message) {
// Your dialog implementation
print('Error: $message');
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('Referral')),
body: Center(
child: ElevatedButton(
onPressed: handleShareReferral,
child: Text('Share Referral Link'),
),
),
);
}
}
高级实现
通过重试逻辑、加载状态和剪贴板回退实现完整的推荐系统。
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:share_plus/share_plus.dart';
class ReferralManager extends StatefulWidget {
final String userId;
final String userName;
final String baseLink;
const ReferralManager({
Key? key,
required this.userId,
required this.userName,
required this.baseLink,
}) : super(key: key);
@override
_ReferralManagerState createState() => _ReferralManagerState();
}
class _ReferralManagerState extends State<ReferralManager> {
bool _isGenerating = false;
String? _lastGeneratedLink;
Future<String> _generateShortLink({int retryCount = 0}) async {
final parameters = {
'channel': 'in_app',
'campaign_id': 'organic_referral',
'user_tier': 'premium',
'referral_timestamp': DateTime.now().millisecondsSinceEpoch.toString()
};
final completer = Completer<String>();
Singular.createReferrerShortLink(
widget.baseLink,
widget.userName,
widget.userId,
parameters,
(shortLink, error) async {
if (error != null) {
// Retry logic with exponential backoff
if (retryCount < 3) {
final delay = Duration(seconds: (1 << retryCount)); // 1s, 2s, 4s
print('Retrying in ${delay.inSeconds}s... (Attempt ${retryCount + 1}/3)');
await Future.delayed(delay);
try {
final result = await _generateShortLink(retryCount: retryCount + 1);
completer.complete(result);
} catch (e) {
completer.completeError(e);
}
} else {
completer.completeError(Exception(error));
}
} else if (shortLink != null) {
setState(() {
_lastGeneratedLink = shortLink;
});
completer.complete(shortLink);
} else {
completer.completeError(Exception('Unknown error occurred'));
}
}
);
return completer.future;
}
Future<void> _handleShare() async {
setState(() {
_isGenerating = true;
});
try {
final shortLink = await _generateShortLink();
print('Short link generated: $shortLink');
// Attempt to share
await Share.share(
'${widget.userName} invited you to join! $shortLink',
subject: 'App Invitation from ${widget.userName}'
);
// Track share event
Singular.event('referral_link_shared');
print('Link shared successfully');
} catch (error) {
print('Error in share flow: $error');
// Fallback: Copy to clipboard if available
if (_lastGeneratedLink != null) {
await Clipboard.setData(ClipboardData(text: _lastGeneratedLink!));
_showDialog(
'Link Copied',
'Failed to share, but the referral link has been copied to your clipboard!',
);
} else {
_showDialog(
'Error',
'Failed to generate referral link. Please check your connection and try again.',
);
}
} finally {
setState(() {
_isGenerating = false;
});
}
}
Future<void> _copyToClipboard() async {
if (_lastGeneratedLink != null) {
await Clipboard.setData(ClipboardData(text: _lastGeneratedLink!));
_showDialog('Copied!', 'Referral link copied to clipboard');
} else {
_showDialog('No Link', 'Please generate a link first');
}
}
void _showDialog(String title, String message) {
showDialog(
context: context,
builder: (context) => AlertDialog(
title: Text(title),
content: Text(message),
actions: [
TextButton(
onPressed: () => Navigator.of(context).pop(),
child: Text('OK'),
),
],
),
);
}
@override
Widget build(BuildContext context) {
return Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
if (_isGenerating)
CircularProgressIndicator()
else ...[
ElevatedButton(
onPressed: _handleShare,
child: Text('Share Referral Link'),
),
if (_lastGeneratedLink != null) ...[
SizedBox(height: 16),
OutlinedButton(
onPressed: _copyToClipboard,
child: Text('Copy Link'),
),
],
],
],
);
}
}
实施最佳实践
错误处理
在回调中实施强大的错误处理,以管理网络故障、无效参数或服务器问题。
- 重试逻辑:针对瞬时网络错误实施指数回退
- 用户反馈:链接创建失败时显示清晰的错误信息
- 回退选项:提供其他共享方式(例如,如果短链接创建失败,则共享完整的奇异链接)
-
验证:在调用
createReferrerShortLink之前验证参数,以便及早发现问题
跟踪和分析
利用推荐人信息建立病毒循环并衡量有机增长。
最佳实践:使用与内部用户识别系统一致的推荐人 ID。这样您就可以
- 将新安装归属于特定的推荐用户
- 奖励成功推荐的用户
- 跟踪病毒系数和 K 因子指标
- 识别最有价值的品牌拥护者
链接过期
在分享策略中规划 30 天的链接生命周期。
重要:短链接在 30 天后失效。对于长期活动或持续分享功能,请定期生成新的短链接,或使用完整的奇异链接作为备用。
常用案例
应用内推荐计划
让用户可以通过个性化推荐链接直接从应用中邀请朋友。
- 奖励系统:跟踪推荐并奖励成功注册朋友的用户
- 社交分享:与用于短信、WhatsApp、电子邮件和社交媒体的 share_plus 软件包集成
- 个人邀请:在共享信息中包含推荐人姓名,实现个性化
用户生成的内容
当用户生成想要与他人分享的内容时,创建可分享链接。
- 内容归因:跟踪哪些内容推动了最多的应用安装
- 创作者识别:将新用户归属于内容创作者,实现游戏化
- 活动标签:根据内容类型或类别添加动态参数
活动邀请
为活动邀请函生成唯一链接,跟踪哪些与会者带来了新用户。
- 活动背景:在链接参数中包含活动 ID 和详细信息
- 与会者跟踪:衡量活动之间的病毒传播
- 网络效应:识别转换率最高的活动