SDK do React Native - Suporte de links curtos de referência

Documento

Criação de links de referência curtos

Gere links de referência curtos e compartilháveis que permitem a atribuição de usuário a usuário e rastreiam instalações de aplicativos a partir de referências orgânicas.

Requisito de versão: Essa funcionalidade requer o SDK versão 3.1.8 ou superior. 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 partilha 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 singularespara 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 createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Record<string, any>,
    completionHandler: (data: string | null, error?: string) => void
): void

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: Objeto que contém parâmetros dinâmicos adicionais (opcional, passe um objeto vazio ou nulo se não existir nenhum)
  • completionHandler: Função de retorno com parâmetros (shortLinkURL: string | null, error?: string)

Para obter a documentação completa do método, consulte a referência createReferrerShortLink.


Exemplo básico de utilização

Crie uma ligação curta com parâmetros personalizados e implemente a lógica de partilha na chamada de retorno de sucesso.

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

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.

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

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: Integrar com a API de partilha nativa React 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 querem partilhar com outros.

  • Atribuição de conteúdo: Acompanhe qual conteúdo gera mais instalações de aplicativos
  • Reconhecimento do criador: Atribua 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