Criação de links de referência curtos
Gerar links de referência curtos e compartilháveis que permitem a atribuição de usuário para usuário e rastrear instalações de aplicativos a partir de referências orgânicas.
Requisito de versão: Esta funcionalidade requer a versão 1.0.7 ou superior do SDK. Os links curtos permanecem ativos por 30 dias após a criação.
Visão geral
O que são links curtos de referência
Os links curtos transformam os Singular Links longos e cheios de parâmetros em URLs compactos e seguros, convenientes para partilhar por SMS, redes sociais ou convites na aplicação.
Crie links curtos de forma dinâmica para que os utilizadores possam partilhá-los com amigos e convidá-los a descarregar e utilizar a sua aplicação. Cada link curto rastreia o utilizador que o referiu, permitindo-lhe medir o crescimento viral e atribuir novas instalações a defensores específicos.
Requisitos de implementação
Componentes necessários
Reúna estes elementos antes de criar um link curto de referência:
- Link único: Um link de rastreamento básico que direciona os usuários para o download do seu aplicativo. Consulte as Perguntas frequentes sobre links singulares para obter instruções de configuração
- Parâmetros dinâmicos: Parâmetros personalizados opcionais para adicionar contexto ao link. Veja as opções disponíveis em Parâmetros do link de rastreamento
- Informações do referenciador: Nome e ID do utilizador que partilha o link para permitir a atribuição de novas instalações ao referenciador
Método SDK
Criar link de referência curto
Gera um link de referência curto com parâmetros personalizados e um manipulador de retorno de chamada para estados de sucesso e erro.
Assinatura do método:
static void createReferrerShortLink(
String baseLink,
String referrerName,
String referrerId,
Map<String, String> passthroughParams,
void Function(String? shortLinkURL, String? error) completionHandler
)
Parâmetros:
- baseLink: O URL original do link de rastreamento Singular
- referrerName: Nome de exibição do usuário de referência
- referrerId: Identificador único para o utilizador de referência
- passthroughParams: Mapa que contém parâmetros dinâmicos adicionais (passar mapa vazio se não houver nenhum)
-
completionHandler: Função de retorno com parâmetros
(String? shortLinkURL, String? error)
Para obter a documentação completa do método, consulte a referência createReferrerShortLink.
Exemplo de uso básico
Criar uma ligação curta com parâmetros personalizados e implementar a lógica de partilha na chamada de retorno de sucesso.
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'),
),
),
);
}
}
Implementação avançada
Implemente um sistema de referência completo com lógica de repetição, estados de carregamento e fallback da área de transferência.
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'),
),
],
],
],
);
}
}
Práticas recomendadas de implementação
Tratamento de erros
Implemente um tratamento de erros robusto na chamada de retorno para gerir falhas de rede, parâmetros inválidos ou problemas de servidor.
- Lógica de repetição: Implementar backoff exponencial para erros de rede transitórios
- Feedback do utilizador: Exibir mensagens de erro claras quando a criação de links falhar
- Opção de retorno: Fornecer métodos de partilha alternativos (por exemplo, partilhar a Ligação Singular completa se a criação de uma ligação curta falhar)
-
Validação: Verificar os parâmetros antes de chamar
createReferrerShortLinkpara detetar problemas antecipadamente
Controlo e análise
Aproveite as informações do referenciador para criar loops virais e medir o crescimento orgânico.
Melhores práticas: Utilize IDs de referenciador consistentes que correspondam ao seu sistema interno de identificação de utilizadores. Isto permite-lhe:
- Atribuir novas instalações a utilizadores de referência específicos
- Recompensar os utilizadores por referências bem sucedidas
- Acompanhar o coeficiente viral e as métricas do fator K
- Identificar os seus defensores de marca mais valiosos
Expiração do link
Planeie o ciclo de vida do link de 30 dias na sua estratégia de partilha.
Importante: As hiperligações curtas expiram ao fim de 30 dias. Para campanhas de longo prazo ou funcionalidades de partilha persistentes, gere periodicamente novos links curtos ou utilize o Link Singular completo como alternativa.
Casos de uso comuns
Programas de indicação no aplicativo
Permita que os utilizadores convidem amigos diretamente da sua aplicação com links de referência personalizados.
- Sistema de recompensa: Acompanhe as referências e recompense os utilizadores por inscrições bem sucedidas de amigos
- Partilha social: Integração com o pacote share_plus para SMS, WhatsApp, e-mail e redes sociais
- Convites pessoais: Inclua o nome do referenciador na mensagem partilhada para personalização
Conteúdo gerado pelo utilizador
Crie links partilháveis quando os utilizadores geram conteúdos que pretendem partilhar com outros.
- Atribuição de conteúdo: Acompanhe qual conteúdo gera mais instalações de aplicativos
- Reconhecimento do criador: Atribuir novos utilizadores a criadores de conteúdos para gamificação
- Marcação de campanhas: Adicionar parâmetros dinâmicos com base no tipo ou categoria de conteúdo
Convites para eventos
Gerar links únicos para convites de eventos que monitorizam os participantes que trazem novos utilizadores.
- Contexto do evento: Incluir ID e detalhes do evento nos parâmetros do link
- Acompanhamento de participantes: Medir a propagação viral de evento para evento
- Efeitos de rede: Identificar eventos com as taxas de conversão mais elevadas