Pré-requisitos
Conclua estes passos pré-requisitos antes de instalar o SDK Singular para Unity, para garantir um processo de integração sem problemas.
Pré-requisitos obrigatórios:
- Conclua as etapas de planeamento: Siga o guia em Integrar um SDK da Singular: Planeamento e Pré-requisitos. Estas etapas são obrigatórias para qualquer integração do SDK da Singular.
- Verifique o gestor de dependências: Verifique se o seu projeto utiliza o Google EDM4U (External Dependency Manager for Unity). Saiba mais sobre o Google EDM4U.
-
A atualizar a partir do .unitypackage? Se estiver a migrar do pacote .
.unitypackagepara o novo pacoteUPM, leia as instruções de atualização antes de prosseguir.
Instalação
Instalação através do Unity Package Manager (UPM)
O Singular SDK do Unity é instalado através do Unity Package Manager utilizando Git URLs. Siga estes passos para adicionar o SDK ao seu projeto.
Passos de instalação
- Abrir o Gestor de Pacotes: No Unity, navegue até Janela > Gestor de Pacotes.
- Adicionar pacote a partir do Git: Clique no botão [+] no canto superior esquerdo e selecione «Adicionar pacote a partir de URL do Git».
-
Introduza o URL do Git:
-
Para o SDK padrão: introduza
https://github.com/singular-labs/Singular-Unity-SDK.git -
Para o SDK Kids: Introduza
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
Para o SDK padrão: introduza
- Conclua a instalação: Clique em "Adicionar" para instalar o pacote SDK.
Não está a utilizar o Google EDM4U? Se o seu projeto não utilizar o Gestor de Dependências Externas, deve descarregar e adicionar manualmente as dependências nativas.
Instalação manual de dependências
-
Transferir dependências: Transfira o ficheiro
Plugins.zipadequado do bucket S3 da Singular:-
SDK Padrão (v5.7.0):
Descarregar Plug-ins do SDK Padrão -
SDK Kids (v5.6.0):
Descarregar Plugins do SDK Kids
-
SDK Padrão (v5.7.0):
- Extrair para Assets: Extraia os ficheiros descarregados e mova-os para Assets > Plugins no seu projeto Unity .
-
Configurar a estrutura do iOS: Navegue até
Assets > Plugins > iOS e selecione
Singular.xcframework. - Incorporar binário: No painel Inspector, marque a opção "Add to Embedded Binaries".
Dicas de configuração para Android
Configure as suas definições de compilação do Android para garantir o funcionamento adequado do SDK. O Unity oferece várias formas de personalizar manifestos do Android e ficheiros Gradle .
Pode modificar o AndroidManifest utilizando um dos dois métodos:
Método 1: Manifesto personalizado do Unity
- Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
- Ative «Manifesto principal personalizado» na secção Configurações de publicação.
-
O Unity gera um ficheiro
AndroidManifest.xmlpadrão em Assets/Plugins/Android/AndroidManifest.xml. - Edite este ficheiro para adicionar as permissões e configurações necessárias.
Fonte: Documentação do Manifesto Android do Unity
Método 2: Android Studio
- Exporte o seu projeto do Unity usando Arquivo > Configurações de Compilação > Exportar Projeto.
- Abra o projeto exportado no Android Studio.
-
Edite o ficheiro `
AndroidManifest.xml` diretamente no Android Studio.
Método 1: Modelo personalizado do Unity
- Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
- Ative "Modelo Gradle personalizado" na secção Configurações de publicação.
-
O Unity gera um ficheiro `
mainTemplate.gradle` em Assets/Plugins/Android/mainTemplate.gradle. - Adicione as suas configurações Gradle personalizadas a este ficheiro.
Fonte: Documentação de visão geral do Gradle do Unity
Método 2: Android Studio
- Exporte o seu projeto do Unity.
- Abra o projeto no Android Studio.
-
Edite diretamente o ficheiro `
build.gradle` da aplicação.
Ao criar aplicações Android no Unity, poderá deparar-se com erros de «classe duplicada» causados por várSDK do iOSs que incluem as mesmas dependências transitivas. Isto ocorre frequentemente com a biblioteca Android Vending Licensing quando se utilizam tanto o SDK da AppLovin como o SDK da Singular.
Exemplo de erro:
Duplicate class com.android.vending.licensing.ILicensingService found in modules
applovin-sdk-13.5.0.aar -> jetified-applovin-sdk-13.5.0-runtime (com.applovin:applovin-sdk:13.5.0)
and singular_sdk-12.11.0.aar -> jetified-singular_sdk-12.11.0-runtime (com.singular.sdk:singular_sdk:12.11.0)
Solução 1: Utilizar o External Dependency Manager (EDM4U)
Se o seu projeto utiliza o External Dependency Manager para Unity (recomendado), adicione regras de exclusão ao seu ficheiro XML de dependências.
-
Localize o seu ficheiro «
*Dependencies.xml» no seu projeto Unity (normalmente em «Assets/Editor» ou num local semelhante). - Adicione uma regra de exclusão a uma das dependências do SDK:
<dependencies>
<androidPackages>
<androidPackage spec="com.applovin:applovin-sdk:13.5.0">
<androidSdkPackageIds>
<exclude group="com.android.vending" module="licensing"/>
</androidSdkPackageIds>
</androidPackage>
<androidPackage spec="com.singular.sdk:singular_sdk:12.11.0" />
</androidPackages>
</dependencies>
Nota: Esta abordagem é mais persistente do que modificar modelos Gradle, uma vez que o Android Resolver pode substituir alterações personalizadas nos modelos durante a resolução.
Solução 2: Utilizar modelos Gradle personalizados
Se não estiver a utilizar o EDM4U, aplique regras de exclusão diretamente nos seus ficheiros de configuração do Gradle.
- Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
- Ative "Modelo Gradle Principal Personalizado" ou "Modelo Gradle do Iniciador Personalizado".
-
Abra
Assets/Plugins/Android/mainTemplate.gradle(oulauncherTemplate.gradle). - Adicione a regra de exclusão ao seu bloco de dependências:
dependencies {
implementation('com.applovin:applovin-sdk:13.5.0') {
exclude group: 'com.android.vending', module: 'licensing'
}
implementation 'com.singular.sdk:singular_sdk:12.11.0'
}
Alternativa: Aplique uma exclusão global adicionando isto após o seu bloco de dependências:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
Verifique a resolução
- Após aplicar a exclusão, limpe o seu projeto eliminando as pastas Library/Bee e Temp .
- Recompile o seu projeto Android no Unity.
- Verifique se o erro de classe duplicada já não aparece na saída da compilação.
Por que isto funciona: Ambos os SDKs incluem a mesma biblioteca de licenciamento Android como uma dependência transitiva. A exclusão indica ao Gradle para usar apenas uma cópia, resolvendo o conflito.
Se o seu projeto usa o ProGuard para ofuscação de código, adicione as
seguintes
regras de retenção ao seu ficheiro ` proguard-unity.txt ` para
evitar
que o SDK Singular seja removido:
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }
Dicas de configuração para iOS
Configure as definições específicas do iOS para ativar a atribuição correta, o deep linking e a funcionalidade de teste.
Após compilar o seu projeto Unity para iOS e antes de compilar no Xcode, atualize as suas dependências do CocoaPods para garantir que tem as versões mais recentes do SDK.
cd /path/to/your/ios/project
pod repo update
pod update
Para testar a sua integração, registe o IDFV (Identificador do Fornecedor) para adicionar rapidamente o seu dispositivo de teste na Consola do SDK da Singular.
Adicionar registo do IDFV
- Abra o seu projeto Xcode após a compilação a partir do Unity.
- Navegue até Classes > UnityAppController.mm.
-
Encontre o método `
applicationDidBecomeActive`. - Adicione o seguinte código para registar o IDFV:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- Compile e execute a sua aplicação no Xcode.
- Verifique os registos da consola do Xcode para ver a saída do IDFV.
- Copie o IDFV e adicione-o como um dispositivo de teste na Consola do SDK da Singular.
Ative os Universal Links para deep linking, configurando os Domínios Associados no seu projeto do Xcode.
Passos para a configuração de links profundos
- Adicionar domínio associado: No Xcode, navegue até ao separador «Signing &Capabilities» do seu alvo de aplicação.
- Ativar funcionalidade: Clique em [+] Capability e adicione "Associated Domains".
-
Adicionar domínio: Adicione o seu domínio de rastreamento
Singular
no formato:
applinks:yourdomain.sng.link - Configurar ID da equipa: No painel de controlo da Singular, navegue até às definições da sua aplicação e adicione o seu ID da equipa da Apple. Isto permite que a Singular gere e hospede o ficheiro Apple App Site Association (AASA) necessário para os Universal Links.
Importante: Sem os Domínios Associados e o ID da Equipa devidamente configurados, os Universal Links não funcionarão e os utilizadores não conseguirão abrir a sua aplicação a partir dos links de rastreamento da Singular.
Se estiver a utilizar outros SDKs que registam o UnityAppController (como o Firebase, Adjust ou AppsFlyer), poderá encontrar conflitos que impedem o Singular de inicializar corretamente. No Unity, apenas uma classe pode registar-se como UnityAppController de cada vez.
Para resolver este conflito:
-
Abra o
ficheiro
SingularSwizzledAppController.mno seu projeto Xcode. - Descomente todo o código neste ficheiro.
-
Abra o
SingularAppDelegate.me verifique se a seguinte linha não está comentada:IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)
Isto permite que o Singular funcione em conjunto com outros SDKs utilizando o método swizzling em vez de criar uma subclasse do UnityAppController.
Integre o SDK
Crie o GameObject SingularSDK
O SDK do Singular requer um GameObject na hierarquia da sua cena do Unity para funcionar. Pode adicionar este GameObject utilizando o prefab fornecido ou criando-o manualmente.
Adicionar o prefab à cena
- No painel Project, navegue até Packages > Singular > SingularSDK > Prefabs.
- Arraste o prefab SingularSDKObject para o seu painel Hierarchy.
- O prefab está agora pronto para ser configurado no Inspector.
Criação manual de GameObject
- No painel Hierarchy, clique com o botão direito do rato e selecione Create Empty.
-
Dê ao GameObject o nome «
SingularSDKObject» (é necessário o nome exato). - Com o GameObject selecionado, navegue até ao painel Inspector.
- Clique em Add Component.
- Procure por "Singular" e selecione o componente de script Singular SDK.
Importante: O GameObject deve ser nomeado
exatamente
SingularSDKObject para que o SDK funcione
corretamente.
Configurar as definições do SDK
Configure as suas credenciais do SDK e definições de inicialização através do Unity Inspector. A sua Chave API e Segredo são necessários para que o SDK comunique com os servidores da Singular.
Adicionar credenciais da API
- Selecione SingularSDKObject: Clique no SingularSDKObject na sua Hierarquia.
- Localize as credenciais: inicie sessão na sua con ta Singular e navegue até Ferramentas de Desenvolvedor > Integração do SDK > Chaves do SDK.
- Copiar chaves: Copie a sua Chave SDK e o Segredo SDK.
- Cole no Inspector: No painel Inspector do Unity, cole as credenciais nos campos Chave API Singular e Segredo API Singular.
Importante: NÃO utilize a Chave da API de Relatórios da Singular . Utilize apenas a Chave da API e o Segredo específicos do SDK, disponíveis na página Integração do SDK . A utilização de credenciais erradas impedirá que os dados sejam enviados para a Singular.
Verifique a sua integração: Após a configuração, teste a sua implementação utilizando a Consola do SDK da Singular para garantir que os eventos estão a ser monitorizados corretamente.
Definições padrão do Inspector
O SingularSDKObject vem com predefinições sensatas. Compreender estas configurações ajuda-o a personalizar o comportamento do SDK de acordo com os requisitos da sua aplicação.
- Inicializar ao acordar: Ativado por padrão. O SDK inicializa-se automaticamente quando o GameObject acorda. Desative esta opção se precisar de adiar a inicialização para consentimento de privacidade ou outros requisitos.
- SKAN ativado: Ativado por predefinição (apenas iOS ). Ativa a atribuição SKAdNetwork no Modo Gerido, onde o Singular atualiza automaticamente os valores de conversão com base no seu modelo de conversão configurado.
- Aguardar autorização de rastreamento: Defina para 0 (desativado). Se a sua aplicação apresentar o aviso de Transparência de Rastreamento de Aplicações iOS (ATT), defina isto para 300 segundos. Isto atrasa a sessão do SDK até que o utilizador responda ao aviso ATT, garantindo que o IDFA possa ser capturado se o consentimento for concedido. Deixe em 0 se não estiver a utilizar o ATT.
- Ativar registo: Ativado por predefinição. Gera registos de depuração do SDK para ajudar na integração e na resolução de problemas. Deve ser desativado em compilações de produção. Funciona com a configuração Nível de registo (ver abaixo).
-
Nível de registo: Definido para 3 (Informação) por predefinição.
Controla
o nível de detalhe do registo. Números mais baixos produzem registos mais detalhados
:
// Based on Android Logger log levels public enum LogLevel { Verbose = 2, // Most verbose Debug = 3, Info = 4, // Default Warn = 5, Error = 6, Assert = 7 // Least verbose }Nota: Os registos detalhados estão disponíveis principalmente no Android.
- Tempo de espera DDL (segundos): Definido como 0 (usa o padrão de 60 segundos ). Determina quanto tempo o SDK espera pelos dados de deep link diferidos do servidor. O servidor interrompe a pesquisa após esse tempo de espera se nenhum deep link diferido for encontrado.
- Tempo de espera da sessão (segundos): Defina como 0 (usa o padrão de 60 segundos). Define por quanto tempo a aplicação pode ficar em segundo plano antes de o SDK criar uma nova sessão ao retornar ao primeiro plano.
- Tempo de espera para resolução de link curto: Defina como 0 (usa o padrão de 10 segundos). Tempo máximo de espera para a resolução do link curto . Protege a experiência do utilizador, evitando longas esperas caso um link curto não possa ser resolvido.
Opções de configuração adicionais
A partir de 18 de junho de 2025: o Advanced Mobile Measurement (AMM) da Meta elimina a necessidade de implementar o Meta Install Referrer. Se os relatórios do AMM estiverem ativados, não é necessário configurar o Meta Install Referrer.
Se precisar de suportar o método de atribuição Meta Install Referrer legado, adicione o seu ID da aplicação do Facebook à configuração do SingularSDKObject .
Passos de configuração
- Selecione o SingularSDKObject na sua hierarquia de cenas.
- No painel Inspector, localize o campo "Facebook App ID" .
- Introduza o seu ID da aplicação do Facebook (encontra-o na sua Consola de Desenvolvedor do Facebook).
Recursos adicionais:
Inicializar o SDK
Conformidade com a privacidade: Ao implementar o SDK da Singular, cumpra as leis de privacidade nas regiões onde opera, incluindo o RGPD, a CCPA, a COPPA e outras. Para obter orientações, consulte Práticas de aceitação e recusa do SDK.
Inicialize o SDK da Singular sempre que a sua aplicação for iniciada. A inicialização do SDK é essencial para todas as funcionalidades de atribuição da Singular e cria uma nova sessão para o cálculo das métricas de retenção de utilizadores.
Inicialização automática
Por predefinição, o script SingularSDK.cs inicializa automaticamente
o SDK quando a sua cena é carregada através do método Awake() do Unity.
Não é necessário código adicional se a opção Initialize OnAwake
estiver ativada no Inspector.
Inicialização manual
Se precisar de inicializar o SDK num momento específico (por exemplo, após obter o consentimento do utilizador), desative a inicialização automática e chame o método de inicialização manualmente.
Configuração da inicialização manual
- Selecione o SingularSDKObject na hierarquia da sua cena.
- No painel do Inspector, desmarque Initialize On Awake.
-
Chame `
SingularSDK.InitializeSingularSDK()` no seu código quando estiver pronto para inicializar.
Método InitializeSingularSDK
Utilize este método para inicializar manualmente o SDK quando a inicialização automática estiver desativada.
using UnityEngine;
using Singular;
public class GameInitializer : MonoBehaviour
{
void Start()
{
// Perform any required setup (e.g., consent management)
CheckUserConsent();
// Initialize Singular SDK after consent is obtained
// SDK Key and Secret are configured on the SingularSDKObject
SingularSDK.InitializeSingularSDK();
}
void CheckUserConsent()
{
// Your consent logic here
}
}
Segurança de threads: Chame sempre os métodos do Singular SDK do Unity a partir da mesma thread utilizada para outras chamadas da API do Unity. O SDK não é seguro para threads em várias threads.
Configuração avançada
Necessário para a medição de conversões integrada do Google Ads para iOS
Se a sua aplicação executa campanhas do Google Ads direcionadas a utilizadores do iOS 14.5 ou superior, são necessários passos adicionais de configuração do SDK para suportar a Medição de Conversão Integrada (ICM) do iOS. Isto inclui:
- Integrar o SDK de Medição no Dispositivo (ODM) do Google
- Atualização para o SDK Singular para iOS v12.8.1+ (ou v5.5.0+ para Unity, v1.8.0+ para Flutter/Cordova, v3.9.0+ para React Native)
- Adicionar o sinalizador do ligador «
-ObjC» e ativar «enableOdmWithTimeoutInterval» em «SingularConfig»
Nota: A ativação de enableOdmWithTimeoutInterval atrasa a inicialização do SDK e pode adiar os callbacks de deep link. Conclua esta configuração durante a implementação inicial do SDK para evitar trabalho adicional.
Consulte os requisitos técnicos completos do iOS ICM
Configurar o tempo limite da sessão
Personalize o tempo que a sua aplicação pode permanecer em segundo plano antes de o SDK criar uma nova sessão quando a aplicação regressar ao primeiro plano.
Configuração do tempo limite da sessão
O tempo de espera padrão da sessão é de 60 segundos. Para alterar este valor:
- Selecione o SingularSDKObject na hierarquia da sua cena.
- No painel Inspector, localize o campo Session Timeout Sec.
- Introduza o valor de tempo limite pretendido em segundos (por exemplo, 120 para 2 minutos).
- Deixe em 0 para utilizar o tempo de espera padrão de 60 segundos.
Prática recomendada: tenha em conta os padrões de utilização típicos da sua aplicação ao definir o tempo limite da sessão. Jogos com sessões curtas e frequentes podem beneficiar de um tempo limite mais curto, enquanto as aplicações de produtividade podem necessitar de tempos limite mais longos.
Atualização de .unitypackage para UPM
Se estiver a migrar do método de instalação antigo do .unitypackage para a abordagem moderna do Unity Package Manager (UPM), siga estes
passos críticos de atualização.
Crítico: Deve remover manualmente todos os ficheiros existentes do Singular SDK antes de instalar o pacote UPM . Se não o fizer, isso causará conflitos e erros de compilação .
Procedimento de atualização
Conclua estes passos por ordem antes de instalar o SDK através do Unity Package Manager:
1. Remova os ficheiros de código
Navegue até à pasta /Code
do seu projeto (normalmente Assets/Singular/Code)
e elimine todos os scripts C# relacionados com o Singular.
2. Remova as dependências do Android
Navegue até /Plugins/Android e remova os seguintes ficheiros Singular:
-
Todos os ficheiros
.aarcom "singular" no nome -
Todos os ficheiros
.jarcom "singular" no nome -
singular-sdk.aar -
install-referrer-*.aar -
singular-unitybridge.aar
3. Remova as dependências do iOS
Navegue até /Plugins/iOS e remova os seguintes ficheiros Singular:
-
Todos os ficheiros de cabeçalho
.h(por exemplo,SingularSDK.h) -
Todos os ficheiros de implementação
.m(por exemplo,SingularUnityBridge.m) -
Singular.xcframeworkpasta
Importante: Remova apenas os ficheiros específicos do Singular. Tenha cuidado para não eliminar outros ficheiros de plugins dos quais o seu projeto possa depender.
4. Verifique se o estado está limpo
- Após remover os ficheiros, feche o Unity completamente.
- Elimine a pasta Library no diretório do seu projeto para forçar o Unity a reimportar os recursos.
- Reabra o seu projeto do Unity.
- Aguarde até que o Unity termine de reimportar os recursos.
- Verifique se não existem erros de compilação antes de prosseguir com a instalação do UPM.
5. Instalar o pacote UPM
Agora está pronto para instalar o Singular SDK através do Unity Package Manager. Siga as instruções de instalação do UPM no início deste guia.