SDK de Unreal Engine: compatibilidad con enlaces cortos de referencia

Seguir
Avatar
Jared Ornstead
Updated
Documento

Creación de enlaces de referencia cortos

Genere enlaces de referencia cortos y compartibles que permitan la atribución de usuario a usuario y el seguimiento de las instalaciones de aplicaciones a partir de referencias orgánicas.

Requisitos de versión: Esta funcionalidad requiere la versión 2.0.6 o superior del SDK. Los enlaces cortos permanecen activos durante 30 días tras su creación.

Información general

¿Qué son los enlaces cortos?

Los enlaces cortos transforman los enlaces singulares largos y llenos de parámetros en URL compactas y seguras, cómodas para compartir a través de SMS, redes sociales o invitaciones dentro de la aplicación.

Cree enlaces cortos de forma dinámica para que los usuarios puedan compartirlos con sus amigos e invitarles a descargar y utilizar su aplicación. Cada enlace corto realiza un seguimiento del usuario que lo ha recomendado, lo que le permite medir el crecimiento viral y atribuir nuevas instalaciones a promotores específicos.

Requisitos de implementación

Componentes necesarios

Reúna estos elementos antes de crear un enlace corto de referencia:

  • Enlace singular: Un enlace de seguimiento base que dirige a los usuarios a la descarga de su aplicación. Consulte las preguntas frecuentes sobre enlaces singularespara obtener instrucciones de configuración
  • Parámetros dinámicos: Parámetros personalizados opcionales para añadir contexto al enlace. Ver las opciones disponibles en Parámetros del enlace de seguimiento
  • Información del remitente: Nombre e ID del usuario que comparte el enlace para permitir la atribución de nuevas instalaciones al remitente.

Implementación SDK

Registrar delegado de enlace corto

Configure el controlador de devolución de llamada delegado en el constructor de su clase de personaje para recibir los resultados de la creación de enlaces cortos.

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 el controlador delegado en el constructor de su clase antes de crear cualquier enlace corto. La llamada de retorno recibe una URL de enlace corto correcta en el campo "data" o un mensaje de error en el campo "error", pero nunca ambos.

Crear enlace corto de referencia

Genere un enlace corto con parámetros personalizados utilizando el método CreateReferrerShortLink.

Firma del método: 

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

Parámetros:

  • baseLink: La URL original del enlace de seguimiento Singular
  • referrerName: Nombre para mostrar del usuario remitente
  • referrerId: Identificador único del usuario remitente
  • args: TMap que contiene parámetros dinámicos adicionales (puede estar vacío)

Ejemplo de uso

Cree un enlace corto con parámetros personalizados y gestione la respuesta en su callback 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."));
    }
}

Práctica recomendada: Incluya parámetros personalizados significativos que le ayuden a analizar qué canales y campañas de compartición generan más instalaciones. Utilice ID de remitente coherentes que coincidan con su sistema interno de identificación de usuarios para una atribución precisa.

Mejores prácticas de implementación

Gestión de errores

Implemente una sólida gestión de errores en su devolución de llamada para gestionar fallos de red, parámetros no válidos o problemas del servidor.

  • Lógica de reintentos: Implemente un retardo exponencial para errores de red transitorios.
  • Comentarios del usuario: Muestra mensajes de error claros cuando falla la creación de enlaces
  • Opción alternativa: Proporcionar métodos alternativos para compartir (por ejemplo, compartir el enlace singular completo si falla la creación del enlace corto).
  • Validación: Verificación de parámetros antes de llamar a CreateReferrerShortLink para detectar problemas con antelación.

Dependencia de la red: La creación de enlaces cortos requiere una conexión activa a Internet. Maneje siempre los fallos de red con elegancia y proporcione información a los usuarios si falla la creación del enlace.

Seguimiento y análisis

Aproveche la información de los remitentes para crear bucles virales y medir el crecimiento orgánico.

Métricas de crecimiento viral: Utilice ID de remitente coherentes para:

  • Atribuir las nuevas instalaciones a usuarios específicos que las han recomendado.
  • Recompensar a los usuarios por sus referencias
  • Realizar un seguimiento del coeficiente viral y las métricas del factor K
  • Identificar a los defensores de marca más valiosos

Caducidad de enlaces

Planifique el ciclo de vida de los enlaces de 30 días en su estrategia de compartición.

Importante: Los enlaces cortos caducan a los 30 días. Para campañas a largo plazo o funciones de compartición persistentes, genere nuevos enlaces cortos periódicamente o utilice el Enlace Singular completo como alternativa.

Casos de uso comunes

Programas de recomendación dentro de la aplicación

Permite a los usuarios invitar a amigos directamente desde tu aplicación con enlaces de recomendación personalizados.

  • Sistema de recompensas: Realice un seguimiento de las recomendaciones y recompense a los usuarios por las inscripciones exitosas de amigos.
  • Compartir en redes sociales: Integración con la funcionalidad de compartir nativa de la plataforma para SMS, redes sociales y aplicaciones de mensajería.
  • Invitaciones personales: incluya el nombre del recomendante en el mensaje compartido para personalizarlo.
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);
}

Contenido generado por el usuario

Cree enlaces compartibles cuando los usuarios generen contenidos que quieran compartir con otros.

  • Atribución de contenidos: Seguimiento de los contenidos que generan más instalaciones de aplicaciones
  • Reconocimiento de creadores: Atribuya los nuevos usuarios a los creadores de contenidos para la gamificación.
  • Etiquetado de campañas: Añada parámetros dinámicos basados en el tipo o la categoría del contenido
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
    );
}

Invitaciones a eventos

Genere enlaces únicos para invitaciones a eventos que realicen un seguimiento de los asistentes que traen nuevos usuarios.

  • Contexto del evento: Incluya el ID y los detalles del evento en los parámetros del enlace
  • Seguimiento de asistentes: Mida la propagación viral de un evento a otro
  • Efectos de red: Identifique los eventos con las mayores tasas de conversión
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);
}

Compartir en plataformas específicas

Implementación de compartición en Android

Implemente la compartición nativa de Android utilizando JNI para invocar la hoja de compartición del 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

Implementación de compartición iOS

Implemente la compartición nativa de iOS utilizando Objective-C++ para presentar UIActivityViewController.

Nota de implementación: La compartición en iOS requiere una implementación en Objective-C++. Cree un archivo .mm separado para el código específico de la plataforma y exponga los métodos de llamada de C++.