SDK do Cordova - Suporte de ligações curtas de referência

Seguir
Avatar
Jared Ornstead
Updated
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 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 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 referenciador curto com parâmetros personalizados e um manipulador de retorno de chamada para estados de sucesso e erro.

Assinatura do método: 

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    baseLink: string,
    referrerName: string,
    referrerId: string,
    passthroughParams: Object,
    resultHandler: Object
): 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 houver nenhum)
  • resultHandler: Objeto com as funções de retorno de chamada onSuccesse onError

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 no retorno de chamada de sucesso.

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

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.

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

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 plugins de partilha social Cordova 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údo que querem 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 exclusivos 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

Plug-ins Cordova necessários

Plug-ins recomendados

Instale estes plugins Cordova para melhorar a experiência de partilha de links de referência.

Plug-in de partilha social: 

cordova plugin add cordova-plugin-x-socialsharing

Plug-in da área de transferência: 

cordova plugin add cordova-plugin-clipboard

Nota: Embora estes plug-ins não sejam necessários para gerar ligações curtas, melhoram significativamente a experiência do utilizador ao permitir a partilha nativa e a funcionalidade da área de transferência.