Instalação

Instale o SDK do Singular para Unreal Engine adicionando o plugin do SDK à pasta Plugins do seu projeto e habilitando-o no seu projeto do Unreal Engine.

Instalar o SDK

Siga estas etapas para integrar o SDK do Singular ao seu projeto do Unreal Engine.

1. Baixe e extraia o arquivo compactado do SDK a partir do link fornecido acima.
2. Na pasta raiz do Project, crie uma pasta caso ela ainda não exista. Plugins
3. Crie uma pasta "SingularSDK" dentro da pasta "Plugins" do seu aplicativo.

4. Copie os arquivos extraídos para a pasta "SingularSDK" dentro da pasta Plugins do seu aplicativo.

   

5. Feche o seu projeto do Unreal caso ele esteja aberto.
6. Reabra o seu projeto. Se aparecer o aviso Missing Modules, escolha Yes para continuar.
   
7. Habilite o SingularSDK Plugin pelo menu "Edit>Plugins". Pesquise por Singular.
   

8. Adicione SingularSDK como dependência ao array PublicDependencyModuleNames no arquivo Build.cs do seu aplicativo (Source/ProjectName/<YOUR_APP>.Build.cs).

   C++

   PublicDependencyModuleNames.AddRange(new string[] { 
       "Core", 
       "CoreUObject",
       "Engine", 
       "InputCore", 
       "SingularSDK" 
   });

Problema de instalação conhecido

Durante a primeira compilação, você pode encontrar um erro fatal relacionado ao arquivo de cabeçalho do framework do Singular.

PROBLEMA CONHECIDO: Durante a primeira compilação você pode enfrentar o seguinte erro fatal:

Plugins/SingularSDK/Source/SingularSDK/Private/SingularSDKBPLibrary.cpp:14:9: fatal error: 'Singular/Singular.h' file not found

Para contornar esse problema, siga estas etapas:

• Extraia o arquivo Singular.framework.zip de "Plugins/SingularSDK/Source/ThirdParty/iOS".
• Mova a pasta Singular.framework para "/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular"

Inicialização do SDK

Inicialize o SDK Singular sempre que seu aplicativo for iniciado para permitir o rastreamento de atribuição, o gerenciamento de sessão e o relatório de eventos.

Sobre o SDID

O Singular Device ID (SDID) é um identificador em nível de dispositivo que a Singular gera e gerencia. Em uma integração híbrida, em que este SDK é executado no seu app e o seu servidor também envia eventos pela API Server-to-Server (S2S), enviar o mesmo SDID nesses eventos do lado do servidor os vincula ao mesmo dispositivo que o SDK está rastreando. Isso permite que a Singular atribua a atividade do SDK e do S2S a um único dispositivo sem depender de identificadores de publicidade específicos da plataforma.

Por que inicializar o SDK

A inicialização do SDK é um pré-requisito para todas as funcionalidades de atribuição do Singular. Ela cria uma nova sessãoenviada ao Singular para calcular as métricas de retenção de usuários.

Método Inicializar

USingularSDKBPLibrary::Initialize

Chame o método Initialize para iniciar o SDK Singular e enviar uma sessão de usuário para os servidores Singular.

Assinatura do método

