SDK de Flutter - Soporte de enlaces cortos de referencia

Documento

Creación de enlaces de referencia cortos

Genere enlaces de referencia cortos y compartibles que permitan la atribución de usuario a usuario y el seguimiento de las instalaciones de aplicaciones a partir de referencias orgánicas.

Requisito de versión: Esta funcionalidad requiere la versión 1.0.7 o superior del SDK. Los enlaces cortos permanecen activos durante 30 días tras su creación.

Información general

¿Qué son los enlaces cortos?

Los enlaces cortos transforman los Singular Links largos y llenos de parámetros en URLs compactas y seguras, cómodas para compartir a través de SMS, redes sociales o invitaciones dentro de la aplicación.

Cree enlaces cortos de forma dinámica para que los usuarios puedan compartirlos con sus amigos e invitarles a descargar y utilizar su aplicación. Cada enlace corto realiza un seguimiento del usuario que lo ha recomendado, lo que le permite medir el crecimiento viral y atribuir nuevas instalaciones a promotores específicos.


Requisitos de implementación

Componentes necesarios

Reúna estos elementos antes de crear un enlace corto de referencia:

  • Enlace singular: Un enlace de seguimiento base que dirige a los usuarios a la descarga de su aplicación. Consulte las preguntas frecuentes sobre enlaces singulares para obtener instrucciones de configuración
  • Parámetros dinámicos: Parámetros personalizados opcionales para añadir contexto al enlace. Ver las opciones disponibles en Parámetros del enlace de seguimiento
  • Información del remitente: Nombre e ID del usuario que comparte el enlace para permitir la atribución de nuevas instalaciones al remitente.

Método SDK

Crear enlace corto de remitente

Genera un enlace de referencia corto con parámetros personalizados y un controlador de devolución de llamada para los estados de éxito y error.

Firmadel 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: La URL original del enlace de seguimiento de Singular
  • referrerName: Nombre para mostrar del usuario remitente
  • referrerId: Identificador único del usuario remitente
  • passthroughParams: Mapa que contiene parámetros dinámicos adicionales (pasar mapa vacío si no hay ninguno)
  • completionHandler: Función de devolución de llamada con parámetros (String? shortLinkURL, String? error)

Para ver la documentación completa del método, consulte la referencia createReferrerShortLink.


Ejemplo de uso básico

Cree un enlace corto con parámetros personalizados e implemente la lógica de compartición en la devolución de llamada de éxito.

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

Implementación avanzada

Implemente un sistema de remisión completo con lógica de reintento, estados de carga y recuperación de portapapeles.

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

Mejores prácticas de implementación

Gestión de errores

Implemente una sólida gestión de errores en la devolución de llamada para gestionar fallos de red, parámetros no válidos o problemas del servidor.

  • Lógica de reintentos: Implementación de reintentos exponenciales para errores de red transitorios.
  • Comentarios del usuario: Visualización de mensajes de error claros cuando falla la creación de enlaces
  • Opción alternativa: Proporcionar métodos alternativos para compartir (por ejemplo, compartir el enlace singular completo si falla la creación del enlace corto).
  • Validación: Verifique los parámetros antes de llamar a createReferrerShortLink para detectar problemas con antelación.

Seguimiento y análisis

Aproveche la información de los remitentes para crear bucles virales y medir el crecimiento orgánico.

Práctica recomendada: Utilice identificadores de referencia coherentes que coincidan con su sistema interno de identificación de usuarios. Esto le permitirá

  • Atribuir las nuevas instalaciones a usuarios de referencia específicos.
  • Recompensar a los usuarios por sus referencias
  • Realizar un seguimiento del coeficiente viral y las métricas del factor K
  • Identificar a sus defensores de marca más valiosos

Caducidad de enlaces

Planifique el ciclo de vida de los enlaces de 30 días en su estrategia de compartición.

Importante: Los enlaces cortos caducan a los 30 días. Para campañas a largo plazo o funciones de compartición persistentes, genere nuevos enlaces cortos periódicamente o utilice el Enlace Singular completo como alternativa.


Casos de uso comunes

Programas de recomendación dentro de la aplicación

Permite a los usuarios invitar a amigos directamente desde tu aplicación con enlaces de recomendación personalizados.

  • Sistema de recompensas: Realice un seguimiento de las recomendaciones y recompense a los usuarios por las inscripciones exitosas de amigos.
  • Compartir en redes sociales: Integración con el paquete share_plus para SMS, WhatsApp, correo electrónico y redes sociales.
  • Invitaciones personales: Incluya el nombre del remitente en el mensaje compartido para personalizarlo.

Contenido generado por el usuario

Cree enlaces compartibles cuando los usuarios generen contenido que quieran compartir con otros.

  • Atribución de contenidos: Rastrea qué contenido impulsa más instalaciones de aplicaciones
  • Reconocimiento de creadores: Atribuya los nuevos usuarios a los creadores de contenidos para la gamificación.
  • Etiquetado de campañas: Añada parámetros dinámicos basados en el tipo o la categoría del contenido

Invitaciones a eventos

Genere enlaces únicos para invitaciones a eventos que realicen un seguimiento de los asistentes que traen nuevos usuarios.

  • Contexto del evento: Incluya el ID y los detalles del evento en los parámetros del enlace
  • Seguimiento de asistentes: Mida la propagación viral de un evento a otro
  • Efectos de red: Identificar los eventos con las tasas de conversión más altas