SDK do Unreal Engine - Suporte a links curtos 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 2.0.6 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

Implementação do SDK

Registar o delegado do link curto

Configure o manipulador de retorno de chamada do delegado no construtor da sua classe de personagem para receber os resultados da criação do link curto.

C++ 
// Add to your character header file (.h)
#include "SingularDelegates.h"

// Declare delegate pointer and callback method
USingularDelegates* SingularDelegates;

UFUNCTION()
void OnSingularShortLinkResolved(const FSingularShortLinkParams& LinkParams);

// In your character implementation file (.cpp)
// Register the delegate in the constructor
AYourCharacter::AYourCharacter()
{
    if (SingularDelegates == nullptr)
    {
        // Create and register the delegate handler
        SingularDelegates = CreateDefaultSubobject<USingularDelegates>(
            TEXT("SingularShortLinksHandler")
        );

        SingularDelegates->OnSingularShortLinksResolved.AddDynamic(
            this, 
            &AYourCharacter::OnSingularShortLinkResolved
        );

        UE_LOG(LogTemp, Log, TEXT("Short link delegate registered"));
    }
}

// Implement the callback method
void AYourCharacter::OnSingularShortLinkResolved(const FSingularShortLinkParams& LinkParams)
{
    // Extract the short link URL or error message
    const FString ShortLinkURL = LinkParams.SingularShortLinksParams["data"];
    const FString ErrorMessage = LinkParams.SingularShortLinksParams["error"];

    if (!ShortLinkURL.IsEmpty())
    {
        // Success - short link was created
        UE_LOG(LogTemp, Log, TEXT("Generated short link: %s"), *ShortLinkURL);

        // Share the link using your preferred sharing method
        ShareLinkWithUser(ShortLinkURL);
    }
    else if (!ErrorMessage.IsEmpty())
    {
        // Error occurred during link creation
        UE_LOG(LogTemp, Error, TEXT("Short link error: %s"), *ErrorMessage);

        // Implement retry logic or show error to user
        HandleShortLinkError(ErrorMessage);
    }
}

Importante: Registe o manipulador delegado no construtor da sua classe antes de criar quaisquer ligações curtas. A chamada de retorno recebe um URL de ligação curta bem sucedido no campo "data" ou uma mensagem de erro no campo "error", mas nunca ambos.

Criar link curto de referência

Gere um link de referência curto com parâmetros personalizados usando o método CreateReferrerShortLink.

Assinatura do método: 

static void CreateReferrerShortLink(
    FString baseLink, 
    FString referrerName, 
    FString referrerId, 
    TMap<FString, FString> args
)

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
  • args: TMap que contém parâmetros dinâmicos adicionais (pode estar vazio)

Exemplo de utilização

Crie um link curto com parâmetros personalizados e trate a resposta na sua chamada de retorno do delegado.

C++ 
// Example: User clicks "Invite Friends" button
void AYourCharacter::OnInviteFriendsClicked()
{
    // Add custom parameters to the link
    TMap<FString, FString> LinkParameters;
    LinkParameters.Add(TEXT("channel"), TEXT("sms"));
    LinkParameters.Add(TEXT("campaign_id"), TEXT("summer_referral_2025"));
    LinkParameters.Add(TEXT("referral_type"), TEXT("friend_invite"));

    // Create the short referrer link
    USingularSDKBPLibrary::CreateReferrerShortLink(
        TEXT("https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fmyapp.com"),  // Base link
        TEXT("John Doe"),                                                         // Referrer name
        TEXT("user_12345"),                                                       // Referrer ID
        LinkParameters                                                            // Custom parameters
    );

    UE_LOG(LogTemp, Log, TEXT("Short link creation requested"));
}

// Handle successful link creation
void AYourCharacter::ShareLinkWithUser(const FString& ShortLinkURL)
{
    // Example: Show share UI with the short link
    FString ShareMessage = FString::Printf(
        TEXT("Join me in this awesome game! %s"), 
        *ShortLinkURL
    );

    // Platform-specific sharing implementation
    #if PLATFORM_ANDROID
        ShareOnAndroid(ShareMessage);
    #elif PLATFORM_IOS
        ShareOnIOS(ShareMessage);
    #else
        // Fallback: Copy to clipboard
        FPlatformApplicationMisc::ClipboardCopy(*ShortLinkURL);
        UE_LOG(LogTemp, Log, TEXT("Link copied to clipboard: %s"), *ShortLinkURL);
    #endif
}

