SDK de React Native - 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.

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:

static createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Record<string, any>,
    completionHandler: (data: string | null, error?: string) => void
): 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)
  • completionHandler: Función de devolución de llamada con parámetros (shortLinkURL: string | null, error?: string)

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.

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import React from 'react';
import { View, Button, Alert, Share } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function ReferralScreen() {
  const handleShareReferral = () => {
    // Create custom parameters for the link
    const parameters = {
      channel: 'sms',
      campaign_id: 'summer_promo_2025',
      referral_type: 'friend_invite'
    };

    // Generate the short referrer link
    NativeSingular.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) {
          // Error occurred during link creation
          console.error('Error creating short link:', error);
          Alert.alert('Error', 'Failed to create share link. Please try again.');
        } else if (shortLink) {
          // Success - short link was created
          console.log('Generated short link:', shortLink);

          // Share the link using React Native's Share API
          shareLink(shortLink);
        }
      }
    );
  };

  const shareLink = async (shortLink) => {
    try {
      const result = await Share.share({
        message: `Join me on this awesome app! ${shortLink}`,
        url: shortLink // iOS only
      });

      if (result.action === Share.sharedAction) {
        if (result.activityType) {
          console.log('Shared with activity type:', result.activityType);
        } else {
          console.log('Link shared successfully');
        }
      } else if (result.action === Share.dismissedAction) {
        console.log('Share dismissed');
      }
    } catch (error) {
      console.error('Error sharing link:', error);
      Alert.alert('Error', 'Failed to share link');
    }
  };

  return (
    <View>
      <Button title="Share Referral Link" onPress={handleShareReferral} />
    </View>
  );
}

Implementación avanzada

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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useState } from 'react';
import { View, Button, Alert, ActivityIndicator } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import Clipboard from '@react-native-clipboard/clipboard';

export default function ReferralManager({ userId, userName, baseLink }) {
  const [isGenerating, setIsGenerating] = useState(false);
  const [lastGeneratedLink, setLastGeneratedLink] = useState(null);

  const generateShortLink = (retryCount = 0) => {
    return new Promise((resolve, reject) => {
      const parameters = {
        channel: 'in_app',
        campaign_id: 'organic_referral',
        user_tier: 'premium',
        referral_timestamp: Date.now().toString()
      };

      NativeSingular.createReferrerShortLink(
        baseLink,
        userName,
        userId,
        parameters,
        (shortLink, error) => {
          if (error) {
            // Retry logic with exponential backoff
            if (retryCount < 3) {
              const delay = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
              console.log(`Retrying in ${delay}ms... (Attempt ${retryCount + 1}/3)`);

              setTimeout(() => {
                generateShortLink(retryCount + 1)
                  .then(resolve)
                  .catch(reject);
              }, delay);
            } else {
              reject(new Error(error));
            }
          } else if (shortLink) {
            setLastGeneratedLink(shortLink);
            resolve(shortLink);
          } else {
            reject(new Error('Unknown error occurred'));
          }
        }
      );
    });
  };

  const handleShare = async () => {
    setIsGenerating(true);

    try {
      const shortLink = await generateShortLink();
      console.log('Short link generated:', shortLink);

      // Attempt to share
      const { Share } = require('react-native');
      const result = await Share.share({
        message: `${userName} invited you to join! ${shortLink}`,
        url: shortLink
      });

      if (result.action === Share.sharedAction) {
        console.log('Link shared successfully');
        // Track share event
        NativeSingular.event('referral_link_shared');
      }
    } catch (error) {
      console.error('Error in share flow:', error);

      // Fallback: Copy to clipboard if available
      if (lastGeneratedLink) {
        Clipboard.setString(lastGeneratedLink);
        Alert.alert(
          'Link Copied',
          'Failed to share, but the referral link has been copied to your clipboard!',
          [{ text: 'OK' }]
        );
      } else {
        Alert.alert(
          'Error',
          'Failed to generate referral link. Please check your connection and try again.',
          [{ text: 'OK' }]
        );
      }
    } finally {
      setIsGenerating(false);
    }
  };

  const copyToClipboard = () => {
    if (lastGeneratedLink) {
      Clipboard.setString(lastGeneratedLink);
      Alert.alert('Copied!', 'Referral link copied to clipboard');
    } else {
      Alert.alert('No Link', 'Please generate a link first');
    }
  };

  return (
    <View>
      {isGenerating ? (
        <ActivityIndicator size="large" />
      ) : (
        <>
          <Button 
            title="Share Referral Link" 
            onPress={handleShare}
            disabled={isGenerating}
          />
          {lastGeneratedLink && (
            <Button 
              title="Copy Link" 
              onPress={copyToClipboard}
            />
          )}
        </>
      )}
    </View>
  );
}

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 React Native Share API para SMS, WhatsApp, correo electrónico y redes sociales.
  • Invitaciones personales: incluye el nombre del recomendante 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: Identifique los eventos con las mayores tasas de conversión