Instalar o SDK

1. Faça o download e extraia o arquivo SDK.
2. Na pasta raiz Project, crie uma pasta Plugins se ela não existir.
3. Crie uma pasta "SingularSDK" na pasta "Plugins" da sua aplicação.

4. Copie os ficheiros de arquivo extraídos para a pasta "SingularSDK" " na pasta Plugins da sua aplicação.

   

   Sugestão: Para evitar um aviso de versão ao carregar o plug-in, remova a linha "EngineVersion" : "4.25.0" do ficheiro SingularSDK.uplugin.

5. Atualize o "Plugins/SingularSDK/Source/SingularSDK/SingularSDK.Build.cs" com o seguinte:

   • Adicione o using System.IO; à parte superior do ficheiro.
   • Na condição Target.Platform == UnrealTargetPlatform.IOS:

     • Substituir

       PublicAdditionalLibraries.Add("sqlite3.0");
       PublicAdditionalLibraries.Add("z");

       Por isto:

       // System libraries with explicit paths
       string XcodeSDKPath = "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/usr/lib";
       PublicAdditionalLibraries.AddRange(new string[] {
            Path.Combine(XcodeSDKPath, "libsqlite3.tbd"),
            Path.Combine(XcodeSDKPath, "libz.tbd")
       });
       PublicSystemLibraryPaths.Add(XcodeSDKPath);

     • Atualizar

       PublicFrameworks.AddRange(new string[] { 
            "AdSupport", 
            "StoreKit", 
            "SystemConfiguration", 
            "Security"
       });

       Com isto:

       PublicFrameworks.AddRange(new string[] {
            "AdSupport",
            "AppTrackingTransparency",
            "StoreKit",
            "SystemConfiguration",
            "Security",
            "AdServices",
            "WebKit",
            "Singular"
       });

   Exemplo:

   using System.IO;
   // ...
   if (Target.Platform == UnrealTargetPlatform.IOS)
   {    // ...
        // System libraries with explicit paths
        string XcodeSDKPath = "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/usr/lib";
        PublicAdditionalLibraries.AddRange(new string[] {
           Path.Combine(XcodeSDKPath, "libsqlite3.tbd"),
           Path.Combine(XcodeSDKPath, "libz.tbd")
        });
        PublicSystemLibraryPaths.Add(XcodeSDKPath);
        //....
        PublicFrameworks.AddRange(new string[] {
        "AdSupport",
        "AppTrackingTransparency",
        "StoreKit",
        "SystemConfiguration",
        "Security",
        "AdServices",
        "WebKit",
        "Singular"
        });
        //...
   }

6. Feche seu projeto Unreal se ele estiver aberto.
7. Reabra seu projeto. Se for solicitado um prompt de Módulos ausentes, escolha Sim para continuar.
   
8. Ative o SingularSDK Plugin no menu: "Edit>Plugins". Procure por Singular.
   

9. Adicione SingularSDK como uma dependência ao array PublicDependencyModuleNames no ficheiro Build.cs da sua aplicação (Source/ProjectName/<YOUR_APP>.Build.cs):
   

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

KNOWN ISSUE on Build: fatal error: 'Singular/Singular.h' file not found

#

PROBLEMACONHECIDO: Durante a primeira compilação, pode ocorrer o seguinte erro fatal:

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

Para contornar este problema, siga estes passos:

• Extraia o ficheiro 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"

• Abra e modifique o ficheiro SingularConfig.h a partir de "/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular/Singular.framework/Headers"

  • Adicionar a seguinte linha ao topo do ficheiro:

    #pragma clang diagnostic ignored "-Wobjc-property-no-attribute"

    

Inicializar o SDK

O código de inicialização do SDK deve ser chamado sempre que seu aplicativo for aberto. Ele é um pré-requisito para todas as funcionalidades de atribuição do Singular e também envia uma nova sessão para o Singular que é usada para calcular a retenção de usuários. Recomendamos inicializar o SDK o mais cedo possível na execução do seu aplicativo.