static bool Initialize(
    FString sdkKey, 
    FString sdkSecret,
    int sessionTimeout = 60,
    FString customUserId = TEXT(""),
    bool skAdNetworkEnabled = true,
    bool manualSkanConversionManagement = false,
    int waitForTrackingAuthorizationWithTimeoutInterval = 0,
    bool oaidCollection = false,
    bool enableLogging = false,
    int logLevel = 3,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

Exemplo de implementação

Inicialize o SDK em seu construtor de modo de jogo com credenciais de API e opções de configuração.

// Copyright Epic Games, Inc. All Rights Reserved.

#include "MyProject2GameMode.h"
#include "MyProject2Character.h"
#include "UObject/ConstructorHelpers.h"
#include "SingularSDKBPLibrary.h"
#include "SingularDelegates.h"

#if PLATFORM_IOS
#include "IOS/IOSPlatformMisc.h"
#import <UIKit/UIKit.h>
#endif

AMyProject2GameMode::AMyProject2GameMode()
    : Super()
{
#if PLATFORM_IOS
    // Log IDFV for iOS testing
    NSString *idfv = [[UIDevice currentDevice] identifierForVendor].UUIDString;
    if (idfv)
    {
        FString IDFVString = FString(idfv);
        UE_LOG(LogTemp, Log, TEXT("IDFV: %s"), *IDFVString);
    }
    else
    {
        UE_LOG(LogTemp, Warning, TEXT("Failed to retrieve IDFV"));
    }
#endif

    // Register the SDID accessor handler before initialization to confirm the SDK
    // received the SDID (SDID is enabled by default for new accounts)
    USingularDelegates* SingularDelegates = CreateDefaultSubobject<USingularDelegates>(TEXT("SingularSdidAccessorHandler"));
    SingularDelegates->OnSingularSdidReceived.AddDynamic(this, &AMyProject2GameMode::OnSingularSdidReceived);
    SingularDelegates->OnSingularDidSetSdid.AddDynamic(this, &AMyProject2GameMode::OnSingularDidSetSdid);

    // Initialize Singular SDK
    bool Success = USingularSDKBPLibrary::Initialize(
        "YOUR_SDK_KEY",        // API Key from Singular dashboard
        "YOUR_SDK_SECRET",      // Secret from Singular dashboard
        60,                      // Session timeout in seconds
        TEXT(""),               // Custom user ID (optional)
        true,                    // Enable SKAdNetwork for iOS
        false,                   // Manual SKAdNetwork conversion management
        30,                      // Wait 30 seconds for ATT prompt
        false,                   // Disable OAID collection
        true,                    // Enable logging for debugging
        3,                       // Log level (0-5, higher = more verbose)
        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"));
    }

    // Set default pawn class
    static ConstructorHelpers::FClassFinder<APawn> PlayerPawnClassFinder(
        TEXT("/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter")
    );
    DefaultPawnClass = PlayerPawnClassFinder.Class;
}

void AMyProject2GameMode::OnSingularSdidReceived(const FString result)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDID received: %s"), *result);
}

void AMyProject2GameMode::OnSingularDidSetSdid(const FString result)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDID set: %s"), *result);
}

Adicione as declarações de handler correspondentes ao cabeçalho do seu game mode (por exemplo, AMyProject2GameMode.h):

UFUNCTION()
void OnSingularSdidReceived(const FString result);

UFUNCTION()
void OnSingularDidSetSdid(const FString result);

Parâmetros de configuração

Parâmetros necessários

Esses parâmetros são necessários para a inicialização do SDK. Obtenha suas credenciais no painel de controle do Singular.

• sdkKey: Sua chave do SDK do Singular em"Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK" na sua conta do Singular
• sdkSecret: Seu segredo do SDK do Singular a partir do mesmo local na sua conta do Singular

Parâmetros opcionais

Personalize o comportamento do SDK com esses parâmetros de configuração opcionais.

• sessionTimeout (Padrão: 60): Define um tempo limite de sessão personalizado em segundos. Após este período de inatividade, é criada uma nova sessão quando o utilizador regressa à aplicação.
• customUserId (Predefinição: vazio): Definir um identificador de utilizador personalizado na inicialização. Saiba mais sobre IDs de utilizador personalizados.
• skAdNetworkEnabled (Padrão: true, somente iOS): Habilita o suporte de SKAdNetwork para atribuição de iOS. Consulte Introdução à solução SKAdNetwork da Singular.
• manualSkanConversionManagement (Padrão: false, somente iOS): Defina como true para gerenciar manualmente os valores de conversão da SKAdNetwork em vez de deixar que a Singular os manipule automaticamente.
• waitForTrackingAuthorizationWithTimeoutInterval(Padrão: 0, somente iOS): Atrasa o envio de sessões/eventos para a Singular até que o usuário responda ao prompt ATT (App Tracking Transparency) ou até que o tempo limite termine. Saiba mais sobre o suporte a ATT.
• oaidCollection (Padrão: false, somente Android): Defina como true para recolher o OAID (Open Anonymous Device Identifier) do dispositivo em dispositivos Android.
• enableLogging (Padrão: false): Habilita o registro de depuração do SDK para solução de problemas. Deve ser desativado em compilações de produção.
• logLevel (Padrão: 3): Somente Android. Usa os níveis do android.util.Log, de 2 Verbose a 7 Assert; um número menor é mais detalhado.
• clipboardAttribution (Predefinição: false, apenas iOS): Ativar a leitura da área de transferência para atribuição de ligações universais.
• facebookAppId (Padrão: vazio): Defina seu ID do aplicativo do Facebook para integração de atribuição do Facebook.
• customSdid (Padrão: vazio): Definir um ID de dispositivo único personalizado em vez de usar o identificador gerado automaticamente.