Flutter SDK - 支持推荐人短链接

文档

创建简短的推荐人链接

生成简短、可共享的推荐人链接,以实现用户到用户归因并跟踪来自有机推荐的应用程序安装。

版本要求:此功能需要 SDK 1.0.7 或更高版本。短链接在创建后 30 天内保持有效。

概述

什么是短推荐人链接

短链接将冗长、充满参数的奇异链接转换为简洁、安全的 URL,便于通过短信、社交媒体或应用程序内的邀请进行分享。

动态创建短链接,以便用户与朋友分享,邀请他们下载和使用您的应用程序。每个短链接都会跟踪推荐用户,使您能够衡量病毒式增长,并将新安装归功于特定的拥护者。


实施要求

所需组件

在创建推荐人短链接之前,请先收集这些元素:

  • 单一链接:引导用户下载应用程序的基本跟踪链接。有关设置说明,请参阅奇异链接常见问题
  • 动态参数:用于为链接添加上下文的可选自定义参数。查看跟踪链接参数中的可用选项
  • 推荐人信息:分享链接的用户的姓名和 ID,以便将新安装归因于推荐人

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 参考资料


基本使用示例

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

Dart
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'),
        ),
      ),
    );
  }
}

高级实现

通过重试逻辑、加载状态和剪贴板回退实现完整的推荐系统。

Dart
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 和详细信息
  • 与会者跟踪:衡量活动之间的病毒传播
  • 网络效应:识别转换率最高的活动