SDK do Flutter - Suporte de links curtos de referência

Documento

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.

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

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.

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

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 createReferrerShortLink para 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