SDK do Unity - Integração básica

Documento

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:


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

  1. Abrir o Gestor de Pacotes: No Unity, navegue até Janela > Gestor de Pacotes.
  2. Adicionar pacote a partir do Git: Clique no botão [+] no canto superior esquerdo e selecione «Adicionar pacote a partir de URL do Git».
  3. 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
  4. 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

  1. Transferir dependências: Transfira o ficheiro Plugins.zip adequado do bucket S3 da Singular:
  2. Extrair para Assets: Extraia os ficheiros descarregados e mova-os para Assets > Plugins no seu projeto Unity .
  3. Configurar a estrutura do iOS: Navegue até Assets > Plugins > iOS e selecione Singular.xcframework .
  4. 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 .

Como atualizar o AndroidManifest.xml
#

Pode modificar o AndroidManifest utilizando um dos dois métodos:

Método 1: Manifesto personalizado do Unity

  1. Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
  2. Ative «Manifesto principal personalizado» na secção Configurações de publicação.
  3. O Unity gera um ficheiro AndroidManifest.xml padrão em Assets/Plugins/Android/AndroidManifest.xml.
  4. 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

  1. Exporte o seu projeto do Unity usando Arquivo > Configurações de Compilação > Exportar Projeto.
  2. Abra o projeto exportado no Android Studio.
  3. Edite o ficheiro ` AndroidManifest.xml ` diretamente no Android Studio.
Como atualizar os ficheiros de compilação do Gradle
#

Método 1: Modelo personalizado do Unity

  1. Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
  2. Ative "Modelo Gradle personalizado" na secção Configurações de publicação.
  3. O Unity gera um ficheiro ` mainTemplate.gradle ` em Assets/Plugins/Android/mainTemplate.gradle.
  4. 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

  1. Exporte o seu projeto do Unity.
  2. Abra o projeto no Android Studio.
  3. Edite diretamente o ficheiro ` build.gradle ` da aplicação.
Resolução de erros de classes duplicadas
#

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.

  1. Localize o seu ficheiro « *Dependencies.xml » no seu projeto Unity (normalmente em « Assets/Editor» ou num local semelhante).
  2. Adicione uma regra de exclusão a uma das dependências do SDK:
XML
<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.

  1. Navegue até Arquivo > Configurações de Compilação > Configurações do Player > Configurações de Publicação.
  2. Ative "Modelo Gradle Principal Personalizado" ou "Modelo Gradle do Iniciador Personalizado".
  3. Abra Assets/Plugins/Android/mainTemplate.gradle (ou launcherTemplate.gradle).
  4. Adicione a regra de exclusão ao seu bloco de dependências:
Gradle
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:

Gradle
configurations.all {
    exclude group: 'com.android.vending', module: 'licensing'
}

Verifique a resolução

  1. Após aplicar a exclusão, limpe o seu projeto eliminando as pastas Library/Bee e Temp .
  2. Recompile o seu projeto Android no Unity.
  3. 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.

Configuração do ProGuard
#

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:

proguard-unity.txt
-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.

Atualize as dependências do CocoaPods
#

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.

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
Registar o IDFV para testes
#

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

  1. Abra o seu projeto Xcode após a compilação a partir do Unity.
  2. Navegue até Classes > UnityAppController.mm.
  3. Encontre o método ` applicationDidBecomeActive `.
  4. Adicione o seguinte código para registar o IDFV:
Objective-C
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
  1. Compile e execute a sua aplicação no Xcode.
  2. Verifique os registos da consola do Xcode para ver a saída do IDFV.
  3. Copie o IDFV e adicione-o como um dispositivo de teste na Consola do SDK da Singular.
Configurar o suporte a Deep Link
#

Ative os Universal Links para deep linking, configurando os Domínios Associados no seu projeto do Xcode.

  1. Adicionar domínio associado: No Xcode, navegue até ao separador «Signing &Capabilities» do seu alvo de aplicação.
  2. Ativar funcionalidade: Clique em [+] Capability e adicione "Associated Domains".
  3. Adicionar domínio: Adicione o seu domínio de rastreamento Singular no formato: applinks:yourdomain.sng.link
  4. 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.

⚠️ Importante: Resolução de conflitos do UnityAppController
#

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:

  1. Abra o ficheiro SingularSwizzledAppController.m no seu projeto Xcode.
  2. Descomente todo o código neste ficheiro.
  3. Abra o SingularAppDelegate.m e 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.

Método 1: Utilizar o prefab do Singular (Recomendado)
#

Adicionar o prefab à cena

  1. No painel Project, navegue até Packages > Singular > SingularSDK > Prefabs.
  2. Arraste o prefab SingularSDKObject para o seu painel Hierarchy.
  3. O prefab está agora pronto para ser configurado no Inspector.
Método 2: Criar GameObject manualmente
#

Criação manual de GameObject

  1. No painel Hierarchy, clique com o botão direito do rato e selecione Create Empty.
  2. Dê ao GameObject o nome « SingularSDKObject » (é necessário o nome exato).
  3. Com o GameObject selecionado, navegue até ao painel Inspector.
  4. Clique em Add Component.
  5. 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

  1. Selecione SingularSDKObject: Clique no SingularSDKObject na sua Hierarquia.
  2. Localize as credenciais: inicie sessão na sua con ta Singular e navegue até Ferramentas de Desenvolvedor > Integração do SDK > Chaves do SDK.
  3. Copiar chaves: Copie a sua Chave SDK e o Segredo SDK.
  4. 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.

Opções de configuração padrã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 :
    C#
    // 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

Configuração do Referenciador de Instalação do Facebook (Meta)
#

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

  1. Selecione o SingularSDKObject na sua hierarquia de cenas.
  2. No painel Inspector, localize o campo "Facebook App ID" .
  3. 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

  1. Selecione o SingularSDKObject na hierarquia da sua cena.
  2. No painel do Inspector, desmarque Initialize On Awake.
  3. 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.

C#
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:

  1. Selecione o SingularSDKObject na hierarquia da sua cena.
  2. No painel Inspector, localize o campo Session Timeout Sec.
  3. Introduza o valor de tempo limite pretendido em segundos (por exemplo, 120 para 2 minutos).
  4. 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.

Instruções de migração: .unitypackage para UPM
#

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:

Remoção passo a passo dos ficheiros
#

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 .aar com "singular" no nome
  • Todos os ficheiros .jar com "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.xcframework pasta

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

  1. Após remover os ficheiros, feche o Unity completamente.
  2. Elimine a pasta Library no diretório do seu projeto para forçar o Unity a reimportar os recursos.
  3. Reabra o seu projeto do Unity.
  4. Aguarde até que o Unity termine de reimportar os recursos.
  5. 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.