SDK do Unreal Engine - Referência de métodos

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK do Unreal Engine - Referência de métodos

O SDK do Singular Unreal Engine fornece recursos abrangentes de rastreamento e atribuição para aplicativos do Unreal Engine. Esta referência documenta todos os métodos SDK disponíveis com suas assinaturas e exemplos de uso.

CreateReferrerShortLink

Criar link curto de referência

Gera um link curto Singular que pode ser compartilhado para rastrear a atribuição de usuário para usuário e campanhas de crescimento viral.

Assinatura

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

Exemplo de utilização

C++ 
// Create a referrer short link
FString BaseLink = TEXT("https://example.sng.link/abc123");
FString ReferrerName = TEXT("John Doe");
FString ReferrerId = TEXT("user_12345");

TMap<FString, FString> PassthroughParams;
PassthroughParams.Add(TEXT("campaign"), TEXT("summer_promo"));
PassthroughParams.Add(TEXT("level"), TEXT("5"));

USingularSDKBPLibrary::CreateReferrerShortLink(
    BaseLink,
    ReferrerName,
    ReferrerId,
    PassthroughParams
);

GetLimitDataSharing

Obter estado da partilha de dados limitada

Verifica o estado atual da limitação da partilha de dados para conformidade com a privacidade.

Assinatura

C++ 
static bool GetLimitDataSharing();

Exemplo de utilização

C++ 
// Check if data sharing is limited
bool IsLimited = USingularSDKBPLibrary::GetLimitDataSharing();

if (IsLimited)
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is currently limited"));
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is enabled"));
}

Inicializar

Inicializar SDK Singular

Inicializa o Singular SDK com parâmetros de configuração, incluindo credenciais de API, configurações de rastreamento e opções de privacidade.

Assinatura

C++ 
static bool Initialize(
    FString apiKey,
    FString apiSecret,
    int sessionTimeout = 60,
    FString customUserId = TEXT(""),
    bool skAdNetworkEnabled = true,
    bool manualSkanConversionManagement = false,
    int waitForTrackingAuthorizationWithTimeoutInterval = 0,
    bool oaidCollection = false,
    bool enableLogging = false,
    int logLevel = 0,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

Exemplo de uso

C++ 
// Initialize SDK with required parameters
FString ApiKey = TEXT("SDK KEY");
FString ApiSecret = TEXT("YOUR_API_SECRET");

bool Success = USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                    // Session timeout in seconds
    TEXT(""),             // Custom user ID (optional)
    true,                 // SKAdNetwork enabled
    false,                // Manual SKAN conversion management
    0,                    // Wait for tracking authorization timeout
    false,                // OAID collection
    true,                 // Enable logging for debugging
    3,                    // Log level (0-5)
    false,                // Clipboard attribution
    TEXT(""),             // Facebook App ID (optional)
    TEXT("")              // Custom SDID (optional)
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
}
else
{
    UE_LOG(LogTemp, Error, TEXT("Failed to initialize Singular SDK"));
}

IsAllTrackingStopped

Verificar se todo o rastreamento foi interrompido

Determina se todo o rastreamento foi interrompido para conformidade com a privacidade ou preferência do usuário.

Assinatura

C++ 
static bool IsAllTrackingStopped();

Exemplo de utilização

C++ 
// Check tracking status
bool IsTrackingStopped = USingularSDKBPLibrary::IsAllTrackingStopped();

if (IsTrackingStopped)
{
    UE_LOG(LogTemp, Warning, TEXT("Tracking is currently stopped"));
    // Update UI to reflect tracking status
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Tracking is active"));
}

LimitDataSharing

Definir a limitação da partilha de dados

Controlar se os dados do utilizador são partilhados com terceiros para garantir a conformidade da privacidade com regulamentos como o GDPR e a CCPA.

Assinatura

C++ 
static void LimitDataSharing(bool shouldLimitDataSharing);

Exemplo de utilização

C++ 
// Limit data sharing when user opts out
USingularSDKBPLibrary::LimitDataSharing(true);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been limited"));

// Enable data sharing when user opts in
USingularSDKBPLibrary::LimitDataSharing(false);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been enabled"));

ResumeAllTracking

Retomar todo o seguimento

Reativar o seguimento depois de ter sido interrompido, permitindo que o SDK retome a recolha de dados e a comunicação de eventos.

Assinatura

C++ 
static void ResumeAllTracking();

Exemplo de utilização

