SDK de Cordova - Soporte de enlaces cortos de referencia

Seguir
Avatar
Jared Ornstead
Updated
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.

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

Información general

¿Qué son los enlaces de referencia cortos?

Los enlaces cortos transforman los enlaces singulares largos y llenos de parámetros en URL 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 singularespara 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: 

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Object,
    resultHandler: Object
): void

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: Objeto que contiene parámetros dinámicos adicionales (opcional, pasar objeto vacío o null si no hay ninguno)
  • resultHandler: Objeto con las funciones de devolución de llamada onSuccessy onError

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.

JavaScript 
document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
  // Create custom parameters for the link
  var parameters = {
    channel: 'sms',
    campaign_id: 'summer_promo_2025',
    referral_type: 'friend_invite'
  };

  // Define result handler
  var resultHandler = {
    onSuccess: function(shortLink) {
      // Success - short link was created
      console.log('Generated short link:', shortLink);
      
      // Share the link using Cordova social sharing plugin
      shareLink(shortLink);
    },
    onError: function(error) {
      // Error occurred during link creation
      console.error('Error creating short link:', error);
      alert('Failed to create share link. Please try again.');
    }
  };

  // Generate the short referrer link
  cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    'https://sample.sng.link/D52wc/cuvk?pcn=test',  // Base Singular Link
    'John Doe',                                      // Referrer name
    'user_12345',                                    // Referrer ID
    parameters,                                      // Custom parameters
    resultHandler                                    // Callback handler
  );
}

function shareLink(shortLink) {
  // Use Cordova social sharing plugin
  if (window.plugins && window.plugins.socialsharing) {
    window.plugins.socialsharing.share(
      'Join me on this awesome app!',
      'App Invitation',
      null,
      shortLink
    );
  } else {
    // Fallback: Copy to clipboard
    copyToClipboard(shortLink);
    alert('Link copied to clipboard: ' + shortLink);
  }
}

function copyToClipboard(text) {
  // Use Cordova clipboard plugin if available
  if (cordova.plugins.clipboard) {
    cordova.plugins.clipboard.copy(text);
  }
}

Implementación avanzada

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

JavaScript 
// Referral Manager Implementation
var ReferralManager = {
  isGenerating: false,
  lastGeneratedLink: null,
  retryCount: 0,
  maxRetries: 3,

  generateShortLink: function(userId, userName, baseLink, callback) {
    var self = this;
    
    if (self.isGenerating) {
      console.log('Link generation already in progress');
      return;
    }

    self.isGenerating = true;
    self.showLoadingIndicator();

    var parameters = {
      channel: 'in_app',
      campaign_id: 'organic_referral',
      user_tier: 'premium',
      referral_timestamp: Date.now().toString()
    };

    var resultHandler = {
      onSuccess: function(shortLink) {
        self.isGenerating = false;
        self.lastGeneratedLink = shortLink;
        self.retryCount = 0;
        self.hideLoadingIndicator();
        
        console.log('Short link generated:', shortLink);
        
        // Track link generation
        cordova.plugins.SingularCordovaSdk.event('referral_link_created');
        
        if (callback) {
          callback(null, shortLink);
        }
      },
      onError: function(error) {
        console.error('Error generating link:', error);
        
        // Retry logic with exponential backoff
        if (self.retryCount < self.maxRetries) {
          var delay = Math.pow(2, self.retryCount) * 1000; // 1s, 2s, 4s
          self.retryCount++;
          
          console.log('Retrying in ' + delay + 'ms... (Attempt ' + 
                     self.retryCount + '/' + self.maxRetries + ')');
          
          setTimeout(function() {
            self.isGenerating = false;
            self.generateShortLink(userId, userName, baseLink, callback);
          }, delay);
        } else {
          // Max retries reached
          self.isGenerating = false;
          self.retryCount = 0;
          self.hideLoadingIndicator();
          
          if (callback) {
            callback(error, null);
          }
        }
      }
    };

    // Generate the link
    cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      baseLink,
      userName,
      userId,
      parameters,
      resultHandler
    );
  },

  shareReferralLink: function(userId, userName, baseLink) {
    var self = this;
    
    self.generateShortLink(userId, userName, baseLink, function(error, shortLink) {
      if (error) {
        // Use fallback if available
        if (self.lastGeneratedLink) {
          self.copyToClipboard(self.lastGeneratedLink);
          alert('Failed to generate new link, but your previous referral link has been copied to clipboard!');
        } else {
          alert('Failed to generate referral link. Please check your connection and try again.');
        }
      } else if (shortLink) {
        // Success - share the link
        self.shareViaPlugin(shortLink);
      }
    });
  },

  shareViaPlugin: function(shortLink) {
    var self = this;
    
    if (window.plugins && window.plugins.socialsharing) {
      window.plugins.socialsharing.shareWithOptions(
        {
          message: 'Join me on this awesome app!',
          url: shortLink,
          chooserTitle: 'Share via'
        },
        function(result) {
          console.log('Share completed:', result.completed);
          if (result.completed) {
            // Track successful share
            cordova.plugins.SingularCordovaSdk.event('referral_link_shared');
          }
        },
        function(error) {
          console.error('Share error:', error);
          // Fallback to clipboard
          self.copyToClipboard(shortLink);
          alert('Link copied to clipboard!');
        }
      );
    } else {
      // No share plugin available - copy to clipboard
      self.copyToClipboard(shortLink);
      alert('Referral link copied to clipboard: ' + shortLink);
    }
  },

  copyToClipboard: function(text) {
    if (cordova.plugins && cordova.plugins.clipboard) {
      cordova.plugins.clipboard.copy(text);
      console.log('Copied to clipboard:', text);
    }
  },

  showLoadingIndicator: function() {
    // Show loading UI
    var loader = document.getElementById('loading-indicator');
    if (loader) {
      loader.style.display = 'block';
    }
  },

  hideLoadingIndicator: function() {
    // Hide loading UI
    var loader = document.getElementById('loading-indicator');
    if (loader) {
      loader.style.display = 'none';
    }
  }
};

// Usage example
document.addEventListener('deviceready', function() {
  // Setup share button
  document.getElementById('share-button').addEventListener('click', function() {
    var userId = 'user_12345';
    var userName = 'John Doe';
    var baseLink = 'https://sample.sng.link/D52wc/cuvk?pcn=test';
    
    ReferralManager.shareReferralLink(userId, userName, baseLink);
  });

  // Setup copy button
  document.getElementById('copy-button').addEventListener('click', function() {
    if (ReferralManager.lastGeneratedLink) {
      ReferralManager.copyToClipboard(ReferralManager.lastGeneratedLink);
      alert('Link copied to clipboard!');
    } else {
      alert('Please generate a link first');
    }
  });
}, false);

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 los plugins de compartición social de Cordova 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

Plugins Cordova necesarios

Plugins recomendados

Instale estos plugins de Cordova para mejorar la experiencia de compartir enlaces de referencia.

Plugin de compartición social: 

cordova plugin add cordova-plugin-x-socialsharing

Plugin de portapapeles: 

cordova plugin add cordova-plugin-clipboard

Nota: Aunque estos plugins no son necesarios para generar enlaces cortos, mejoran significativamente la experiencia del usuario al habilitar la función nativa de compartir y el portapapeles.