SDK do Unreal Engine - Suporte a links curtos de referência

Seguir
Avatar
Jared Ornstead
Updated

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 compartilhar por SMS, redes sociais ou convites no aplicativo.

Crie links curtos de forma dinâmica para que os usuários possam compartilhá-los com amigos e convidá-los a baixar e utilizar o seu aplicativo. Cada link curto rastreia o usuário 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 usuário que compartilha o link para permitir a atribuição de novas instalações ao referenciador

Implementação do SDK

Registrar 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: Registre o manipulador delegado no construtor da sua classe antes de criar quaisquer links curtos. A chamada de retorno recebe um URL de link curto 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 usuário 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 compartilhamento e campanhas geram mais instalações. Utilize IDs de referenciador consistentes que correspondam ao seu sistema interno de identificação de usuários 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 gerenciar 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 usuário: Exiba mensagens de erro claras quando a criação de links falhar
  • Opção de retorno: Fornecer métodos de compartilhamento alternativos (por exemplo, compartilhar a Singular Link completa se a criação de um link curto falhar)
  • Validação: Verificar os parâmetros antes de chamar CreateReferrerShortLink para detectar problemas antecipadamente

Dependência de rede: A criação de links curtos requer uma conexão ativa com a Internet. Trate sempre as falhas de rede de forma adequada e dê feedback aos usuários se a criação do link falhar.

Controle 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 usuários de referência específicos
  • Recompensar os usuários 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 compartilhamento.

Importante: Os links curtos expiram ao fim de 30 dias. Para campanhas de longo prazo ou funcionalidades de compartilhamento 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 usuários convidem amigos diretamente do seu aplicativo com links de referência personalizados.

  • Sistema de recompensa: Acompanhe as referências e recompense os usuários por inscrições bem sucedidas de amigos
  • Compartilhamento social: Integre-se com a funcionalidade de compartilhamento nativa da plataforma para SMS, redes sociais e aplicativos de mensagens
  • Convites pessoais: Inclua o nome do referenciador na mensagem compartilhada 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 usuário

Crie links compartilháveis quando os usuários geram conteúdos que pretendem compartilhar com outros.

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

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

Compartilhamento específico da plataforma

Implementação de compartilhamento no Android

Implementar o compartilhamento nativo do Android utilizando JNI para invocar a folha de compartilhamento 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 compartilhamento iOS

Implementar o compartilhamento nativo do iOS utilizando Objective-C++ para apresentar UIActivityViewController.

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