C++ 
// Resume tracking when user grants consent
USingularSDKBPLibrary::ResumeAllTracking();
UE_LOG(LogTemp, Log, TEXT("Tracking has been resumed"));

SendEvent

Enviar evento personalizado

Rastreie um evento personalizado por nome para medir as acções e o envolvimento do utilizador na sua aplicação.

Assinatura

C++ 
static void SendEvent(FString eventName);

Exemplo de utilização

C++ 
// Track level completion event
USingularSDKBPLibrary::SendEvent(TEXT("level_completed"));

// Track tutorial start
USingularSDKBPLibrary::SendEvent(TEXT("tutorial_start"));

// Track user achievement
USingularSDKBPLibrary::SendEvent(TEXT("achievement_unlocked"));

SendEventWithArgs

Enviar evento personalizado com atributos

Acompanhe um evento personalizado com atributos adicionais para fornecer um contexto detalhado sobre as acções do utilizador.

Assinatura

C++ 
static void SendEventWithArgs(
    FString eventName,
    TMap<FString, FString> args
);

Exemplo de utilização

C++ 
// Track level completion with attributes
TMap<FString, FString> LevelAttributes;
LevelAttributes.Add(TEXT("level_name"), TEXT("Dark Forest"));
LevelAttributes.Add(TEXT("level_number"), TEXT("5"));
LevelAttributes.Add(TEXT("time_spent"), TEXT("245"));
LevelAttributes.Add(TEXT("score"), TEXT("8500"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("level_completed"),
    LevelAttributes
);

// Track item purchase with details
TMap<FString, FString> PurchaseAttributes;
PurchaseAttributes.Add(TEXT("item_id"), TEXT("sword_legendary"));
PurchaseAttributes.Add(TEXT("item_category"), TEXT("weapon"));
PurchaseAttributes.Add(TEXT("item_rarity"), TEXT("legendary"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("item_purchased"),
    PurchaseAttributes
);

SendRevenue

Enviar evento de receita

Rastreie eventos geradores de receita com moeda e valor para medir o desempenho da monetização.

Assinatura

C++ 
static void SendRevenue(
    FString eventName,
    FString currency,
    float amount
);

Exemplo de uso

C++ 
// Track in-app purchase revenue
USingularSDKBPLibrary::SendRevenue(
    TEXT("coin_pack_purchase"),
    TEXT("USD"),
    4.99f
);

// Track subscription purchase
USingularSDKBPLibrary::SendRevenue(
    TEXT("premium_subscription"),
    TEXT("EUR"),
    9.99f
);

SendRevenueWithArgs

Enviar evento de receita com atributos

Acompanhe a receita com atributos adicionais para fornecer informações detalhadas sobre a transação.

Assinatura

C++ 
static void SendRevenueWithArgs(
    FString eventName,
    FString currency,
    float amount,
    TMap<FString, FString> args
);

Exemplo de utilização

C++ 
// Track revenue with transaction details
TMap<FString, FString> TransactionAttributes;
TransactionAttributes.Add(TEXT("product_id"), TEXT("com.game.coins.large"));
TransactionAttributes.Add(TEXT("product_name"), TEXT("Large Coin Pack"));
TransactionAttributes.Add(TEXT("quantity"), TEXT("1"));
TransactionAttributes.Add(TEXT("payment_method"), TEXT("credit_card"));

USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("iap_purchase"),
    TEXT("USD"),
    9.99f,
    TransactionAttributes
);

SetCustomUserId

Definir ID de utilizador personalizado

Atribua um identificador de utilizador personalizado para rastrear utilizadores em dispositivos e sessões utilizando o seu próprio sistema de ID.

Assinatura

C++ 
static void SetCustomUserId(FString customUserId);

Exemplo de utilização

C++ 
// Set custom user ID after login
FString UserId = TEXT("user_abc123xyz");
USingularSDKBPLibrary::SetCustomUserId(UserId);
UE_LOG(LogTemp, Log, TEXT("Custom user ID set: %s"), *UserId);

SetUninstallToken

Definir token de rastreamento de desinstalação

Registe um token de notificação push para permitir o rastreio de desinstalação para medir a retenção de utilizadores.

Assinatura

C++ 
static void SetUninstallToken(FString token);

Exemplo de utilização

C++ 
// Set push notification token for uninstall tracking
FString PushToken = TEXT("abc123def456...");
USingularSDKBPLibrary::SetUninstallToken(PushToken);
UE_LOG(LogTemp, Log, TEXT("Uninstall token registered"));

SkanGetConversionValue

Obter valor de conversão de SKAdNetwork

Recupera o valor de conversão atual de SKAdNetwork para aplicações iOS (apenas iOS).

Assinatura

C++ 
static int SkanGetConversionValue();

Exemplo de utilização

C++ 
// Get current SKAdNetwork conversion value (iOS only)
int ConversionValue = USingularSDKBPLibrary::SkanGetConversionValue();
UE_LOG(LogTemp, Log, TEXT("Current conversion value: %d"), ConversionValue);

SkanRegisterAppForAdNetworkAttribution

Registar a aplicação para atribuição de rede de anúncios

Registar a aplicação com a estrutura SKAdNetwork da Apple para rastreio de atribuição (apenas iOS).

Assinatura

C++ 
static void SkanRegisterAppForAdNetworkAttribution();

Exemplo de utilização

C++ 
// Register for SKAdNetwork attribution (iOS only)
USingularSDKBPLibrary::SkanRegisterAppForAdNetworkAttribution();
UE_LOG(LogTemp, Log, TEXT("Registered for SKAdNetwork attribution"));

SkanUpdateConversionValue

Atualizar o valor de conversão de SKAdNetwork

Atualiza o valor de conversão de SKAdNetwork para refletir o engajamento e a monetização do usuário (somente iOS).

Assinatura

C++ 
static bool SkanUpdateConversionValue(int conversionValue);

Exemplo de utilização

C++ 
// Update conversion value based on user actions (iOS only)
int NewValue = 10;
bool Success = USingularSDKBPLibrary::SkanUpdateConversionValue(NewValue);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated to: %d"), NewValue);
}
else
{
    UE_LOG(LogTemp, Warning, TEXT("Failed to update conversion value"));
}

