Pré-requisitos
Conclua estas etapas de pré-requisitos antes de instalar o SDK do Singular Unity para garantir um processo de integração tranquilo.
Pré-requisitos necessários:
- Concluir as etapas de planejamento: Siga o guia em Integração de um SDK Singular: Planejamento e pré-requisitos. Essas etapas são obrigatórias para qualquer integração do SDK Singular.
- Verificar o gerenciador de dependências: Verifique se o seu projeto usa o Google EDM4U (Gerenciador de Dependências Externas para Unity). Saiba mais sobre o Google EDM4U.
-
Atualizando de .unitypackage? Se estiver a migrar do antigo
.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 usando URLs do Git. Siga estas etapas para adicionar o SDK ao seu projeto.
Etapas de instalação
- Abra o Gerenciador de pacotes: Em Unity, navegue até Janela > Gerenciador de pacotes.
- Adicionar pacote do Git: Clique no botão [+]no canto superior esquerdo e selecione "Add package from git URL".
-
Introduza o URL do Git:
-
Para SDK padrão: Introduza
https://github.com/singular-labs/Singular-Unity-SDK.git -
Para o SDK para crianças: Digite
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
Para SDK padrão: Introduza
- Concluir 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 utiliza o External Dependency Manager, tem de transferir e adicionar manualmente as dependências nativas.
Instalação manual de dependências
-
Baixe as dependências: Baixe o arquivo
Plugins.zipapropriado do bucket S3 da Singular:-
SDK padrão (v5.6.0):
Baixar os plug-ins do SDK padrão -
SDK para crianças (v5.6.0):
Baixar os plug-ins do SDK para crianças
-
SDK padrão (v5.6.0):
- Extrair para Assets: Extraia os ficheiros descarregados e mova-os para Assets > Plugins no seu projeto Unity.
-
Configurar a estrutura iOS: Navegue até Assets > Plugins > iOS e selecione
Singular.xcframework. - Incorporar o binário: No painel Inspetor, selecione a opção "Add to Embedded Binaries".
Dicas de configuração do Android
Configure as definições de compilação do Android para garantir a funcionalidade adequada do SDK. O Unity fornece várias formas de personalizar os manifestos do Android e os ficheiros Gradle.
Você pode modificar o AndroidManifest usando um de dois métodos:
Método 1: Manifesto personalizado do Unity
- Navegue até Arquivo > Configurações de compilação > Configurações do jogador > Configurações de publicação.
- Active "Manifesto principal personalizado" na secção Definições de publicação.
-
O Unity gera um arquivo
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 do Android do Unity
Método 2: Android Studio
- Exporte seu projeto do Unity usando Arquivo > Configurações de compilação > Exportar projeto.
- Abra o projeto exportado no Android Studio.
-
Edite o arquivo
AndroidManifest.xmldiretamente no Android Studio.
Método 1: Modelo personalizado do Unity
- Navegue até File > Build Settings > Player Settings > Publishing Settings.
- Active "Custom Gradle Template" (Modelo Gradle Personalizado ) na secção Publishing Settings (Definições de Publicação).
-
O Unity gera um ficheiro
mainTemplate.gradleem Assets/Plugins/Android/mainTemplate.gradle. - Adicione as suas configurações Gradle personalizadas a este ficheiro.
Fonte: Documentação de visão geral do Unity Gradle
Método 2: Android Studio
- Exporte o seu projeto do Unity.
- Abra o projeto no Android Studio.
-
Editar diretamente o ficheiro
build.gradleda aplicação.
Ao criar aplicativos Android no Unity, você pode encontrar erros de "Duplicate class" causados por várSDK do iOSs incluindo as mesmas dependências transitivas. Isso geralmente ocorre com a biblioteca Android Vending Licensing ao usar o AppLovin SDK e o Singular SDK.
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.10.0.aar -> jetified-singular_sdk-12.10.0-runtime (com.singular.sdk:singular_sdk:12.10.0)
Solução 1: Usando o Gerenciador de Dependências Externas (EDM4U)
Se o seu projeto usa o Gerenciador de Dependências Externas para Unity (recomendado), adicione regras de exclusão ao seu arquivo XML de Dependências.
-
Localize o seu ficheiro
*Dependencies.xmlno seu projeto Unity (normalmente emAssets/Editorou numa localização 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.10.0" />
</androidPackages>
</dependencies>
Observação: essa abordagem é mais persistente do que modificar os modelos do Gradle, pois o Android Resolver pode substituir as alterações de modelos personalizados durante a resolução.
Solução 2: usar modelos personalizados do Gradle
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.
- Active "Modelo de Gradle principal personalizado"ou "Modelo de Gradle do lançador 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.10.0'
}
Alternativa: Aplique uma exclusão global adicionando isso após o bloco de dependências:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
Verificar resolução
- Depois de aplicar a exclusão, limpe o seu projeto eliminando as pastas Library/Bee e Temp.
- Reconstrua seu projeto Android no Unity.
- Verifique se o erro de classe duplicada não aparece mais na saída da compilação.
Por que isso funciona: Ambos os SDKs agrupam a mesma biblioteca de licenciamento do Android como uma dependência transitiva. A exclusão diz 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 manutenção ao seu arquivo 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 do iOS
Defina as configurações específicas do iOS para habilitar a atribuição adequada, a vinculação profunda e a funcionalidade de teste.
Depois de criar seu projeto Unity para iOS e antes de criar no Xcode, atualize as dependências do CocoaPods para garantir que você tenha as versões mais recentes do SDK.
cd /path/to/your/ios/project
pod repo update
pod update
Para testar sua integração, registre o IDFV (Identifier for Vendor) para adicionar rapidamente seu dispositivo de teste no Console do Singular SDK.
Adicionar registro de IDFV
- Abra seu projeto Xcode após a compilação 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 seu aplicativo no Xcode.
- Verifique os logs do console do Xcode para a saída do IDFV.
- Copie o IDFV e adicione-o como um dispositivo de teste no Console do Singular SDK.
Habilite Universal Links para links diretos configurando Domínios associados no seu projeto Xcode.
Etapas de configuração do Deep Link
- Adicionar domínio associado: No Xcode, navegue até a guia Assinatura e recursosdo seu aplicativo de destino.
- Habilite a capacidade: Clique em [+] Capacidade e adicione "Domínios associados".
-
Adicionar domínio: Adicione seu domínio de rastreamento Singular no formato:
applinks:yourdomain.sng.link - Configurar ID da equipe: No painel do Singular, navegue até as configurações do seu aplicativo e adicione seu ID da equipe da Apple. Isso permite que o Singular gere e hospede o arquivo Apple App Site Association (AASA) necessário para os Universal Links.
Importante: Sem Domínios Associados e ID de Equipe configurados corretamente, os Universal Links não funcionarão e os usuários não poderão abrir seu aplicativo a partir de links de rastreamento do Singular.
Integrar o SDK
Criar o GameObject SingularSDK
O Singular SDK requer um GameObject na hierarquia da sua cena Unity para funcionar. Você pode adicionar este GameObject usando o prefab fornecido ou criando-o manualmente.
Adicionar Prefab à cena
- No painel Projeto, navegue até Pacotes > Singular > SingularSDK > Prefabs.
- Arraste o prefab SingularSDKObject para o painel Hierarquia.
- O prefab está agora pronto para ser configurado no Inspetor.
Criação manual de GameObject
- No painel Hierarchy (Hierarquia ), clique com o botão direito do rato e selecione Create Empty (Criar vazio).
-
Dê um nome ao GameObject
SingularSDKObject(é necessário um nome exato). - Com o GameObject selecionado, navegue até o painel Inspetor.
- Clique em Adicionar componente.
- Procure por "Singular" e selecione o componente de script Singular SDK.
Crítico: O GameObject deve ter o nome exato SingularSDKObject para que o SDK funcione corretamente.
Configurar as definições do SDK
Configure as credenciais do SDK e as definições de inicialização através do Unity Inspetor. Sua chave de API e segredo são necessários para que o SDK se comunique com os servidores da Singular.
Adicionar credenciais de API
- Selecione SingularSDKObject: Clique no SingularSDKObject na sua Hierarquia.
- Localize as credenciais: Faça login na sua conta Singulare navegue até Developer Tools > Integração do SDK > Chaves do SDK.
- Copiar chaves: Copie a chave SDK e o segredo SDK.
- Cole no Inspetor: No painel Inspetor do Unity, cole as credenciais nos campos Singular API Key e Singular API Secret.
Importante: NÃO use a chave da API de relatório Singular, use apenas a chave e o segredo da API específicos do SDK na página Integração do SDK. O uso de credenciais erradas impedirá que os dados sejam enviados para o Singular.
Verificar sua integração: Após a configuração, teste sua implementação usando o Singular SDK Consolepara garantir que os eventos estão sendo rastreados corretamente.
Configurações padrão do inspetor
O SingularSDKObject vem com padrões sensatos. Entender essas configurações ajuda a personalizar o comportamento do SDK de acordo com os requisitos do seu aplicativo.
- Inicializar ao acordar: Ativado por predefinição. O SDK é inicializado automaticamente quando o GameObject acorda. Desactive esta opção se precisar de atrasar a inicialização devido a consentimento de privacidade ou outros requisitos.
- SKAN ativado: Ativado por padrão (somente iOS). Ativa a atribuição de SKAdNetwork no Modo gerenciado, em que o Singular atualiza automaticamente os valores de conversão com base no modelo de conversão configurado.
- Aguardar autorização de rastreamento: Defina como 0 (desativado). Se o seu aplicativo mostrar o prompt iOS App Tracking Transparency (ATT), defina isso como 300 segundos. Isso atrasa a sessão SDK até que o usuário responda ao prompt ATT, garantindo que o IDFA possa ser capturado se o consentimento for concedido. Deixe em 0 se não estiver a utilizar a ATT.
- Ativar o registo: Ativado por predefinição. Emite 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 definição de Nível de registo (ver abaixo).
-
Nível de registo: Definido como 3 (Info) por predefinição. Controla a verbosidade 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.
- DDL Timeout Sec: Defina como 0 (usa o padrão de 60 segundos). Determina quanto tempo o SDK espera por dados de deep link adiados do servidor. O servidor para de pesquisar após esse tempo limite se nenhum deep link diferido for encontrado.
- Tempo limite da sessão Seg: Definido como 0 (usa o padrão de 60 segundos). Define por quanto tempo o aplicativo pode ficar em segundo plano antes que o SDK crie uma nova sessão ao retornar ao primeiro plano.
- Tempo limite de resolução de link curto: Definido como 0 (usa o padrão de 10 segundos). Protege a experiência do utilizador ao evitar longas esperas se uma ligação curta não puder ser resolvida.
Opções de configuração adicionais
A partir de 18 de junho de 2025: A Medição móvel avançada (AMM)do Meta elimina a necessidade de implementar o Referenciador de instalação do Meta. Se o relatório AMM estiver ativado, não será necessário configurar o Referenciador de instalação do Meta.
Se você precisar oferecer suporte ao método legado de atribuição do Meta Install Referrer, adicione sua ID do aplicativo do Facebook à configuração SingularSDKObject.
Etapas de configuração
- Selecione o SingularSDKObject na hierarquia da cena.
- No painel Inspetor, localize o campo "ID do aplicativo do Facebook".
- Insira sua ID de aplicativo do Facebook (encontre-a no Console do desenvolvedor do Facebook).
Recursos adicionais:
Inicializar o SDK
Conformidade com a privacidade: Ao implementar o Singular SDK, cumpra as leis de privacidade em suas regiões operacionais, incluindo GDPR, CCPA, COPPA e outras. Para obter orientação, consulte Práticas de aceitação e exclusão do SDK.
Inicialize o SDK Singular sempre que seu aplicativo for iniciado. A inicialização do SDK é essencial para todas as funcionalidades de atribuição do Singular e cria uma nova sessão para calcular as métricas de retenção de usuários.
Inicialização automática
Por padrão, o script SingularSDK.cs inicializa automaticamente o SDK quando sua cena é carregada através do método Awake() do Unity. Nenhum código adicional é necessário se a opção Inicializar ao acordarestiver ativada no Inspetor.
Inicialização manual
Se precisar de inicializar o SDK num momento específico (por exemplo, depois de obter o consentimento do utilizador), desactive a inicialização automática e chame o método de inicialização manualmente.
Configuração da inicialização manual
- Selecione o objeto SingularSDKObject na hierarquia da cena.
- No painel Inspetor, desmarque Inicializar ao acordar.
-
Chame
SingularSDK.InitializeSingularSDK()no seu código quando estiver pronto para inicializar.
Método InitializeSingularSDK
Use 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 thread: Sempre chame os métodos do Singular SDK do Unity a partir do mesmo thread usado para outras chamadas da API do Unity. O SDK não é seguro para threads em vários threads.
Configuração avançada
Configurar o tempo limite da sessão
Personalize o tempo que seu aplicativo pode permanecer em segundo plano antes que o SDK crie uma nova sessão quando o aplicativo retornar ao primeiro plano.
Configuração do tempo limite da sessão
O tempo limite de sessão padrão é de 60 segundos. Para alterar esse valor:
- Selecione o objeto SingularSDKObject na hierarquia da cena.
- No painel Inspetor, localize o campo Session Timeout Sec.
- Digite o valor de tempo limite desejado em segundos (por exemplo, 120 para 2 minutos).
- Deixe em 0 para usar o tempo limite padrão de 60 segundos.
Melhores práticas: Considere os padrões de utilização típicos da sua aplicação ao definir o tempo limite da sessão. Os jogos com sessões curtas frequentes podem beneficiar de um tempo limite mais curto, enquanto as aplicações de produtividade podem necessitar de tempos limite mais longos.
Atualizando de .unitypackage para UPM
Se você estiver migrando do método de instalação legado .unitypackage para a abordagem moderna do Unity Package Manager (UPM), siga estas etapas críticas de atualização.
Crítico: Você deve remover manualmente todos os arquivos do Singular SDK existentes antes de instalar o pacote UPM. Se isso não for feito, haverá conflitos e erros de compilação.
Procedimento de atualização
Conclua estas etapas em ordem antes de instalar o SDK por meio do Unity Package Manager:
1. Remover ficheiros de código
Navegue até a pasta /Codedo seu projeto (normalmente Assets/Singular/Code) e exclua todos os scripts C# relacionados ao Singular.
2. Remover dependências do Android
Navegue até /Plugins/Androide remova os seguintes arquivos 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. Remover 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 excluir outros arquivos de plug-in dos quais seu projeto possa depender.
4. Verificar o estado limpo
- Depois de remover os arquivos, feche o Unity completamente.
- Exclua a pasta Library no diretório do seu projeto para forçar o Unity a reimportar os assets.
- Reabra seu projeto Unity.
- Aguarde até que o Unity termine de reimportar os recursos.
- Verifique se não há erros de compilação antes de continuar com a instalação do UPM.
5. Instalar o pacote UPM
Agora você está pronto para instalar o Singular SDK através do Unity Package Manager. Siga as instruções de instalação do UPMna parte superior deste guia.