// Handle link creation errors
void AYourCharacter::HandleShortLinkError(const FString& ErrorMessage)
{
    // Log the error
    UE_LOG(LogTemp, Warning, TEXT("Short link failed: %s"), *ErrorMessage);

    // Retry logic for transient errors
    if (ErrorMessage.Contains(TEXT("network")) || ErrorMessage.Contains(TEXT("timeout")))
    {
        // Retry after delay
        FTimerHandle RetryTimer;
        GetWorldTimerManager().SetTimer(
            RetryTimer,
            this,
            &AYourCharacter::OnInviteFriendsClicked,
            2.0f,  // Retry after 2 seconds
            false
        );
    }
    else
    {
        // Show error message to user
        ShowErrorMessage(TEXT("Unable to create share link. Please try again later."));
    }
}

Melhores práticas: Inclua parâmetros personalizados significativos que o ajudem a analisar que canais de partilha e campanhas geram mais instalações. Utilize IDs de referenciador consistentes que correspondam ao seu sistema interno de identificação de utilizadores para uma atribuição precisa.

Práticas recomendadas de implementação

Tratamento de erros

Implemente um tratamento de erros robusto no seu retorno de chamada para gerir falhas de rede, parâmetros inválidos ou problemas de servidor.

  • Lógica de repetição: Implemente um backoff exponencial para erros de rede transitórios
  • Feedback do utilizador: Exiba 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

Dependência de rede: A criação de links curtos requer uma ligação ativa à Internet. Trate sempre as falhas de rede de forma adequada e dê feedback aos utilizadores se a criação da ligação falhar.

Controlo e análise

Aproveite as informações do referenciador para criar loops virais e medir o crescimento orgânico.

Métricas de crescimento viral: Utilize IDs de referenciador consistentes para:

  • 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: Integre-se com a funcionalidade de partilha nativa da plataforma para SMS, redes sociais e aplicações de mensagens
  • Convites pessoais: Inclua o nome do referenciador na mensagem partilhada para personalização
C++ 
// Example: Referral reward system
void AReferralManager::ProcessSuccessfulReferral(const FString& ReferrerId, const FString& NewUserId)
{
    // Track the referral event
    TMap<FString, FString> ReferralData;
    ReferralData.Add(TEXT("referrer_id"), ReferrerId);
    ReferralData.Add(TEXT("new_user_id"), NewUserId);
    ReferralData.Add(TEXT("referral_source"), TEXT("in_app_share"));

    USingularSDKBPLibrary::SendEventWithArgs(TEXT("referral_success"), ReferralData);

    // Award reward to referring user
    AwardReferralReward(ReferrerId);

    UE_LOG(LogTemp, Log, TEXT("Referral processed: %s referred %s"), *ReferrerId, *NewUserId);
}

Conteúdo gerado pelo utilizador

Crie links partilháveis quando os utilizadores geram conteúdos que pretendem 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
C++ 
// Example: Share user-generated content
void AContentManager::ShareUserContent(const FString& ContentId, const FString& CreatorId, const FString& CreatorName)
{
    // Add content-specific parameters
    TMap<FString, FString> ContentParams;
    ContentParams.Add(TEXT("content_id"), ContentId);
    ContentParams.Add(TEXT("content_type"), TEXT("custom_level"));
    ContentParams.Add(TEXT("share_source"), TEXT("ugc_gallery"));

    // Create short link with content creator as referrer
    USingularSDKBPLibrary::CreateReferrerShortLink(
        TEXT("https://mygame.sng.link/Ab3d/cdef?_dl=mygame://content"),
        CreatorName,
        CreatorId,
        ContentParams
    );
}

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
C++ 
// Example: Share event invitation
void AEventManager::InviteToEvent(const FString& EventId, const FString& EventName, const FString& HostId, const FString& HostName)
{
    // Add event-specific parameters
    TMap<FString, FString> EventParams;
    EventParams.Add(TEXT("event_id"), EventId);
    EventParams.Add(TEXT("event_name"), EventName);
    EventParams.Add(TEXT("event_date"), GetEventDateString(EventId));
    EventParams.Add(TEXT("invite_type"), TEXT("host_invite"));

    // Create short link with event host as referrer
    USingularSDKBPLibrary::CreateReferrerShortLink(
        TEXT("https://mygame.sng.link/Ev2nt/wxyz?_dl=mygame://event"),
        HostName,
        HostId,
        EventParams
    );

    UE_LOG(LogTemp, Log, TEXT("Event invitation link created for: %s"), *EventName);
}

