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.
// 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>
);
}
import React from 'react';
import { View, Button, Alert, Share } from 'react-native';
import { Singular } from 'singular-react-native';
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
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) {
// 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.
// 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>
);
}
import React, { useState } from 'react';
import { View, Button, Alert, ActivityIndicator, Clipboard } from 'react-native';
import { Singular } from 'singular-react-native';
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()
};
Singular.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
Singular.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
createReferrerShortLinkpara 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