SkanUpdateConversionValues

Atualizar valores de conversão de SKAdNetwork com valores finos e grossos

Actualiza a SKAdNetwork com o valor de conversão fino, o valor grosseiro e o estado de bloqueio para iOS 16.1+ (apenas iOS).

Assinatura

C++ 
static void SkanUpdateConversionValues(
    int conversionValue,
    int coarse,
    bool lock
);

Exemplo de utilização

C++ 
// Update conversion values with fine and coarse values (iOS 16.1+)
int FineValue = 25;
int CoarseValue = 1;  // 0 = low, 1 = medium, 2 = high
bool Lock = false;    // Set to true to prevent further updates

USingularSDKBPLibrary::SkanUpdateConversionValues(FineValue, CoarseValue, Lock);
UE_LOG(LogTemp, Log, TEXT("Updated conversion values: fine=%d, coarse=%d"), FineValue, CoarseValue);

StopAllTracking

Parar todo o rastreamento

Interrompe completamente todas as actividades de rastreio do SDK para cumprir as preferências de privacidade do utilizador ou os requisitos regulamentares.

Assinatura

C++ 
static void StopAllTracking();

Exemplo de utilização

C++ 
// Stop tracking when user withdraws consent
USingularSDKBPLibrary::StopAllTracking();
UE_LOG(LogTemp, Warning, TEXT("All tracking has been stopped"));

TrackingOptIn

Registar a opção de rastreamento

Notifica a Singular de que o usuário optou explicitamente pelo rastreamento para conformidade com o GDPR.

Assinatura

C++ 
static void TrackingOptIn();

Exemplo de uso

C++ 
// Record user opt-in for GDPR compliance
USingularSDKBPLibrary::TrackingOptIn();
UE_LOG(LogTemp, Log, TEXT("User has opted in to tracking"));

TrackingUnder13

Marcar usuário como menor de 13 anos

Notifica a Singular que o usuário tem menos de 13 anos de idade para conformidade com a COPPA e proteção da privacidade das crianças.

Assinatura

C++ 
static void TrackingUnder13();

Exemplo de uso

C++ 
// Mark user as under 13 for COPPA compliance
USingularSDKBPLibrary::TrackingUnder13();
UE_LOG(LogTemp, Log, TEXT("User marked as under 13 years old"));

UnsetCustomUserId

Remover ID de usuário personalizado

Limpa a ID de usuário personalizada definida anteriormente, normalmente usada durante o logout ou a troca de conta.

Assinatura

C++ 
static void UnsetCustomUserId();

Exemplo de utilização

C++ 
// Clear custom user ID on logout
USingularSDKBPLibrary::UnsetCustomUserId();
UE_LOG(LogTemp, Log, TEXT("Custom user ID has been cleared"));