Para inicializar o SDK, chame o método USingularSDKBPLibrary::Initialize na classe SingularSDKBPLibrary:

• Um bom lugar para inicializar o SDK é no construtor do modo de jogo, e para imprimir o identificador idfv para iOS também:

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

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

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

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

AMyProject2GameMode::AMyProject2GameMode()
	: Super()
{
	#if PLATFORM_IOS
    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

	USingularSDKBPLibrary::Initialize(
            "SDK KEY",    // API Key from config
            "SDK SECRET", // Secret from config
            60,                // Session timeout (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 (iOS-specific)
        );
	
	// set default pawn class to our Blueprinted character
	static ConstructorHelpers::FClassFinder PlayerPawnClassFinder(TEXT("/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter"));
	DefaultPawnClass = PlayerPawnClassFinder.Class;

}

Parâmetros do método

Definir uma ID de utilizador

Você pode enviar seu ID de usuário interno para a Singular usando um método do SDK da Singular.

• A ID de usuário pode ser qualquer identificador e não deve expor PII (Informações de identificação pessoal). Por exemplo, não deve utilizar o endereço de correio eletrónico, o nome de utilizador ou o número de telefone de um utilizador. A Singular recomenda o uso de um valor com hash exclusivo apenas para seus dados primários.
• O valor da ID de usuário passado para a Singular também deve ser a mesma ID de usuário interna que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
• A Singular incluirá o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID do usuário é um dado primário e a Singular não o compartilha com outras partes.
• O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desmarcado usando o método UnsetCustomUserId ou até que o aplicativo seja desinstalado. Fechar ou reiniciar a aplicação não anula a definição do ID de utilizador.

Para definir o ID de utilizador, utilize o método SetCustomUserId. Para a anular (por exemplo, se o Utilizador "sair" da conta), ligue para UnsetCustomUserId.

Se você já sabe a ID de usuário quando o aplicativo é aberto, chame SetCustomUserId antes de inicializar o SDK do Singular. Dessa forma, o Singular pode ter a ID de usuário desde a primeira sessão. No entanto, a ID de usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame SetCustomUserId após a conclusão do fluxo de registo.

USingularSDKBPLibrary::SetCustomUserId("custom_user_id");

USingularSDKBPLibrary::UnsetCustomUserId();

USingularSDKBPLibrary::SetDeviceCustomUserId("custom_user_id");

Suporte à transparência de rastreamento de aplicativos do iOS 14+

No iOS 14+, os aplicativos precisam solicitar o consentimento do usuário antes de compartilhar dados do usuário, incluindo o uso do valor IDFA do dispositivo (consulte Transparência do rastreamento de aplicativos). A Singular se beneficia muito de ter o IDFA para identificar dispositivos e realizar a atribuição de instalação. Portanto, você deve solicitar o consentimento do usuário antes que o SDK Singular comece a enviar uma sessão de usuário e eventos de usuário para os servidores Singular.

Depois que o SDK envia uma sessão, ele aciona o processo de atribuição de instalação do Singular, com base apenas nos dados que estão disponíveis para o Singular naquele momento.

Para atrasar o envio de uma sessão de usuário e eventos de usuário pelo SDK, inicialize o Singular SDK com o parâmetro waitForTrackingAuthorizationWithTimeoutInterval. Se isso for feito:

1. O SDK será inicializado e começará a gravar uma sessão e eventos de usuário, mas ainda não os enviará para o servidor Singular.
2. Assim que o consentimento do App Tracking Transparency for concedido/negado ou o tempo limite definido terminar, o SDK enviará a sessão e quaisquer eventos em fila para o servidor Singular (com ou sem o IDFA).
3. Em seguida, o Singular iniciará o processo de atribuição, aproveitando o IDFA se ele estiver disponível.

Para obter mais informações, consulte Preparando para o iOS 14.