Partilha específica da plataforma

Implementação de partilha no Android

Implementar a partilha nativa do Android utilizando JNI para invocar a folha de partilha do sistema.

C++ 
#if PLATFORM_ANDROID
void AYourCharacter::ShareOnAndroid(const FString& Message)
{
    if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
    {
        // Get the Intent class
        jclass IntentClass = FAndroidApplication::FindJavaClass("android/content/Intent");

        // Create Intent with ACTION_SEND
        jfieldID ActionSendField = Env->GetStaticFieldID(IntentClass, "ACTION_SEND", "Ljava/lang/String;");
        jobject ActionSend = Env->GetStaticObjectField(IntentClass, ActionSendField);

        jmethodID IntentConstructor = Env->GetMethodID(IntentClass, "<init>", "()V");
        jobject IntentObject = Env->NewObject(IntentClass, IntentConstructor);

        // Set action and type
        jmethodID SetActionMethod = Env->GetMethodID(IntentClass, "setAction", "(Ljava/lang/String;)Landroid/content/Intent;");
        Env->CallObjectMethod(IntentObject, SetActionMethod, ActionSend);

        jmethodID SetTypeMethod = Env->GetMethodID(IntentClass, "setType", "(Ljava/lang/String;)Landroid/content/Intent;");
        jstring TypeString = Env->NewStringUTF("text/plain");
        Env->CallObjectMethod(IntentObject, SetTypeMethod, TypeString);

        // Add the message
        jmethodID PutExtraMethod = Env->GetMethodID(IntentClass, "putExtra", "(Ljava/lang/String;Ljava/lang/String;)Landroid/content/Intent;");
        jfieldID ExtraTextField = Env->GetStaticFieldID(IntentClass, "EXTRA_TEXT", "Ljava/lang/String;");
        jobject ExtraText = Env->GetStaticObjectField(IntentClass, ExtraTextField);
        jstring MessageString = Env->NewStringUTF(TCHAR_TO_UTF8(*Message));
        Env->CallObjectMethod(IntentObject, PutExtraMethod, ExtraText, MessageString);

        // Create chooser and start activity
        jmethodID CreateChooserMethod = Env->GetStaticMethodID(IntentClass, "createChooser", "(Landroid/content/Intent;Ljava/lang/CharSequence;)Landroid/content/Intent;");
        jstring ChooserTitle = Env->NewStringUTF("Share via");
        jobject ChooserIntent = Env->CallStaticObjectMethod(IntentClass, CreateChooserMethod, IntentObject, ChooserTitle);

        // Start the activity
        FJavaWrapper::CallVoidMethod(Env, FJavaWrapper::GameActivityThis, FJavaWrapper::FindMethod(Env, FJavaWrapper::GameActivityClassID, "startActivity", "(Landroid/content/Intent;)V", false), ChooserIntent);

        // Cleanup
        Env->DeleteLocalRef(IntentClass);
        Env->DeleteLocalRef(ActionSend);
        Env->DeleteLocalRef(IntentObject);
        Env->DeleteLocalRef(TypeString);
        Env->DeleteLocalRef(MessageString);
        Env->DeleteLocalRef(ExtraText);
        Env->DeleteLocalRef(ChooserTitle);
        Env->DeleteLocalRef(ChooserIntent);

        UE_LOG(LogTemp, Log, TEXT("Android share dialog opened"));
    }
}
#endif

Implementação de partilha iOS

Implementar a partilha nativa do iOS utilizando Objective-C++ para apresentar UIActivityViewController.

Nota de implementação: a partilha iOS requer a implementação de Objective-C++. Crie um ficheiro .mm separado para o código específico da plataforma e exponha os métodos chamáveis C++.