Unreal Engine SDK: integração básica

Adição do SDK ao seu projeto

Para adicionar o SDK do Singular ao seu projeto:

  1. O arquivo do SDK que você baixou contém uma pasta SingularSDK que contém o plug-in do SDK. Copie a pasta SingularSDK para a pasta Plugins de seu aplicativo.
  2. Adicione o SingularSDK como uma dependência à matriz PublicDependencyModuleNames no arquivo Build.cs do seu aplicativo (<YOUR_APP>.Build.cs):

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

Inicialização do SDK

Observação: lembre-se de manter a conformidade com as várias leis de privacidade promulgadas nas regiões em que estiver fazendo negócios, incluindo, entre outras, GDPR, CCPA e COPPA, ao implementar os SDKs da Singular. Para obter mais informações, consulte Práticas de aceitação e exclusão de SDK.

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

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

Método Initialize
Descrição Inicializa o SDK da Singular e envia uma sessão de usuário para os servidores da Singular.
Assinatura
static bool Initialize(FString sdkKey, FString sdkSecret,
       int sessionTimeout = 60,
       FString customUserId = TEXT(""),
       bool skAdNetworkEnabled = false,
       bool manualSkanConversionManagement = false,
       int waitForTrackingAuthorizationWithTimeoutInterval = 0,
       bool oaidCollection = false);
Exemplo de uso
#include "SingularSDKBPLibrary.h"
  
  [...]
  
  USingularSDKBPLibrary::Initialize("SDK KEY", "SDK SECRET");
  

Parâmetros do método

Parâmetro Necessário? Descrição Padrão
sdkKey   Para obter essas chaves, faça login em sua conta da Singular e acesse "Developer Tools > SDK Integration > SDK Keys".  
sdkSecret    

sessionTimeout

  Defina um tempo limite de sessão personalizado (em segundos). 60
customUserId   Envie o ID do usuário para a Singular. Saiba mais abaixo  
waitForTrackingAuthorization WithTimeoutInterval   (iOS) Atrasar o envio de uma sessão/eventos para a Singular até que o usuário concorde ou se recuse a compartilhar os dados do identificador do dispositivo. Saiba mais abaixo False
skAdNetworkEnabled   (iOS) Defina como True para que a Singular rastreie o valor de conversão do usuário. Consulte Introdução à solução SKAdNetwork da Singular para obter mais informações. False
manualSkanConversion Management   (iOS) Defina como True se quiser gerenciar seu valor de conversão SKAdNetwork manualmente (você mesmo o define e atualiza no código). Consulte Introduçãoà solução SKAdNetwork da Singular para obter mais informações. False
oaidCollection   (Android) Defina como true para coletar o OAID do dispositivo. False

Envio do ID de usuário para a Singular (opcional)

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

Observação: Se você usar a solução Cross-Device da Singular, deverá coletar o ID do usuário em todas as plataformas.

  • O ID do usuário pode ser qualquer identificador e não deve expor PII (Informações Pessoais Identificáveis). Por exemplo, você não deve usar o endereço de e-mail, nome de usuário ou número de telefone de um usuário. A Singular recomenda o uso de um valor hash exclusivo apenas para seus dados primários.
  • O valor do ID de usuário passado para a Singular também deve ser o mesmo ID de usuário interno que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
  • A Singular incluirá o ID de usuário nas exportações em nível de usuário, ETL e postbacks de BI interno (se configurado). O ID do usuário é um dado primário, e a Singular não o compartilha com terceiros.
  • O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desfeito usando o método UnsetCustomUserId ou até que o aplicativo seja desinstalado. O fechamento ou a reinicialização do aplicativo não desinstala a ID de usuário.

Para definir a ID de usuário, use o método SetCustomUserId. Para cancelar a definição (por exemplo, se o usuário fizer "logout" da conta), ligue para UnsetCustomUserId.

Observação: se vários usuários usarem um único dispositivo, recomendamos a implementação de um fluxo de logout para definir e cancelar a definição da ID de usuário para cada login e logout.

Se você já souber a ID do usuário quando o aplicativo for aberto, ligue para SetCustomUserId antes de inicializar o SDK da Singular. Dessa forma, a 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 depois que o fluxo de registro for concluído.

Método SetCustomUserId do SingularSDK
Descrição Envia o ID do usuário para o Singular.
Assinatura static void SetCustomUserId(FString customUserId)
Exemplo de uso
USingularSDKBPLibrary::SetCustomUserId("custom_user_id");
Método UnsetCustomUserId do SingularSDK
Descrição Desfaz a definição do ID de usuário que foi enviado para a Singular.
Assinatura static void UnsetCustomUserId()
Exemplo de uso
USingularSDKBPLibrary::UnsetCustomUserId();

Opcional: Mapeamento do dispositivo de ID de usuário personalizado

Importante: esse recurso avançado da Enterprise só está disponível em casos excepcionais. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.

A Singular pode receber dados adicionais de rastreamento de eventos móveis por meio de uma integração de servidor para servidor. Para utilizar esse recurso, você deve mapear o ID do usuário para o identificador de rastreamento de dispositivos móveis da Singular.

Observação: chame esse método o mais rápido possível após a inicialização do SDK da Singular ou assim que tiver o ID do usuário.

Método SetCustomUserId do SingularSDK
Descrição Define o ID de usuário personalizado igual ao login e o mapeia para o identificador de rastreamento da Singular.
Assinatura static void SetDeviceCustomUserId(FString customUserId)
Exemplo de uso
USingularSDKBPLibrary::SetDeviceCustomUserId("custom_user_id");

Opcional: 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 no rastreamento de aplicativos). A Singular se beneficia muito com o IDFA para identificar dispositivos e realizar a atribuição de instalações. Portanto, você deve solicitar o consentimento do usuário antes que o SDK da Singular comece a enviar uma sessão de usuário e eventos de usuário para os servidores da Singular.

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

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

  1. O SDK será inicializado e começará a gravar uma sessão e os eventos do usuário, mas ainda não os envi ará 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 todos os eventos em fila para o servidor Singular (com ou sem o IDFA).
  3. O Singular iniciará então o processo de atribuição, aproveitando o IDFA, se estiver disponível.

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